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 layoutstring (
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.removeTooltipElement(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.
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)