Modding
This is a WIP page that I'm using to document the game's modding API as I go
Dictionary Info here
Key Terms
Dictionary
In the game every single item, object, machine, NPC, or button has a definition in the Dictionary. If there is not a definition the game will not recognise what you are trying to reference.
You can add definitions through the api_define_*() methods.
Modding Console
The Modding Console is a debugging tool available by pressing ., and it shows all messages from both the Modding API itself as well as any logs or errors from individual mods
API Reference
api_enable_dev
This turns on Dev Mode, which allows you to run commands through the in-game console
@method api_enable_dev()
@return {Nil}
Example LUA code to turn on dev mode:
api_enable_dev()
There are no associated errors with this method
@return {Nil}
api_log()
Allows you to log messages to the Modding Console
@parameter mod_name {String} - the name of your mod, the same as your mod folder, i.e. "sample_mod"
@parameter func {String} - the name of the method calling this log, shown in the console
@parameter message {String} - the message to show in the console
@return {Nil}
Example LUA code to log "Hello World!" to the Modding Console:
There are no associated errors with this method
api_define_item()
This allows you to define a new Item for the game and add it to the Dictionary
This is needed before you can spawn the item in, add it to recipes, or use it with machines.
The sprite you use needs to be a 60x16px image within your mods resources, made up of 4 frames (normal, highlighted, undiscovered, undiscovered + highlighted). The sprite will be loaded virtually and used automatically when drawing your item.
Once you've created an item with this method you'll be able to access your sprite reference with TODO if you need it during a custom draw call. You'll also be able to directly get the definition from the dictionary with TODO
@parameter mod_name {String} - the name of your mod, the same as your mod folder, i.e. "sample_mod"
@parameter definition {Table} - the item definition with the following keys:
id {String} - a unique identifier for the item. This will be prepended with "mod_name_"
name {String} - a name for the item that will be shown in tooltips
category {String} - a category for the item that will be shown in tooltips
tooltip {String} - a tooltip description for the item that will be shown in tooltips
shop_buy {Decimal} - a buying price for the item if this item was to be bought
shop_sell {Decimal} - a selling price for item if this item was to be sold
shop_key {Boolean} - whether this is a key item which means it can't be sold
machines {Array} - a list of machine this item can be used in i.e. ["workbench", "sawbench"]
durability {Integer} - if this item is a tool that gets used up you can specify a total durability here
singular {Boolean} - if true then this item will not be able to be stacked
placeable {Boolean} - whether this item can be placed - if specified you must also give an "obj" key
place_grass {Boolean} - if placeable, this specifies the item can only be placed on grass only
place_water {Boolean} - if placeable, this specifies the item can be placed on shallow water
place_deep {Boolean} - if placeable, this specifies the item can be placed on deep water
obj {String} - if placeable, this specifies the object that will be created when the item is placed. If this is not a different object id, you should be making an Object instead of an Item
honeycore {Boolean} - specifies whether this item will buy/sell for Honeycore instead of Rubees
Example LUA code to define an axe item with an ID of "sample_mod_super_axe":
item["id"] = "super_axe"
item["category"] = "Tools"
item["tooltip"] = "This is my first mod tool!"
item["shop_buy"] = 0.0
item["shop_sell"] = 0.0
item["shop_key"] = false
item["durability"] = 9999
item["name"] = "Super Axe"
def_item = api_define_item("sample_mod", item, "sample_item_sprite.png")
If there are any errors while trying to define an item you'll see one of the following codes logged in the Modding Console
This means one of the required keys above was missing from your definition parameter
Error: ID Already Defined
This means the id key provided is already in the Dictionary, either it's already used or you defined the item twice.
Error: Failed To Map Keys
This means one of your keys couldn't be mapped properly - possible a null value.
Error: Failed To Add Sprite
This means your sprite couldn't be added, either an incorrect format or file not found