InventoryUI

local InventoryUI = require("Starlit/client/ui/InventoryUI")

The InventoryUI module contains utilities related to the character inventory UI. Currently it only contains utilities for item tooltips.

Events

InventoryUI.onFillItemTooltip: LuaEvent

Triggered whenever an inventory item’s tooltip is being rendered. The Layout passed from this event is needed for most tooltip functions.

Parameters:

tooltip (ObjectTooltip) – The tooltip being filled.
layout (Layout) – The tooltip layout being filled.
item (InventoryItem) – The item the tooltip is being filled for.

Functions

InventoryUI.addTooltipLabel(layout: Layout, label: string, colour: Starlit.Colour | nil) → element: LayoutItem

Adds a label to a tooltip layout.

Parameters:

layout (Layout) – The tooltip layout
string (label) – The text to display as a label.
colour (Starlit.Colour | nil) – The colour of the text.

Returns:

element (LayoutItem) – The created tooltip element.

InventoryUI.addTooltipKeyValue(layout: Layout, key: string, value: string, keyColour: Starlit.Colour | nil, valueColour: Starlit.Colour | nil) → element: LayoutItem

Adds a key/value pair to a tooltip layout.

Parameters:

layout (Layout) – The tooltip layout.
key (string) – Key text.
value (string) – Value text.
keyColour (Starlit.Colour | nil) – Key colour.
valueColour (Starlit.Colour | nil) – Value colour.

Returns:

element (LayoutItem) – The created tooltip element.

InventoryUI.addTooltipBar(layout: Layout, label: string, amount: number, labelColour: Starlit.Colour | nil, barColour: Starlit.Colour | nil) → element: LayoutItem

Adds a progress bar to a tooltip layout.

Parameters:

layout (Layout) – The tooltip layout.
label (string) – Label text.
amount (number) – How filled the bar should be, between 0 and 1.
labelColour (Starlit.Colour | nil) – Label colour.
barColour (Starlit.Colour | nil) – Colour of the filled part of the bar. Defaults to lerping between the user’s good colour and bad colour by the amount.

Returns:

element (LayoutItem) – The created tooltip element.

InventoryUI.addTooltipInteger(layout: Layout, label: string, value: integer, highGood: boolean, labelColour: Starlit.Colour | nil) → element: LayoutItem

Adds an integer key/value to a tooltip layout. Positive values will be rendered with a plus. The value will be coloured in the user’s good colour or bad colour depending on the value of highGood. If you just want a number shown without the plus or colouration, convert your number to a string and use addTooltipKeyValue.

Parameters:

layout (Layout) – The tooltip layout.
label (string) – Label text.
value (integer) – The integer value to show.
highGood (boolean) – If true, values above zero are shown in green and values below zero are shown in red. If false, the opposite is true.
labelColour (Starlit.Colour | nil) – Label colour.

Returns:

element (LayoutItem) – The created tooltip element.

InventoryUI.getTooltipElementByLabel(layout: Layout, label: string) → item: LayoutItem | nil

Finds and returns a layout element from its label. Useful to find elements added by Vanilla or other mods.

Parameters:

layout (Layout) – The tooltip layout.
string (label) – The string label of the element.

Returns:

element (LayoutItem | nil) – The layout item.

Note

It is best practice to use getText() for the label to ensure your code works in all game languages. Most Vanilla tooltip labels add “:” to the end of the translated string; you will need to replicate this to catch them.

InventoryUI.getTooltipElementIndex(layout, element) → integer

Returns the index of the element in the tooltip layout.

Parameters:

layout (Layout) – The tooltip layout.
element (LayoutItem) – The tooltip element to get the index of.

Returns:

index (integer) – The index of the element, or -1 if the element does not belong to this layout.

InventoryUI.removeTooltipElement(layout: Layout, element: LayoutItem | integer) → LayoutItem | nil

Removes an existing tooltip element from a tooltip.

Parameters:

layout (Layout) – The tooltip layout.
element (LayoutItem | integer) – The tooltip element to remove, or the index (from the top) of the element to remove. Negative indices count from the bottom.

Returns:

element (LayoutItem | nil) – The element that was removed.

InventoryUI.moveTooltipElement(layout: Layout, element: LayoutItem, index: integer)

Moves a layout element to a specific index, shifting elements down to make room.

Parameters:

layout (Layout) – The tooltip layout.
element (LayoutItem) – The tooltip element.
index (integer) – The index to move the layout element to, counting from the top of the tooltip. Negative indices insert from the bottom up.

Examples

A basic example of using the OnFillItemTooltip event to populate a specific item’s tooltip:

-- Require the InventoryUI module so we can use it.
local InventoryUI = require("Starlit/client/ui/InventoryUI")


-- Create the event listener.
-- If your IDE supports LuaCATS annotations, the following line tells it the function is an event listener.
---@type Starlit.InventoryUI.Callback_OnFillItemTooltip
local function addAppleTooltip(tooltip, layout, item)
    -- Only run our code if the item is an apple
    if item:getFullType() ~= "Base.Apple" then
       return
    end

    -- Adds the text 'Apple.' to every apple's tooltip.
    InventoryUI.addTooltipLabel(layout, "Apple.")

    -- Adds the key-value pair "Grown at: Sweet Apple Acres" to every apple's tooltip.
    InventoryUI.addTooltipKeyValue(layout, "Grown at:", "Sweet Apple Acres")

    -- Adds a half-full progress bar for sweetness to every apple's tooltip.
    InventoryUI.addTooltipBar(layout, "Sweetness:", 0.5)

    -- Adds a bites taken counter to every apple's tooltip, with the value 1.
    InventoryUI.addTooltipInteger(layout, "Bites taken:", 1, false)

    -- Finds and returns the Vanilla tooltip element showing the item's encumbrance.
    local encumbrance = InventoryUI.getTooltipElementByLabel(layout, getText("Tooltip_item_Weight") .. ":")
    -- If encumbrance is nil, then it's already been removed by another mod.
    if encumbrance then
        -- Removes the encumbrance element.
        InventoryUI.removeTooltipElement(layout, encumbrance)
    end
end

-- Adds the event listener to the event, so that it will be called when the event is triggered.
InventoryUI.onFillItemTooltip:addListener(addAppleTooltip)