Usage

To add the library as a dependency, add the line require=\StarlitLibrary to your mod.info. The game will make sure that Starlit Library will always be enabled if your mod is, and show a warning to users if they are missing the library.

Note

In Build 41, use require=StarlitLibrary instead.

You will likely want to mark the dependency on your Steam Workshop page too. This will show a pop-up to users installing your mod encouraging them to install the library as well. Unfortunately, the in-game uploader doesn’t have a way to do this before uploading. To add a Workshop dependency, navigate to your mod’s Workshop page, click ‘Add/Remove Required Items’ in the owner panel, select the Subscribed Items tab and search for Starlit Library.

Using Modules

Starlit Library’s API is developed modularly. This means that to access the API, your Lua file must first require the module and place it into a local variable. To require a module, you must call the Lua function require(path) with the path to the file where the module is defined. Every module’s page includes sample code for requiring the module.

For example, to use the Version module to check the current version of Starlit, you must require the Version module, place it into a local variable, and then call its functions.

-- require the Version module and put it into a local variable called Version
local Version = require("Starlit/Version")

-- print the current Starlit version
print("Current Starlit Library version is " .. Version.VERSION_STRING)

-- show a warning to the player if the current version is not at least 1.4.0
Version.ensureVersion(1, 4, 0)

Using Events

Starlit Library uses a custom implementation of events for performance and API reasons. They use similar logic to Vanilla events, but their syntax is different.

event:addListener(myFunction)
event:removeListener(myFunction)

Additionally, they are not stored in a global Events table. Events are objects stored within modules, which must as always be required to be accessed.

An example of using the onFillItemTooltip event from the InventoryUI module:

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

-- create our event listener function
local function myListener()
    print("onFillItemTooltip fired!")
end

-- register the listener to the event
InventoryUI.onFillItemTooltip:addListener(myListener)

Debug Menu

The Library has its own debug menu separate from the game’s. To open the debug menu, you need to set a keybind for it in your mod options (available only in debug mode). The debug menu contains a list of separate debugging UIs, documented on the pages they are relevant to.

Intellisense

Note

If you don’t already have it, you will need [Umbrella](https://github.com/asledgehammer/Umbrella) to define the Vanilla game types. Intellisense for Starlit Library will still work without it, but its usefulness will be limited.

Starlit Library’s code is fully type annotated. To get code completion, error checking and other IDE features for Starlit modules, add the media/lua/ folder of your mod installation as a library to your IDE/Lua plugin. The process to do this is IDE specific. Only [VSCode](https://code.visualstudio.com)’s [Lua](https://marketplace.visualstudio.com/items?itemName=sumneko.lua) extension is officially supported, but it should work with any IDE that supports LuaCATS annotations.

VSCode + Lua extension

In extension settings, search for the Lua - Workspace: Library setting and add the path to the lua folder of your Starlit Library installation. For example, a typical path on Windows would be C:\Program Files (x86)\Steam\steamapps\workshop\content\108600\3378285185\mods\StarlitLibrary\42\media\lua. This may differ if your Steam library is installed to a different place, or you are not using the Steam workshop.