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.

Require: require("Starlit/client/ui/InventoryUI")

Data

Starlit.client.ui.InventoryUI.preRenderItems: starlit.LuaEvent<InventoryItem[], IsoPlayer>: Triggered before items are rendered in the inventory panel.

Function

Starlit.client.ui.InventoryUI.addTooltipBar( layout: ObjectTooltip.Layout, label: string, amount: number, labelColour?: Starlit.Colour, barColour?: Starlit.Colour ): (element: ObjectTooltip.LayoutItem)

Adds a progress bar to a tooltip layout.

Parameters:

layout (ObjectTooltip.Layout) – The tooltip layout.
label (string) – Label text.
amount (number) – How filled the bar should be, between 0 and 1.
labelColour? (Starlit.Colour) – Label colour.
barColour? (Starlit.Colour) – 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 (ObjectTooltip.LayoutItem) – The created tooltip element.

Starlit.client.ui.InventoryUI.addTooltipInteger( layout: ObjectTooltip.Layout, label: string, value: integer, highGood: boolean, labelColour?: Starlit.Colour ): (element: ObjectTooltip.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 (ObjectTooltip.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) – Label colour.

Returns:

element (ObjectTooltip.LayoutItem) – The created tooltip element.

Starlit.client.ui.InventoryUI.addTooltipKeyValue( layout: ObjectTooltip.Layout, key: string, value: string, keyColour?: Starlit.Colour, valueColour?: Starlit.Colour ): (element: ObjectTooltip.LayoutItem)

Adds a key/value pair to a tooltip layout.

Parameters:

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

Returns:

element (ObjectTooltip.LayoutItem) – The created tooltip element.

Starlit.client.ui.InventoryUI.addTooltipLabel( layout: ObjectTooltip.Layout, label: string, colour?: Starlit.Colour ): (element: ObjectTooltip.LayoutItem)

Adds a label to a tooltip layout.

Parameters:

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

Returns:

element (ObjectTooltip.LayoutItem) – The created tooltip element.

Starlit.client.ui.InventoryUI.getTooltipElementByLabel(layout: ObjectTooltip.Layout, label: string): ObjectTooltip.LayoutItem?

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

Parameters:: layout (ObjectTooltip.Layout) – The tooltip layout.

Starlit.client.ui.InventoryUI.getTooltipElementIndex( layout: ObjectTooltip.Layout, element: ObjectTooltip.LayoutItem ): (index: integer)

Returns the index of the element in the tooltip layout.

Parameters:

layout (ObjectTooltip.Layout) – The tooltip layout.
element (ObjectTooltip.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.

Starlit.client.ui.InventoryUI.moveTooltipElement( layout: ObjectTooltip.Layout, element: ObjectTooltip.LayoutItem, index: integer ): nil

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

Parameters:

layout (ObjectTooltip.Layout) – The tooltip layout.
element (ObjectTooltip.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.

Starlit.client.ui.InventoryUI.removeTooltipElement( layout: ObjectTooltip.Layout, element: (ObjectTooltip.LayoutItem | integer) ): (element?: ObjectTooltip.LayoutItem)

Removes an existing tooltip element from a tooltip.

Parameters:

layout (ObjectTooltip.Layout) – The tooltip layout.
element ((ObjectTooltip.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? (ObjectTooltip.LayoutItem) – The element that was removed.

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)

Using the preRenderItems event to dynamically change the name of an item:

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

---@type Starlit.InventoryUI.Callback_preDisplayItems
local function setAppleName(items, player)
    -- we only change the name of apples if the player has the trait
    if not player:hasTrait("AppleKnowledge") then
        return
    end

    -- Loop over every item to be rendered
    for i = 1, #items do
        local item = items[i]
        if item:getFullType() == "Base.Apple" then
            local flavour = item:getModData().flavour
            if flavour == "sweet" then
                item:setName("Sweet Apple")
            elseif flavour == "sour" then
                item:setName("Sour Apple")
            else
                item:setName("Mysterious Apple")
            end
        end
    end
end

InventoryUI.preDisplayItems:addListener(setAppleName)