Module: InventoryUI

Important

Documentation has moved to the docs. This wiki will no longer be updated, and may be deleted in the future.

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

Argument	Type	Notes
tooltip	ObjectTooltip	The tooltip being filled.
layout	Layout	The tooltip layout being filled.
item	InventoryItem	The item the tooltip is being filled for.

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

Functions

InventoryUI.addTooltipLabel(layout: Layout, label: string, colour?: Starlit.Colour)

Adds a label to a tooltip layout. The passed label will be the string displayed to the user. If no colour is passed, the default one used by most Vanilla tooltips will be used instead.

---

InventoryUI.addTooltipKeyValue(layout: Layout, key: string, value: string, keyColour?: Starlit.Colour, valueColour?: Starlit.Colour)

Adds a key : value pair to a tooltip layout. The passed key and value strings will be the string displayed to the user. If colours are not passed, the default ones used by Vanilla tooltips will be used.

---

InventoryUI.addTooltipBar(layout: Layout, label: string, amount: number, labelColour?: Starlit.Colour, barColour?: Starlit.Colour)

Adds a progress bar to a tooltip layout. The passed label will be the string displayed to the user. The amount determines what fraction of the bar will be filled, from 0 to 1. If no barColour is passed, the colour of the bar will be a mixture of the user's good colour and bad colour based on how full the bar is.

---

InventoryUI.addTooltipInteger(layout: Layout, label: string, value: integer, highGood: boolean, labelColour?: Starlit.Colour)

Adds an integer key : value pair to a tooltip layout, mimicking the style of Vanilla stat displays. The label will be the string displayed to the user. If the value is positive, it will be rendered with a plus sign.

If highGood is true, values above zero will be rendered in the user's good colour, and values below zero will be rendered in the user's bad colour. If highGood is false, the logic will be inverted.

If no labelColour is passed, the label will use the default colour used by Vanilla tooltips.

---

InventoryUI.removeTooltipElement(layout: Layout, label: string) -> item: LayoutItem?

Removes an existing element from a tooltip layout using the text of its label. The label must be the final translated string.
The removed item will be returned. If there was no item with that label, nil will be returned instead.

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.

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)

    --Removes the Vanilla encumbrance tooltip.
    InventoryUI.removeTooltipElement(layout, getText("Tooltip_item_Weight") + ":")
end

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