Modding API

From APICO Wiki
Jump to navigation Jump to search

Welcome to the API reference for APICO! This API is split up into a bunch of sections listed below, each with an overview table.

You can toggle the details of each section, which contain further information and examples, with the [Expand Details] button.

If you're looking for info on how to start making mods, check out out Getting Started section.

For any of the api_define_* methods you can check out the Sample Mod on GitHub for sprite examples.

Modding

API Reference

Section Description
Standard Datatypes LUA datatypes that are referenced in the API
Custom Datatypes Custom datatypes (LUA tables) that are referenced in the API
Hooks Custom hooks your mod can implement to react to certain game events or cycles
All Methods Methods to get all instances of specific types
Create Methods Methods to create new instances or effects
Define Methods Methods to define things like items, objects, bees, or recipes
Describe Methods Methods to describe game metadata like dictionary definitions
Draw Methods Methods to draw sprites or shapes in draw cycles
Get Methods Methods to get instances or properties
Give Methods Methods to give the player items or money
Misc Methods Misc. helper methods you may find useful
Mod Methods Methods to access and call other loaded mod methods
Set Methods Methods to set values or properties
Slot Methods Methods to help manipulate menu slots
Take Methods Methods to take currency from the player
Use Methods Methods related to using up items the player has

Datatypes, like table, are in yellow and can be clicked on for more details.
Hooks, like register(), are in blue and can also be clicked on for more details.
Methods, like api_create_log(), are in orange and can also be clicked on for more details.

Whenever we mentiond an OID we are referring to the item's unique game ID, check the OID Reference for more info.

Predictor Item.pngStandard Datatypes

These are all the standard datatypes for LUA used by the API

Datatype Description
string standard string datatype
integer standard integer datatype
decimal standard decimal datatype
boolean standard boolean datatype
list standard list/array datatype - list indices start at 1 in LUA!
table 2D array / js object-like datatype, with key-value pairs

string

This is a standard string represented by "Quotes" as in most languages.


integer

This is a standard integer


decimal

This is a standard decimal number


boolean

This is a true/false value, in these docs you will see 0 and 1 used


list

A list is simply a list of values, represented by {1,2,3}. The values inside a list can be any datatype and don't need to match each other.
In LUA, the index for lists starts at 1!!!


table

A table is like a 2D array or a JS object. You can give it any key, which can have any value, for example you could have {name="APICO"}.
A lot of the parameters either needed by the API or returned are some form of table, which we refer to as a "custom datatype"


nil

This is the null or undefined value in LUA


Microscope Item.pngCustom Datatypes

These are custom "datatypes" to help make the API clearer. In reality all of these datatypes are just table elements with different key values set that you can access with datatype["key"]

Datatype Description
bee_definition Represents a definition for a new bee
blueprint Represents a blueprint instruction for the worldgen
boundary Represents a bounding box for an instance
color Represents a custom RGB color
coordinate Represents an x/y coordinate, relative to the top-left of the world
flower_definition Represents a definition for a new flower
info Represents the help information shown on a menu
ingredient Represents an ingredient for a crafting recipe
instance Represents a generic instance, used for items, objects, buttons, gui, and menu objects
item_definition Represents a definition for a new item
layout Represents a layout of slots for a menu definition
menu_definition Represents a definition for a new menu object
npc_definition Represents a definition for a new NPC
obj_definition Represents a definition for a new object
quest_definition Represents a definition for a new quest
quest_line Represents a page of text for a quest
recipe Represents a crafting recipe for the workbench
scripts Represents a set of scripts for a menu definition
stats Represents the stats property of a slot
slot Represents a slot instance
time Represents the game time
wall_definition Represents a definition for a new wall
weather Represents the game weather
window_definition Represents a definition for a new window

bee_definition

Represents a definition for a new bee. This will add an entry into the bee book as well as give you a bee you can use and breed with.

Key Datatype Description
id string lowercase unique name for your bee, i.e. common, used for progress
title string name of your bee for tooltips + books, i.e. Common
latin string the latin name for your bee, shown in the book
hint string the hint to show in the book when this species hasn't been discovered yet
desc string the description to show in the book when this species has been discovered
lifespan list(string) a list of possible lifespan traits this species can spawn with, value options are Hyper, Rapid, Short, Normal, Long, Ancient, Eternal
productivity list(string) a list of possible productivity traits this species can spawn with, value options are Sluggish, Slowest, Slow, Normal, Fast, Fastest, Brisk
fertility list(string) a list of possible fertility traits this species can spawn with, value options are Sterile, Infertile, Unlucky, Fertile, Fecund, Prolific, Swarming
stability list(string) a list of possible stability traits this species can spawn with, value options are Chaotic, Erratic, Unstable, Normal, Stable, Ordered, Pure
behaviour list(string) a list of possible behaviour traits this species can spawn with, value options are Diurnal, Nocturnal, Crepuscular, Cathemeral
climate list(string) a list of possible climate traits this species can spawn with, value options are Temperate, Tropic, Polar, Any
rainlover boolean whether this species can work while it's raining
snowlover boolean whether this species can work while it's snowing
grumpy boolean whether this species is grumpy and needs to be calmed before being worked with
produce string the item oid of the item this species' "special produce" that will be created when frames are extracted
chance integer the chance this bee can be formed when it's the mutation for a hybrid
requirement string the requirement for how this bee can be formed when it's the mutation for a hybrid, shown in the Predictor
bid string a unique 2 character identifier for this species to use for the beebox / beebank storage. The identifier cannot be a number, i.e. 01 as these are reserved by the base game.
This must be unique across all mods, so ask your fellow modders first!
calming list(string) [Optional] if this species is grumpy, you can provide a list of flower oids that calm it, i.e. ["flower1", "flower2"] (see OID Reference)
tier integer [Optional] the tier this bee should belond to, if there is room. Should be a number between 1-5, if no room is in the given tier it'll try the next tier up until it defaults to 5

blueprint

Blueprints represent an instruction for the worldgen. Each Blueprint defines an area in the world to create a blob of land.

Key Datatype Description
width integer the width of the blueprint, which effects the blob of land created
height integer the height of the blueprint, which effects the blob of land created
x integer the y position in the world to put this blueprint
y integer the y position in the world to put this blueprint
type string the type of biome to set for this blueprint, options are "forest", "swamp", "snow", "hallow"
dye integer [Optional] set a dye to apply to the land and nature items, valid number between 1-16

boundary

Boundaries represent the bounding box for a given instance.

Key Datatype Description
top integer the top y position of the bounding box
left integer the left x position of the bounding box
bottom integer the bottom y position of the bounding box
right integer the right x position of the bounding box

color

Colors represent an RGB color that can be defined or passed through the API.

Key Datatype Description
r integer the red value of the color
g integer the green value of the color
b integer the blue value of the color

coordinate

Coordinates represent an x + y position

Key Datatype Description
x integer the x position of this co-ordinate
y integer the y position of this co-ordinate

flower_definition

Represents a definition for a new flower. Flowers can be picked up, placed, crafted with, and visited by bees.
Contrary to all other definitions, flowers defined through the API have an oid without your mod_name, so they will need to be unique across all mods.

Key Datatype Description
id string unique ID for this flower - your oid will be a combination of "flower" and your id, i.e. flower69
species string lowercase unique name for your flower, i.e. waspbane, used for progress
title string name of your flower for tooltips, i.e. Waspbane
latin string the latin name for your flower, shown in the book
hint string the hint to show in the book when this species hasn't been discovered yet
desc string the description to show in the book when this species has been discovered
aquatic boolean whether this flower can be planted / grow on shallow water
deep boolean [Optional] whether this flower can be planted / grow on deep water
shop_buy integer [Optional] the amount this flower can be bought for if sold by an NPC
shop_sell integer [Optional] the amount this flower can be sold for at an NPC
machines list(string) [Optional] a list of object oids that this flower can be used in, i.e. ["workbench", "sawmill"], shown in tooltips (see OID Reference)
tools list(string) [Optional] a list of tools that can be used on this flower, i.e. ["mouse1", "axe1"], shown in tooltips
variants integer [Optional] specifies the number of variants in your sprite image, defaults to 1
chance integer [Optional] the chance this species will be formed as a mutation, defaults to 100
smoker list(string) [Optional] a list of bee species that this flower can be used to calm in a smoker, i.e. ["stubborn"]
has_lighting boolean [Optional] if true, the flower will light up at night like Pondshine

info

Represents a list of information tooltips to use with a menu object's definition. This is the information shown when someone pressed the "Help" button for a menu.
Technically this is a list of values, hence the keys below being numbers.

Key Datatype Description
0 string the tooltip to show, i.e. 1. Input Slots
1 string the color key to use for the tooltip, valid options are GREEN, BLUE, RED, YELLOW, or WHITE

ingredient

Represents an ingredient for a recipe

Key Datatype Description
item string the item for this ingredient
amount integer the amount of this item needed for this ingredient

instance

A generic representation of any instance. All instance types have the same properties, albeit some will be nil. See Instance Properties for more specific information.

Key Datatype Description
id integer the GMS id for this instance, to use in API methods
x integer the x position of this inst
y integer the y position of this inst
oid integer the APICO "id" value used with the Dictionary - will be nil on item/slot instances (see OID Reference)
sprite_index integer the sprite image id used for this instance
image_index integer the sprite image "frame" currently set for this instance
image_xscale integer image xscale used in rendering, i.e. -1 to flip vertically
image_yscale integer image yscale used in rendering, i.e. -1 to flip horizontally
menu_id integer the menu instance for this instance - will be nil if not a menu object instance
slots list(slot) a list of slot instances - will be nil if not a menu instance

item_definition

Represents a definition for a new item. Items can be picked up, dropped, used, and crafted with.
A good in-game example of an item would be Logs

Key Datatype Description
id string id to use to create an oid for this item. Unless defining a flower, your new item oid will be a your mod_id + the item id give, i.e. "sample_mod_my_item" (be mindful of Reserved OIDs)
name string the name of this item, shown in tooltips
category string the category for this item, shown in expanded tooltips
tooltip string the tooltip message for this item, shown in expanded tooltips
shop_key boolean [Optional] whether this is a "key" item and so cannot be sold
shop_buy boolean [Optional] the amount this item can be bought for if sold by an NPC
shop_sell boolean [Optional] the amount this item can be sold for at an NPC
machines list(string) [Optional] a list of object oids that this item this can be used in, i.e. ["workbench", "sawmill"], shown in tooltips (see OID Reference)
placeable boolean [Optional] whether this item can be placed down on the ground, will use the object oid specified in "obj" if true
place_grass boolean [Optional] if placeable, this specifies if the item can only be placed on grass
place_water boolean [Optional] if placeable, this specifies if the item can only be placed on shallow water
place_deep boolean [Optional] if placeable, this specifies if the item can only be placed on deep water
singular boolean [Optional] if specified, items created with this definition will not be able to stack, like frames - you MUST give it a durability if you set this
durability boolean [Optional] if specified, items created with this definition will have a durability, like tools
obj string [Optional] if placeable, this specifies the object oid that will be created when the item is used
honeycore boolean [Optional] if true, this item will be bought + sold for honeycore instead of rubees
bee_lore string [Optional] if set, this will be used as the "lore" in the bee book if this item is a bee's special produce

layout

Represents a layout to use with a menu object's definition. This tells the game where you want the slots in relation to the menu's top left coordinate as well as what can or can't be put in that slot.
Technically this is a list of values, hence the keys below being numbers.

Key Datatype Description
0 string the x position for the slot, relative to the menu's top left coordinate
1 string the y position for the slot, relative to the menu's top left coordinate
2 string [Optional] the type of slot this is, valid options are Input, Liquid Input, Output, Liquid Output, or Shop. Output slots cannot have items put in them.
3 list(string) [Optional] if the type of slot is Input or Liquid Input, this let's you define the items that are allowed in them, i.e. ["log", "sticks1"]. You can also use some "specials" that allow any items of that same oid, namely: "seedX", "flowerX", "trackX", "dyeX", as well as "customX" (see api_define_validation_icon())

menu_definition

Represents a definition for a new menu object. Menu Objects are similar to objects but can be clicked to open a menu, like say a Sawbench.
They can be also given logic to run all the time so are a powerful tool for your mods.

Key Datatype Description
id string id to use to create an oid for this object. Your new object oid will be a your mod_id + the object id give, i.e. "sample_mod_my_object" (be mindful of Reserved OIDs)
name string the name of this object shown in tooltips
category string the category for this object, shown in expanded tooltips
tooltip string the tooltip message for this object, shown in expanded tooltips
shop_key boolean [Optional] whether this is a "key" object and so cannot be sold
shop_buy boolean [Optional] the amount this object can be bought for if sold by an NPC
shop_sell boolean [Optional] the amount this object can be sold for at an NPC
layout list(layout) a list of layouts to set the slots for this objects menu
info list(info) a list of information to show when the menu help button is pressed
buttons list(string) a list of buttons for this objects menu to have, valid options are Help, Target, Sort, Move, Close
machines list(string) [Optional] a list of object oids that this object this can be used in, i.e. ["workbench", "sawmill"], shown in tooltips (see OID Reference)
tools list(string) [Optional] a list of tools that can be used on this object, i.e. ["mouse1", "axe1"], shown in tooltips
nature boolean [Optional] this specifies if the object can only be placed on grass
aquatic boolean [Optional] this specifies if the object can only be placed on shallow water
deep boolean [Optional] this specifies if the object can only be placed on deep water
singular boolean [Optional] this specifies if the object can stack or can only be singular, like frames or bees
invisible boolean [Optional] if true, this object will not be drawn - it's bounding box will still be interactive though!
center boolean [Optional] if true, when this object's menu opens it will automatically be put in the center of the screen
item_sprite string [Optional] if you have an object that's overworld sprite is bigger than 16x16, you can use this to specify an alternate sprite to use as the item + slot sprite

npc_definition

Represents a definition for a new NPC. NPCs are basically just menu objects that move around and have a special second menu for their shop.

Key Datatype Description
id integer id to use for the npc, must be unique across all mods
name string the name of this NPC, shown in tooltips and their dialogue
pronouns string the pronouns for this NPC, shown in their dialogue
tooltip string the tooltip message for this NPC, usually just a greeting message
specials list(string) a list of at least 3 item oids that this NPC will have in it's special item pool
stock list(string) a list of up to 10 item oids that this NPC will have as it's shop stock
greeting string the default greeting message shown in the dialogue menu when it opens
dialogue list(string) a list of dialogue to show one after the other when a player clicks the "talk" button
walking boolean [Optional] whether this NPC will walk around or stay still
shop boolean [Optional] whether this NPC will have a shop or just be dialogue only

obj_definition

Represents a definition for a new object. Objects can be picked up, dropped, placed, clicked on, and crafted with.
A good in-game example of an object would be the Bench

Key Datatype Description
id string id to use to create an oid for this object. Unless defining a flower, your new object oid will be a your mod_id + the object id give, i.e. "sample_mod_my_object" (be mindful of Reserved OIDs)
name string the name of this object shown in tooltips
category string the category for this object, shown in expanded tooltips
tooltip string the tooltip message for this object, shown in expanded tooltips
shop_key boolean [Optional] whether this is a "key" object and so cannot be sold
shop_buy boolean [Optional] the amount this object can be bought for if sold by an NPC
shop_sell boolean [Optional] the amount this object can be sold for at an NPC
machines list(string) [Optional] a list of object oids that this object this can be used in, i.e. ["workbench", "sawmill"], shown in tooltips (see OID Reference)
tools list(string) [Optional] a list of tools that can be used on this object, i.e. ["mouse1", "axe1"], shown in tooltips
drops list(string) [Optional] a list of items that will be dropped when this object is chopped/mined (see "tree" or "shrub" definitions in the dictionary for examples of formatting)
place_grass boolean [Optional] this specifies if the object can only be placed on grass
place_water boolean [Optional] this specifies if the object can only be placed on shallow water
place_deep boolean [Optional] this specifies if the object can only be placed on deep water
durability boolean [Optional] if specified, objects created with this definition will have a durability, like tools (this is NOT the same as health)
hp boolean [Optional] if specified, object created will have health, likes trees (this is NOT the same as durability)
singular boolean [Optional] if specified, objects created with this definition will not be able to stack, like frames
honeycore boolean [Optional] if true, this objects will be bought + sold for honeycore instead of rubees
invisible boolean [Optional] if true, this object will not be drawn - it's bounding box will still be interactive though!
bed boolean [Optional] if true, this object will act as a bed when clicked
bench boolean [Optional] if true, this object will act as a bench when clicked
has_lighting boolean [Optional] if true, this object will light up at night
has_shadow boolean [Optional] if true, a shadow will be automatically drawn under this object
pickable boolean [Optional] if true, you'll be able to pick up this item with the mouse
variants integer [Optional] for nature objects, like trees, this specifies the amount of variants within the sprite for the object
growth string [Optional] if set, after the object is created a timer will start, after which a new object will be created instead, for example saplings in the game use "tree 360 560" to make a tree randomly after 360-560 seconds
item_sprite string [Optional] if you have an object that's overworld sprite is bigger than 16x16, you can use this to specify an alternate sprite to use as the item + slot sprite

quest_definition

Represents a quest definition to make a new quest in the book.

Key Datatype Description
id string the unique id for your quest, for use with the progress handler
title string the title of your quest as shown in the book chapter list
reqs list(string) the requirements needed for the quest to be ready, e.g. ["axe1@2"] would mean 2 wooden axes are needed to complete
icon string the item oid of the item to use for the icon in the overview section of the book (see OID Reference)
reward string the reward that will be given when the quest is handed in, e.g. "honeycore1@10" would give 10 honeycore crystals
unlock list(string) a list of quests ids to unlock when this quest is complete

quest_line

Represents a line in a page of a quest, along with any text or images you want to show.

Key Datatype Description
text string the text for this line
color string [Optional] the color key for the text, defaults to "FONT_BOOK"
gif string [Optional] instead of text you can show a sprite by specifying the oid of the sprite. The sprite should have a width of 148 pixels and a height of either 46, 66, or 86 pixels.
width integer [Optional] if a gif is specified this sets the height of the gif, should be 46, 66, or 86

recipe

Represents a crafting recipe for the workbench.

Key Datatype Description
item string the item oid that this recipe will craft (see OID Reference)
recipe list(ingredient) the ingredients to use for this recipe
total integer [Optional] the total amount of the item you get when crafted, defaults to 1

scripts

Represents a set of script definitions to use when defining a custom menu object. Each script must be a valid function found in your mod.lua file.

Key Datatype Description
define string a script to run when the menu object is first defined, allowing you to set custom properties and stuff
change string a script to run when a slot inside the menu object gets changed
tick string a script to run every tick (0.1s) for that menu object, as long as it's active
draw string a script to run every draw cycle for this menu object, only when the object's menu is actually open

stats

All slots + items have a stats property that is used for certain items that need to store specific extra properties - this is used for all bee "items", but also for canisters and frames.
For bees, you can find the following properties from the stats property:

Key Datatype Description
species string the dominant species for the bee, i.e. common
queen string whether this bee is a queen or not
beetrice boolean whether this bee is a descendent of beetrice - the first bee you get from the book
microscoped boolean whether a bee has been microscoped (so people can't microscope the same bee 3 times)
shiny boolean whether this bee is a blessed variant
d_traits table this table contains a key for every bee trait with the bee's dominant value for that trait, keys included any custom defined traits through api_define_trait() as well as the following standard traits: species, lifespan, productivity, fertility, behaviour, climate, stability, pluvioplhile, chionophile and aggressive. Dominent traits are what determines how the bee acts in beehives.
r_traits table this table contains a key for every bee trait with the bee's recessive value for that trait, keys included any custom defined traits through api_define_trait() as well as the following standard traits: species, lifespan, productivity, fertility, behaviour, climate, stability, pluvioplhile, chionophile and aggressive.

For canisters, you can find the following properties from the stats property:

Key Datatype Description
type string the type of liquid in the canister, can be an empty string if empty or one of the following: water, resin, honey, or mead
amount integer the current amount in the canister
max integer the max amount this canister can hold

For frames, you can find the following properties from the stats property:

Key Datatype Description
filled boolean whether the frame has been filled from a hive
uncapped boolean whether the frame has been uncapped
flowers string a comma-separated list of flowers the bees who filled this frame visited
species string the species of bee that filled this frame
productivity string the dominant productivity trait value of the bee that filled this frame

slot

Represents a slot instance that is part of a parent menu. Slots can be blank or hold items in them.

Key Datatype Description
id integer the GMS id for this instance, to use in API methods
index integer the index of this slot within a menu based on the menu layout, starting at 1
item string if this slot holds an item, this will be the item oid, otherwise it'll be blank, i.e. "" (see OID Reference)
count integer if this slot holds a non-singular item, this will store the count of the slot
current_health integer if this slot holds an item with durability, this will be the current durability amount
total_health integer if this slot holds an item with durability, this will be the full durability amount
stats stats used by frames, canisters and bees (or anything you might have set manually)

time

Represents the current game time when retrieved through api_get_time.
Dawn starts at 3am and ends at 7am. Dusk starts at 5pm and ends at 9pm.

Key Datatype Description
time integer the current time in the day, in ms. This is a number from 0 - 1440000.
One hour in-game is 60000ms, or 1 minute.
day integer the current day that the player is on
name string the "name" for the time of day, either Day, Dawn, Dusk, or Night
clock string the current "clock" for the time of day, i.e. 12:04

wall_definition

Represents a definition for a new wall. Walls can be placed down and picked up with a hammer.

Key Datatype Description
id string id to use to create an oid for this item, must be unique across all mods (i.e. wall90001)
name string the name of this item, shown in tooltips
shop_buy boolean [Optional] the amount this item can be bought for if sold by an NPC
shop_sell boolean [Optional] the amount this item can be sold for at an NPC

window_definition

Represents a definition for a new window. Windows can be placed on walls and picked up with a hammer.

Key Datatype Description
id string id to use to create an oid for this item, must be unique across all mods (i.e. window90001)
name string the name of this item, shown in tooltips
shop_buy boolean [Optional] the amount this item can be bought for if sold by an NPC
shop_sell boolean [Optional] the amount this item can be sold for at an NPC

weather

Represents the current weather when retrieved through api_get_weather. Weather is simply either on or off - the weather effects shown are based on the biome the player is currently in.
Weather is decided at the start of a new day, with a 30% chance every day after Day 4 (or 100% chance if currently in a swamp biome)

Key Datatype Description
active boolean whether weather is current "on" or not
start_time integer the time weather will start today, in ms
end_time integer the time weather will end today, in ms

Standard Boat Item.pngHooks

Hooks are special functions that allow you to hook into different processes as well as let you actually register and setup your mod. When you register your mod you can specify the hooks you want to apply.
Both register() and init() are required for your mod to run.
You can only have one function for each hook (i.e. you can't have two "click()" hooks).

Hook Description
click() this hook is called whenever the player clicks on something with the mouse (or uses "action" on a gamepad)
clock() this hook is called every 1s of real-time
create() this hook is a called whenever an object (tree, flower, generic object, menu object) or item is created
data() this hook is a callback used whenever you call api_get_data() or api_set_data() due to file load being async
destroy() this hook is a called whenever an object (tree, flower, generic object, menu object) is destroyed
draw() this hook is called every draw cycle, on the overworld layer (above objects)
gui() this hook is called every draw cycle, on the gui layer
http() this hook is called when a HTTP response is returned from api_http_request()
init() this hook is called when the mod is first initialised, allowing you to setup mod code for the first time
key() this hook is called whenever a key is pressed
pdraw() this hook is called every draw cycle, on the player layer
ready() this hook is called when all mods have been both registered and initialised and after all objects are loaded in
register() this hook is called first to register the mod with a unique name and setup required hooks
save() this hook is called whenever the player saves or the autosave is called
scroll() this hook is called when the mouse wheel is scrolled
tdraw() this hook is called every draw cycle, on the overworld layer (above tiles but below objects)
tick() this hook is called ever 0.1s of real time
worldgen() this hook is called after the initial world generation is complete but the world hasn't been fully processed, letting you add to the world

click()

This hook is called whenever a player clicks on something with the mouse or uses the "action" button on their gamepad. You can find out what key was pressed with the api_get_key_down() or api_get_key_pressed() methods.
As this is a single hook for the whole mod you'll probably want to split out the calls within this method to other modules to keep things manageable.

This hook is called with the following parameters:

Parameter Datatype Description
button string the button of the mouse, will be LEFT, RIGHT or MIDDLE
click_type string the type of click, will be PRESSED or RELEASED,

Example code to do something if a player clicks on a tree:

function click()

  highlighted = api_get_highlighted("obj")
  if highlighted ~= nil then
    inst = api_get_inst(highlighted)
    if inst["oid"] == true then
      -- do something with the trees
    end
  end
end

clock()

This hook is called every 1s of real time by the game. You can use this to handle any general time related logic you need.

Example code to give the player 1 log every second:

function clock()
  api_give_item("log", 1)
end

create()

This hook is called whenever an item, tree, flower, generic object, or menu object is destroyed. This will happen for all created items so be sure to be filtering out your logic by specific oid / type!
As items can be picked up sometimes immedietely you should be careful on modifying items through this hook as the item may already have been destroyed (i.e. picked up)

Parameter Datatype Description
id integer the instance id of the inst that just got destroyed
x integer the x position of the inst that just go destroyed
y integer the y position of the inst that just go destroyed
oid string the oid of the inst that just go destroyed (see OID Reference)
inst_type string the "type" of inst created, can be one of the following: tree, flower, obj, menu_obj, or item

Example code to drop a custom item whenever a tree is chopped down:

function create(id, x, y, oid, inst_type) 

  -- whenever a tree is created (i.e. growing from a sapling)
  -- turn it into skipper
  if oid == "tree" and inst_type == "tree" then
    api_create_obj("npc1", x, y)
    api_destroy_inst(id)
  end

end

data()

This hook is called whenever you call the api_get_data() or api_set_data() methods, as file loading is asynchronous.
Each mod has it's own dedicated JSON file that you can read and write to through the API to avoid direct file access.

Parameter Datatype Description
ev string the type of data event, either SAVE or LOAD depending on which method you used
data string or table if a SAVE type, will return Success, otherwise if a LOAD type this parameter will contain your JSON file data as a table

Example code to load the mod datafile during init() and access the data:

function init()
  -- get our data file
  api_get_data()
end

function data(ev, data)
  if ev == "LOAD" and data ~= nil then
    -- do something with our data
    val = data["value"]
  end
end

destroy()

This hook is called whenever a tree, flower, generic object, or menu object is destroyed.
While you will be passed the instance ID of the instance destroyed, this instance will no longer exist so you cannot use methods like api_get_data() or api_set_data().

Parameter Datatype Description
id integer the instance id of the inst that just got destroyed
x integer the x position of the inst that just go destroyed
y integer the y position of the inst that just go destroyed
oid string the oid of the inst that just go destroyed (see OID Reference)

Example code to drop a custom item whenever a tree is chopped down:

function destroy(id, x, y, oid) 

  -- if tree was destroyed, drop an item
  if oid == "tree" then
    api_create_item("my_new_obj", 10, x, y)
  end

end

draw()

This hook is called every in-game draw cycle. This hook allows you to use the various Draw Methods to draw stuff every cycle.
This hook will draw items to the overworld layer - if you want to draw ontop of menus / UI you'll need to use the gui() hook instead.

Example code to draw some text above the player:

function draw()

  -- get position
  player_pos = api_get_player_position()
  cam_pos = api_get_cam()
  px = player_pos["x"] - cam_pos["x"]
  py = player_pos["y"] - cam_pos["y"]

  -- draw some text
  api_draw_text(px, py, "Hello World!", true)

end

gui()

This hook is called every in-game draw cycle and, like draw() hook, this hook allows you to use the various Draw Methods to draw stuff every cycle.
This hook will draw items to the GUI layer on top of everything else. If you want to draw underneath menus you need to use draw() instead.

Example code to draw a black circle on top of everything:

function gui()

  -- get position
  cam_pos = api_get_cam()
  px = player_pos["x"] - cam_pos["x"]
  py = player_pos["y"] - cam_pos["y"]

  -- draw a circle
  api_draw_circle(px, py, 100, false, "BLACK")
  
end

http()

This hook is called every time a HTTP response is returned by api_http_request().
This hook returns regardless of whether the HTTP request succeeded or failed.

Parameter Datatype Description
response_id string the string you set in your api_http_request() method to help you identify the callback
status string returns either "Success" or "Error" depending on the HTTP status returned
response string response body returned from the HTTP request

Example code to handle some random HTTP call to get the APICO website homepage:

-- call our HTTP req whereever we like
function init()
  api_http_request("https://apico.buzz", "GET", {}, "", "my_request")
  return "Success"
end

-- http requests are async so you'll need the http() hook to handle the response
function http(response_id, status, response)

  -- check the response_id and status before handling the response body
  if response_id == "my_request" and status == "Success" then
    api_log("http", response)
  end
  
end

init()

An extremely important and required hook which is called after your mod is registered. This is a chance for you to setup anything you need for your mod straight away, like defining different items and objects or setting up mod globals.
If your mod doesn't have an init() hook it will not be loaded.
This hook is called before any mod objects might be loaded so you should use ready() if you want to get any mod objects that might have been saved.

Your init() hook should return Success if things went well, or an error message to be shown in the Modding Console.

Example code to define a global color when the mod is initialised:

global_color = 0

function init()

  -- create a new color, if it fails return an error so the mod load is aborted
  global_loaded = api_define_color("super_green", {r=0,b=0,g=255})
  if global_loaded == nil then return "Error: Couldn't create custom color" end

  -- otherwise if all was a success tell the game we're good so it carries on loading our mod
  return "Success"

end

key()

This hook is called whenever a key is pressed. You can use api_get_key_down or api_get_key_pressed to find out what key/s are being pressed.

Parameter Datatype Description
key_code integer the keycode of the key that was pressed to trigger this event

Example code to run an action when the player presses the spacebar:

function key(key_code)
  if key_code == 32 then 
    -- spacebar has been pressed!
  end
end

pdraw()

This hook is called every in-game draw cycle. This hook allows you to use the various Draw Methods to draw stuff every cycle.
This hook will draw items to the player layer - this means anything you draw will be on top of the player but at the correct depth (behind trees/walls etc).

Example code to draw some text above the player:

function draw()

  -- get position 
  -- note we dont need to add the camera offset as we are calling this hook from the players own draw cycle
  player_pos = api_get_player_position()
  px = player_pos["x"]
  py = player_pos["y"]

  -- draw some text
  api_draw_text(px, py, "Player Name!", true)

end

ready()

This hook is called when all mods have been both registered and initialised. If your mod relies on another mod or just wants to know when everything is ready then it can listen for this event.
This event is called after all world objects are loaded in, including mod objects, and is called right as the player is able to control themselves.

Example code to run a function from another mod after all mods have loaded:

function ready()
  -- check mod exists first
  if api_mod_exists("my_other_mod") then
    -- call a method from the other mod
    api_mod_call("my_other_mod", "some_method", {"param1", "param2"})
  end
end

register()

This is the most important hook as it's called first by the game to register your mod and setup the hooks you want. KISS with this one, don't put any other logic in this method - save that for init() or ready().

Your register() hook should return a table with the following values:

Parameter Datatype Description
name string the unique name of your mod
hooks list(string) a list of hooks you want your mod to subscribe too, i.e. {"click", "clock"}. You do not need to specify "register" or "init" as they are required.
modules list(string) a list of "modules" you want your mod to load. These should be the names of .lua files within a folder called "modules" at the root of your mod. All mod files will be loaded into one single file so any scripts or globals in each file will be accessible from each other.

Example code to register "sample_mod" and subscribe to the clock() and tick() hooks

function register() 
  return {
    name = "sample_mod",
    hooks = {"clock", "tick"},
    modules = {"define"} -- will load /modules/define.lua (if it exists)
  }
end

save()

This hook is called whenever the player manually saves or the game autosaves, to give you a chance to save your mod file if you need to.

Example code to update the mod datafile when the game saves:

-- fake mod data table
global_data = {
  data = "my data",
  times_saved = 0
}

-- hook into the save event
function save() 
  -- log to the console to check that save is called
  api_log("save", "Save called!")

  -- increment a value and save new data
  global_data["times_saved"] = global_data["times_saved"] + 1
  api_set_data(global_data)
end

-- handle the async callback
function data(ev, data)
  if ev == "SAVE" and data ~= nil then
    api_log("save", "Save complete!")
  end
end

scroll()

This hook is called whenever the mouse wheel is scrolled

Parameter Datatype Description
direction string either UP or DOWN
inverse boolean whether the player has set inverse scroll in their settings

Example code to affect some drawing offset with the scroll:

SCROLL_Y = 0

-- handle scroll
function scroll(direction, inverse)
  if direction == "UP" then
    SCROLL_Y = SCROLL_Y + 1
  else
    SCROLL_Y = SCROLL_Y - 1
  end
end

-- draw a circle at the player position, offset by the scroll amount
function draw() 
  cam = api_get_camera_position()
  player = api_get_player_position()
  px = player["x"] - cam["x"]
  py = player["y"] - cam["y"]
  api_draw_circle(px, py + SCROLL_Y, 100, "FONT_RED", false)
end

tdraw()

This hook is called every in-game draw cycle. This hook allows you to use the various Draw Methods to draw stuff every cycle.
This hook is similar to draw() except it will draw things underneath the object layer (i.e. for drawing fake tiles).

Example code to draw a circle that will be below objects/walls:

function tdraw()

  -- get position
  player_pos = api_get_player_position()
  cam_pos = api_get_cam()
  px = player_pos["x"] - cam_pos["x"]
  py = player_pos["y"] - cam_pos["y"]

  -- draw a circle
  api_draw_circle(px, py, 100, "FONT_RED", false)

end

tick()

This hook is called every 0.1 of real time, enabling you to handle things that need to happy more often and update quickly rather than wait for every second in clock().
Please check the logic you are running in this hook along with the FPS meter to ensure you are not starting to reduce performance!

Do not leave api_create_log() calls in this method!!!

Example code to update a counter every tick:

global_count = 0

-- after 10 seconds the count would be 100
function tick()
  global_count = global_count + 1
end

step()

This hook is called every frame, which in GameMaker (locked at 60fps) will mean it's called every 1/60s. This hook let's you handle things that need to be updated due to them being something visual - the position of a custom object as you move for example. If you just used tick() you would see a slight lag as it's not being updated at the same FPS.
Please check the logic you are running in this hook along with the FPS meter to ensure you are not starting to reduce performance!

Do not leave api_create_log() calls in this method!!!

Example code to update a counter every frame:

global_count = 0

-- after 10 seconds the count would be 600
function step()
  global_count = global_count + 1
end

worldgen()

This hook is called twice - firstly after the initial world generation is complete (land blobs have been placed by the blueprint but objects have not been created yet), the secondly after all objects have been created. This gives you a chance to alter the ground or add structures, generate your own objects if you set the blueprint to be blank with api_set_blueprint(), or "replace" existing objects in the world.
For reference, game worlds are 350x350 tiles, with 290x290 being visible on the map and rest being reserved for secret areas.

Parameter Datatype Description
before_objects boolean as the hook is called twice, this bool tells you if this is the pre-object call or post-object call

Example code to change the player's start position when the world is created:

function worldgen(before_objects)

  -- after tiles set, change some tiles!
  if before_objects then

    -- loop through all world tiles
    for x=0,290 do
      for y=0, 290 do
        -- do something with this tile
        ground = api_get_ground(x*16, y*16)
      end
    end
  
    -- move the player to a different start position
    api_set_player_position(100, 200)

  -- after objects set, change some objs!
  else

    -- replace some trees with our own fake trees (1% chance)
    all_trees = api_all_trees()
    for t=1,#all_trees do
      if api_random(100) < 1 then
        api_create_obj("sample_mod_fake_tree", api_gp(all_trees[t], "x"), api_gp(all_trees[t], "y"))
        api_destroy_inst(all_trees[t])
      end
    end

  end

end

Barrel Item.pngAll Methods

All methods allow you to get all instances of a given type regardless of where they are in the world (both active and inactive). They should be used extremely sparingly, as they cause all objects to be momentarily activated!
Do NOT use these in tick()/clock() hooks

Method Description
api_all_flowers() returns a list of all flower instance ids in the world
api_all_trees() returns a list of all tree instance ids in the world
api_all_menu_objects() returns a list of all menu object instance ids in the world
api_all_objects() returns a list of all generic object instance ids in the world

api_all_flowers()

This method returns the IDs of all flowers in the world, regardless of whether they are onscreen or not.

Parameter Datatype Description
oid string filter results to a specific oid (ideally you should always provide a filter) (see OID Reference)

This method will return a list of integers for each instance ID, which you can then use with other methods.

Example code to get all Honeyrose flowers in the world and then DESTROY THEM:

-- remove all flowers
-- i dont know why you'd want to do this either, maybe you just dont like the color red
flowers = api_all_flowers("flower1")
for i=1,#flowers do
  api_destroy_inst(flowers[i])
end

api_all_trees()

This method returns the IDs of all trees in the world, regardless of whether they are onscreen or not.

This method will return a list of integers for each instance ID, which you can then use with other methods.

Example code to get all trees in the world and turn 10% of them into Skipper:

-- turn 10% of all trees into skipper
-- yes this hangs for a bit, what did you expect lol
trees = api_all_trees()
for i=1,#trees do
  if api_random(100) < 10 then

    -- turn tree into skipper
    api_create_obj("npc1", api_gp(trees[i], "x"), api_gp(trees[i], "y"))
    api_destroy_inst(trees[i])

  end
end

api_all_menu_objects()

This method returns the IDs of all menu objects (machines, beehives, npcs etc) in the world, regardless of whether they are working or not.

Parameter Datatype Description
oid string filter results to a specific oid (ideally you should always provide a filter) (see OID Reference)

This method will return a list of integers for each instance ID, which you can then use with other methods.

Example code to get all the Skippers in the world, and then duplicate them:

-- infinity skippers
skippers = api_all_menu_objects("npc1")
for i=1,#skippers do
  -- make a new skipper for each skipper
  api_create_obj("npc1", 
    api_gp(skippers[i], "x") + api_random_range(-8, 8), 
    api_gp(skippers[i], "y") + api_random_range(-8, 8)
  )
end

api_all_objects()

This method returns the IDs of all generic objects (rocks, shrubs, benches etc) in the world, regardless of whether they are onscreen or not.

Parameter Datatype Description
oid string filter results to a specific oid (ideally you should always provide a filter) (see OID Reference)

This method will return a list of integers for each instance ID, which you can then use with other methods.

Example code to get all rocks in the world and turn them into Honeycore:

-- turn all rocks into honeycore
-- dont come crying to me when you inevitably bork your saves
objs = api_all_objects("rock1")
for i=1,#objs do
  api_create_obj("honeycore1", api_gp(objs[i], "x"), api_gp(objs[i], "y"))
  api_destroy_inst(objs[i])
end

Logs Item.pngCreate Methods

Create methods allow you to create something, either an instance, a particle effect, or a timer.

Method Description
api_create_bee_stats() creates a stats for a bee for a given species
api_create_counter() creates a custom counter to iterate through values in a loop
api_create_effect() creates a special effect at a given position
api_create_item() creates an item at a given position
api_create_log() api_log() creates a log in the Modding Console (opened with CTRL+.)
api_create_obj() creates an object or menu object at a given position
api_create_timer() creates a custom timer to callback after x seconds

api_create_bee_stats()

A bee is just a fancy item with a bunch of stats assigned, you've probably seen the stats returned in a slot's properties! This method lets you create a bee stat obj by passing a species.
The traits will be picked at random from those available in the bee definition, like naturally spawned bees + mutations do.

Parameter Datatype Description
species integer the species of the bee to create stats for
queen boolean whether to make this a queen bee or not

Example code to spawn a bee item for a given species:

-- create stats
stats = api_create_bee_stats("common", false)

-- create item
api_create_item("bee", 1, 100, 100, stats)

api_create_counter()

This lets you create a custom counter that will iterate through a range of numbers in set increments at the interval specified. This can be used to make stuff like frame counters for animations.

Parameter Datatype Description
key integer the unique name to give this counter, this will be unique per mod so you don't have to worry about clashing with other mods
interval integer the interval in seconds to increment the counter
start_val integer the value to start the counter at, and reset too when the end_val is reached
end_val integer the max number for the counter, after which it'll reset to the start_val
increment integer the amount to increment by each interval

Example code to create a custom counter that goes from 0 - 100 in increments of 25

function init() 
  -- counter counts every 1s from 0-100, in intervals of 25, then resets back to 0
  api_create_counter("counter", 1, 0, 100, 25)
  return "Success"
end
function clock()
  -- log would give you 0, 25, 50, 75, 100, then back to 0
  api_log("clock", api_get_counter("counter"))
end

api_create_effect()

This lets you create a special particle effect at a given position. All particle types are just variations of speed and direction, most should be obvious what they are or where they're used in the vanilla game to see them in action.
With the exception of BEE_QUEEN, BEE_PFX, NOTE_1, and NOTE_2, all particles are just a single pixel size.

Parameter Datatype Description
px integer the x position to create the particle at
py integer the y position to create the particle at
ptype string the particle type to create, options are: DUST_RIGHT, DUST_LEFT, DUST_DOWN, TREE_LEAVES, TREE_GROWTH, PAINT_GROWTH, GATE_GROWTH, BEE_PFX, ROCK_GROWTH, STEP_RIGHT, STEP_LEFT, BREATH_RIGHT, BREATH_LEFT, BEE_TRAIL, FLOWER_POLLEN, BEE_QUEEN, BEE_CONFETTI, EXTRACT_DUST, RAIN_DROP, SNOW_DROP, RESIN_DROP, SMOKE_PUFF, STEP_SNOW, CHILL_PUFF, MEAD_BUFF, NOTE_1, or NOTE_2
amount integer the number of particles to create
amount integer the color key of particles to create, i.e. FONT_BLUE

Example code to create 50 blue confetti type particles on the player's location:

function draw()
  -- get position of the player
  player_pos = api_get_player_position()
  px = player_pos["x"] - camera_pos["x"]
  py = player_pos["y"] - camera_pos["y"]
  
  -- create particles
  api_create_effect(px, py, "BEE_CONFETTI", 50, "FONT_BLUE")
end

api_create_item()

This lets you create an already defined item at a specific position. If you want to define a new item you need to use api_define_item()

Parameter Datatype Description
item string the item oid of the item you want to create (see OID Reference)
count integer the number of the item to create
x integer the x position to create the item at
y integer the y position to create the item at
stats stats [Optional] a stats obj to use, can be one you got from api_create_bee_stats() or a custom one

This will return either the newly created object item id as a integer else it will return nil if it failed.

Example code to create 50 logs near the player:

-- get position of the player
player_pos = api_get_player_position()

-- create item
api_create_item("log", 50, player_pos["x"] - 32, player_pos["y"] + 48)

api_create_log()

Your new best friend! This logs something to the Modding Console, which you can toggle with CTRL+.. Each log is shown broken down into the mod name, the group, and then the message.
You can also use a shorthand of "api_log()".

Parameter Datatype Description
ident string an identifier for the log to help you identify message
msg string the message to log

Example code to create a log saying hello:

api_log("test_log", "Hello World!")

api_create_obj()

This lets you create an already defined object / menu object at a specific position. If you want to define a new object you need to use api_define_object() or api_define_menu_object().

Parameter Datatype Description
oid string the object oid of the object you want to create (see OID Reference)
x integer the x position to create the object at
y integer the y position to create the object at

For some reason that is completely beyond me this function will always return nil and I don't know why, soz :(

Example code to create a workbench next to the player:

-- get position of the player
player_pos = api_get_player_position()
  
-- create object
api_create_obj("workbench", player_pos["x"] + 8, player_pos["y"] - 16)

api_create_timer()

This lets you create a custom timer, which will count down in seconds before returning a callback to a function you've defined in your mod.

Parameter Datatype Description
method string the function you want to call when the timer ends
seconds integer the amount of time you want to wait
arg1 Any [Optional] an argument to pass into the callback
arg2 Any [Optional] an argument to pass into the callback
arg3 Any [Optional] an argument to pass into the callback
-- create timer in init
function init()
  api_create_log("timer_start", "Timer created!")
  api_create_timer("my_callback", 10, "World!")
end

-- function to callback to
function my_callback(arg1)
  api_create_log("timer_start", "Timer called!")
  api_create_log("timer_start", "Hello " .. arg1)
end


Book1 Item.pngDefine Methods

Define methods let you define new types of things, whether it's instances or colors or recipes. For any define methods that need sprites, you can check the Sample Mod project to see examples of the sprites needed.

Method Description
api_define_bee() defines a new species of bee for the game
api_define_bee_recipe() defines a custom bee "recipe" for hybrids, along with a mutation script to check criteria
api_define_button() defines a custom button to be used with a menu object
api_define_color() defines a custom color to use in draw calls
api_define_command() defines a custom command to use in the In-Game Console
api_define_flower() defines a new species of flower for the game
api_define_flower_recipe() defines a new species of flower for the game
api_define_gif()) defines a custom "gif" sprite to use custom quests
api_define_gui() defines a custom gui (hoverable visual element) to be used with a menu object
api_define_item() defines a new item for the game like Logs or Planks
api_define_item_stats() defines the default "stats" an item will get created with
api_define_liquid() defines a custom liquid to use in barrels, canisters, or your own menu object tanks
api_define_menu_object() defines a new menu object for the game like a Workbench or a Beehive
api_define_notification() defines a new notification type along with a dismiss script for when it's clicked
api_define_npc() defines a custom npc with dialogue and optionally a shop
api_define_object() defines a new object for the game like a Bench or a Statue
api_define_property() api_dp defines a new property on a given instance
api_define_quest() defines a new quest for the game, shown in the guide
api_define_recipe() defines a new recipe for the Mod Workbench
api_define_sprite() defines a custom sprite to use in draw calls
api_define_tank() defines a custom liquid storage tank for a menu
api_define_trait() defines a custom trait to apply to all bees going forward
api_define_validation_icon() defines a custom validation icon for "customX" slot validation with layout's
api_define_wall() defines a custom wall
api_define_window() defines a custom window
api_define_workbench() defines the mod and tab labels shown in the Mod Workbench

api_define_bee()

The one you've all been waiting for! This let's you define your own custom bee species and add it to the game. The species name and bid (both not shown to the player) must be unique across all mods, so play nicely and check in with what other people are doing!

Parameter Datatype Description
bee_def bee_definition the bee definition to be used to create the new species
bee_sprite_image string relative path of the sprite you want to use for the bee item, should be a 72x18 image with 4 frames (normal, normal highlighted, undiscovered, undiscovered highlight)
bee_shiny_image string relative path of the sprite you want to use for the shiny variant, should be a 380x18 image with 20 frames for a shine animation
bee_hd_image string relative path of the sprite you want to use for the "HD" bee image in the book, should be a 96x48 image with 2 frames (normal, undiscovered)
bee_color color a color to use for the bee, used in the book, predictor, and the discovery popup
bee_mag_image string relative path of the sprite you want to use for the bee's news magazine item, should be a 32x16 image with 2 frames (normal, highlighted)
bee_mag_headline string headline text to use in the news magazine popup
bee_mag_body string body text to use in the news magazine popup

If this method worked it will return Success, otherwise if it fails it will return nil and will log an error in the Modding Console with one of the following errors:

Error Description
Missing Required Key a required key was missing from the definition
Bee With This ID Exists a bee with this id is already defined
Bee Produce Item Not Defined the special produce defined is not a valid item
BID Chars Cannot Both Be Numeric a bid must be two characters, but both can't be numbers
Bee Sprites Not Found the sprite paths given were not found
Failed To Map Keys general catch all that for the method, check your parameters + definition

Example code to create a new species of bee:

-- setup bee_definition 
bee_def = {
  id = "nightcrawler",
  title = "Nightcrawler",
  latin = "Crawly Nighty",
  hint = "Found on only the darkest of nights",
  desc = "This is just a cool damn bee",
  lifespan = {"Normal"},
  productivity = {"Normal", "Fast"},
  fertility = {"Fecund", "Prolific"},
  stability = {"Normal", "Stable"},
  behaviour = {"Nocturnal"},
  climate = {"Temperate"},
  rainlover = false,
  snowlover = false,
  grumpy = true,
  produce = "log",
  recipes = {
    { a = "nightcrawler", b = "dream", s = "chaotic" }
  },
  calming = {"flower10", "flower11"},
  chance = 100,
  bid = "X3",
  requirement = ""
}

-- create new bee
-- in this example we have a "sprites" folder in our mod root
api_define_bee(bee_def, 
  "sprites/bee_item.png", "sprites/bee_shiny.png", 
  "sprites/bee_hd.png",
  {r=100, g=100, b=100},
  "sprites/bee_mag.png",
  "This is a headline!",
  "This is the body!"
);

api_define_bee_recipe()

This allows you to define a custom bee "recipe" that lets you specify a hybrid combination along with the criteria for it. Each bee can have up to 3 recipes (as they are shown in the book), and the bees in the recipe need to be defined before calling this method if you are using custom bees.
In mutation land, common-forest is the same as forest-common so it doesn't matter which order you set below.

Parameter Datatype Description
species_a string one of the two bees this hybrid needs - recipe will be added to both bee definitions
species_b string the other bee this hybrid needs - recipe will be added to both bee definitions
species_s string the species that will be formed if a mutation occurs
mutation_script string a mutation check script that will be called if a hybrid between species a + species b finishes it's lifespan. This let's you decide any extra criteria needed for the mutation to occur - must be defined in your mod

If this method worked it will return Success, otherwise if it fails it will return nil and will log an error in the Modding Console with one of the following errors:

Error Description
Bee/s Already Has 3 Recipes species_a or species_b already has 3 recipes defined
Species Given Are Not Defined one of the 3 species parameters are not defined bee species

Example code to create new recipe between Verge and Dream bees to make Ancient bees if the player has enough money:

function init() 

  -- define new menu object
  api_define_bee_recipe("verge", "dream", "ancient", "mutation_chance")

  -- give money
  api_give_money(1000)

  return "Success"
end

-- the chance method should return true or false
-- if the method returns true a mutation will occur so you need to consider "chance" yourself
-- bee_a will be the dominant species of the hybrid offspring, bee_b will be the recessive species
-- beehive will be the menu_obj inst id of the beehive the offspring are being created in
function mutation_chance(bee_a, bee_b, beehive)

  -- script can be reused for multiple mutations so check the combo we want
  if (bee_a == "verge" and bee_b == "dream") or (bee_a == "dream" and bee_b == "verge") then

    -- if player has 1000 money and 50% chance
    money = api_gp(api_get_player_instance(), "money")
    chance = api_random(99) + 1
    if chance >= 50 and money >= 1000 then return true end

  end

  return false
end

api_define_button()

This allows you to define a custom button that can be used with a menu object and clicked to run a function from your mod.

Parameter Datatype Description
menu_id integer the menu object instance id you want to define attach the button to
button_key string the name of the key you want to use which will allow you to access the button instance if you need it later
button_ox integer the relative x position of the button from the top-left of the menu sprite
button_oy integer the relative y position of the button from the top-left of the menu sprite
button_text string text to add to the button, can be blank
button_script string the name of the function you want to call when the button is pressed - must be defined in your mod
sprite_image string relative path of the sprite you want to use for the button, can be any size but needs to have 2 frames (normal, highlighted)

If this method worked it will return Success, otherwise if it fails it will return nil and will log an error in the Modding Console with one of the following errors:

Error Description
Menu Instance Not Found the menu_id given wasn't a valid menu instance id or doesn't exist
Button Sprite Not Found the path for the given sprite was not found

Example code to create a new button on an existing menu:

-- menu define script
function some_menu_define_method(menu_id)
  -- add a button to the menu
  api_define_button(menu_id, "test_button", 50, 50, "Button Text", "button_click", "sprites/example_button.png")
end

-- if you dont draw the button in the menu draw script you would be able to see it
function some_menu_draw_method(menu_id)
  api_draw_button(api_gp(menu_id, "test_button"), true)
end

-- button click script
function button_click(menu_id)
  api_create_log("button", "My button has been pressed!")
end

api_define_color()

All colors in the game are defined in the colors_ref.json file in the base game, each with their own key.
This method allows you to define a custom RGB color to use alongside these existing color keys.

Parameter Datatype Description
name string the name to use for your color, will be the color key you can use in the future to draw with
color color the rgb color you want to define

If this method worked it will return Success, otherwise if it fails it will return nil and will log an error in the Modding Console with one of the following errors:

Error Description
Color Name Already Exists a color with this key already exists

Example code to define a color and use it in the draw() hook:

-- define the color
api_define_color("super_green", {r=0,g=255,b=0})

-- use color in the draw hook 
function draw() 
  -- get relative position of the player
  player_pos = api_get_player_position()
  camera_pos = api_get_cam()
  px = player_pos["x"] - camera_pos["x"]
  py = player_pos["y"] - camera_pos["y"]

  -- draw green circle outline around player
  api_draw_circle(px, py, 64, "super_green", true)
end

api_define_command()

This method allows you to define a custom command that you can run with the in-game console. This requires dev mode to be enabled with api_set_devmode().
Your command name should include the forward slash, i.e. /teleport.

Parameter Datatype Description
command_name string the unique name for your command, must be unique across all mods
command_script string the script to run when the command is entered, will be passed a list of arguments as a parameter

If this method worked it will return Success, otherwise if it fails it will return nil and will log an error in the Modding Console with one of the following errors:

Error Description
Command With That Name Already Exists command name used is already defined

Example code to define a command that lets you teleport to a specific x + y position

function init() 
  -- turn on inline commands
  api_set_devmode(true)
  -- define a new command
  -- use with /teleport x y
  api_define_command("/teleport", "teleport_command")
end

-- command run when player types "/teleport"
function teleport_command(args) 
  -- args are a list of args after /teleport separated by spaces
  -- for example we could type "/teleport 100 50" in this case
  api_set_player_position(args[1], args[2])
end

api_define_flower()

This method lets you define a new species of flower and add it to the game. This not only defines a flower object, but also a seedling for the flower as well as a seed item. As such you'll need to provide sprites for the flower as well as the seed packet.
As flowers do not have a unique ID per mod you will need to make sure your flower is unique between all mods.

Parameter Datatype Description
flower_def flower_definition your flower definition table
flower_sprite_image string relative path of the sprite you want to use for the flower item, should be a 64x16 image with 4 frames (normal, normal highlighted, undiscovered, undiscovered highlight)
flower_variants_image string relative path of the sprite you want to use for overworld variants, should be 16 pixels high and the width based on variants. 2 variants would be 4 frames, as each variant needs a normal sprite and a highlight.
flower_seed_image string relative path of the sprite you want to use for the flower seed item, should be a 64x16 image with 4 frames (normal, normal highlighted, undiscovered, undiscovered highlight)
flower_hd_image string relative path of the sprite you want to use for the "HD" bee image in the book, should be a 96x48 image with 2 frames (normal, undiscovered)
flower_color color custom RGB color for the flower, used in the smoker, overworld and the book

If this method worked it will return Success, otherwise if it fails it will return nil and will log an error in the Modding Console with one of the following errors:

Error Description
Missing Required Key a required key was missing from the definition
Flower With This ID Exists flower with your given id is already defined
Flower Item Creation Failed flower item could not be created, check your definition
Flower Sprites Not Found path for the sprites could not be found
Failed To Map Keys general catch all for the method, check your definition and parameters

Example code to define a custom flower that can be planted on ocean:

-- create flower_definition table
flower_def = {
  id = "14",
  species = "my_flower",
  title = "My Flower",
  latin = "Myus Flowerus",
  hint = "Found in deep water",
  desc = "This is my cool ocean flower!",
  aquatic = true,
  variants = 2,
  deep = true,
  smoker = {"stubborn","fiery"},
  recipes = {
    { a = "flower14", b = "flower1", s = "flower6" }
  }
}

-- define flower
api_define_flower(flower_def, 
  "sprites/flower_item.png", "sprites/flower_variants.png", 
  "sprites/flower_seed_item.png", "sprites/flower_hd.png",
  {r=100, g=100, b=100}
);

api_define_flower_recipe()

This allows you to define a custom flower "recipe" that lets you specify a hybrid combination. Each flower can have up to 3 recipes (as they are shown in the book), and the flowers in the recipe need to be defined before calling this method if you are using custom bees.
Flower mutations don't depend on criteria, the chance is based off the chance defined in species_s's definition - you can set this chance on your own flowers when you define them.

Parameter Datatype Description
species_a string one of the two flowers this hybrid needs - recipe will be added to both flower definitions
species_b string the other flower this hybrid needs - recipe will be added to both flower definitions
species_s string the flower that will be formed if a mutation occurs, it's "chance" value will be used for the mutation chance

If this method worked it will return Success, otherwise if it fails it will return nil and will log an error in the Modding Console with one of the following errors:

Error Description
Flower/s Already Has 3 Recipes species_a or species_b already has 3 recipes defined
Species Given Are Not Defined one of the 3 species parameters are not defined bee species

Example code to create new recipe between Honeyrose and Honeybriar to make Combristle:

-- flower12 is Combristle which has a 36% chance on it's definition
-- this now means frames that have been filled by bees visiting Honeyrose and Honeybriar have a 36% chance to make Combristle seeds when extracted
api_define_flower_recipe("flower1", "flower4", "flower12")

api_define_gif()

This method allows you to define a custom "gif" sprite which you can then use in custom quest definitions.
The only difference between this and api_define_sprite() is that whatever name you provide will be prepended with "gif_", i.e. gif_my_gif_name which will allow the quest rendered to show the GIF correctly.

Parameter Datatype Description
gif_name string the name for this gif, will be prepended with "gif_"
gif_image string the path to the gif sprite you want to add, must be 148px wide, and either 46px, 66px or 86px high
frames integer the number of frames for the gif - your image will be divided by the number of frames given, and used to create the animated gif

If this method worked it will return the gif id which you can use later in you need to, otherwise if it fails it will return nil and will log an error in the Modding Console with one of the following errors:

Error Description
Failed To Find Path specified gif path could not be found
GIF Name Already Exists a gif with this name already exists
Failed To Define GIF general catch-all for this method, check your definition and parameters

Example code define a new gif to then use in a custom quest definition:


api_define_gui()

This lets you create a custom GUI for a given menu. GUIs let you have an interactive section of the menu that shows a tooltip when hovered. In the game these are used for things like progress meters, arrows, and tanks.
Your "gui_key" should be unique per menu object define (i.e. don't use "progress" for 2 different menu objects).

Parameter Datatype Description
menu_id integer the menu object instance id you want to define attach the gui to
gui_key string the name of the key you want to use which will allow you to access the gui instance if you need it later (needs to be unique per define)
gui_ox integer the relative x position of the gui from the top-left of the menu sprite
gui_oy integer the relative y position of the gui from the top-left of the menu sprite
gui_script string the name of the function you want to call when the gui is hovered to return tooltip text - must be defined in your mod
sprite_image string relative path of the sprite you want to use for the gui, can be any size but needs to have 3 frames (highlighted, stencil, progress block)
gui_script string [Optional] the name of the function you want to call when the gui is clicked on - must be defined in your mod

If this method worked it will return Success, otherwise if it fails it will return nil and will log an error in the Modding Console with one of the following errors:

Error Description
Menu Instance Not Found the menu_id given wasn't a valid menu instance id or doesn't exist
GUI Sprite Not Foun the path for the given sprite was not found

Example code:

-- define properties on the menu object 
function some_menu_define(menu_id)

  -- create gui for the menu
  api_define_gui(menu_id, "recycler_progress_bar", 49, 20, "recycler_gui_tooltip", "sprites/recycler_gui_arrow.png")
  
  -- save gui sprite ref for later
  api_dp(menu_id, "progress_bar_sprite", api_get_sprite("sample_mod_recycler_progress_bar"))

end

-- draw the gui in the menu object's draw script
function some_menu_draw(menu_id)

  -- get camera
  cam = api_get_cam()
  
  -- draw gui progress here
  gui = api_get_inst(api_gp(menu_id, "recycler_progress_bar"))
  spr = api_gp(menu_id, "progress_bar_sprite")
  
  -- draw arrow "progress" block then cover up with arrow hole
  -- arrow sprite is 47x10
  gx = gui["x"] - cam["x"]
  gy = gui["y"] - cam["y"]
  progress = (api_gp(menu_id, "p_start") / api_gp(menu_id, "p_end") * 47)
  api_draw_sprite_part(spr, 2, 0, 0, progress, 10, gx, gy)
  api_draw_sprite(spr, 1, gx, gy)
  
  -- draw highlight if highlighted
  if api_get_highlighted("ui") == gui["id"] then
    api_draw_sprite(spr, 0, gx, gy)
  end

end

api_define_item()

This allows you to define a custom item and add it to the game. Items are things you want the player to be able to pick up, drop, use, or craft with. A good example of an item in the base game are Logs or Planks.
When you define an item the item oid will be the id you give prepended with your mod name, i.e. sample_mod_my_item.

Parameter Datatype Description
item_def item_definition an item definition table
sprite_image string relative path to the sprite you want to use for this item, should be a 64x16 image with 4 frames (normal, normal highlighted, undiscovered, undiscovered highlight)

If this method worked it will return Success, otherwise if it fails it will return nil and will log an error in the Modding Console with one of the following errors:

Error Description
Missing Required Key a required key was missing from the definition
Item Marked Placeable But No Object Specified item definition had "placeable" marked as true but no "obj" key was given
ID Already Defined item with this oid has already been defined.
Item Sprite Not Found path to sprite given was not found
Failed To Map Keys general catch-all for the method, check your definition and parameters

Example code to define a new super cool axe:

-- define an item
api_define_item({
  id = "cool_axe",
  name = "Cool Axe",
  category = "Decoration",
  tooltip = "This is a cool axe!",
  durability = 1000,
  singular = true
}, "sprites/cool_axe.png")

-- give the player the item
api_give_item("sample_mod_cool_axe", 1)

api_define_item_stats()

This allows you to define the default stats that an item will spawn with when created, like how canisters or bees always have a default set of stats.

Parameter Datatype Description
oid string the oid of the item to define default stats for (see OID Reference)
stats table the stats to give to an item when created if it has the given oid

This method won't return anything as it's just assigning a value to a key.

Example code to define a new super cool axe and give it default custom stats to use later:

-- define an item
api_define_item({
  id = "cool_axe",
  name = "Cool Axe",
  category = "Decoration",
  tooltip = "This is a cool axe!",
  durability = 1000,
  singular = true
}, "sprites/cool_axe.png")

-- set default stats
api_define_item_stats("sample_mod_cool_axe", { awesomeness = 10 })

-- give the player the item
api_give_item("sample_mod_cool_axe", 1)

-- you could then read the "stats" off of the item (or slot when picked up) to read back the "awesomeness" value

api_define_liquid()

As you may have already found out by messing around with canisters, you can technically change the "type" to be any value you want, however the canister will only render an unknown white liquid.
This method allows you to properly define the color and texture to use for a liquid, and make the game register it properly in barrels/canisters and your own custom tanks (you can see example sprites in the Sample Mod)
Note: Custom liquids cannot be used in the Bottler.

Parameter Datatype Description
name string the name of the liquid to use, this will be shown in tooltips and be set as the liquid "type" in stats
color string a color name to use for the liquid, this can be a default one or your own that you defined with api_define_color()
texture_sprite string the path to a single 37x34px image used as the liquid "texture". This will be drawn at 50% alpha on top of any tanks with your liquid in it, to help identify your liquid without color
preview_sprite string the path to a single 12x12px image used as the liquid preview when hovering over machines with a tank containing your liquid - this should be a solid filled in image (i.e. your color + your texture combined)

If this method worked it will return Success, otherwise if it fails it will return nil and will log an error in the Modding Console with one of the following errors:

Error Description
Liquid Already Defined a liquid with your given "name" is already defined
Color Not Defined the color name given is either not a default color or not a defined color
Texture Sprite Not Found path to sprite given was not found
Preview Sprite Not Found path to sprite given was not found

Example code to define a "coffee" liquid and spawn a canister containing that liquid:

-- define a new liquid and give it a color/texture
api_define_liquid(
  "Coffee", 
  "FONT_GREEN", 
  "sprites/liquid_texture.png",
  "sprites/liquid_preview.png" 
)

-- spawn a canister near the player with some coffee in it
-- if you defined everything correctly you'll be able to put this canister in a barrel or your own custom menu tank
-- and see the tank fill with the correct color / texture and show the right name in the tooltip
player_pos = api_get_player_position()
canister = api_create_item("canister1", 0, player_pos["x"] + 32, player_pos["y"] + 32)
stats = api_gp(canister, "stats")
stats["type"] = "Coffee"
stats["amount"] = 400
api_sp(canister, "stats", stats)

-- profit?

api_define_menu_object()

This let's you define a new menu object. Menu objects are similar to objects but can be clicked to open a menu - a good example in-game would be a sawbench or a crate. They can be also given logic to run all the time so are a powerful tool for your mods.
When you define a menu object the object oid will be the id you give prepended with your mod name, i.e. sample_mod_my_menu_object.
When you define a menu object you also can provide 4 scripts that allow you to run all the fun stuff. These are defined in the scripts you pass in and need to be functions in your mod file. You can also set what values need to be saved from the menu to be loaded when the player reloads the game. See the example further below for more details.

Parameter Datatype Description
menu_def menu_definition the menu definition table to use
sprite_image string relative path of the sprite you want to use for the menu object, should be a 64x16 image with 4 frames (normal, normal highlighted, undiscovered, undiscovered highlight)
menu_image string relative path of the sprite you want to use for the menu itself, can be any size but needs to have 4 frames (normal, highlighted, dragging, help overlay)
scripts scripts a scripts definition for all the scripts you want your menu object to run
draw_script string [Optional] if specified this allows you to override the default object draw (overworld object) with your own draw script - this must be a method in your mod, and won't be called if you set the obj_definition "invisible" property to true

If this method worked it will return Success, otherwise if it fails it will return nil and will log an error in the Modding Console with one of the following errors:

Error Description
Missing Required Key a required key was missing from the definition
ID Already Defined a menu object with this oid already exists
Object Sprite Not Found the given object sprite path was not found
Failed To Add Sprite the given menu sprite path was not found
Failed To Map Keys generic catch-all for the method, check your definition and parameters

Example code to add a custom "Recycler" machine, that takes items and turns them into random seeds:

-- define our menu object in the init() hook
function init() 

  -- define new menu object
  api_define_menu_object({
    id = "recycle_bin",
    name = "Recycle Bin",
    category = "Tools",
    tooltip = "Let's you recycle items into random flower seeds",
    layout = {
      {7, 17},
      {7, 39},
      {30, 17},
      {30, 39},
      {99, 17, "Output"},
      {99, 39, "Output"},
      {122, 17, "Output"},
      {122, 39, "Output"},
      {7, 66},
      {30, 66},
      {53, 66},
      {76, 66},
      {99, 66},
      {122, 66},
    },
    buttons = {"Help", "Target", "Close"},
    info = {
      {"1. Recycle Input", "GREEN"},
      {"2. Recycled Output", "RED"},
      {"3. Extra Storage", "WHITE"},
    },
    tools = {"mouse1", "hammer1"},
    placeable = true
  }, "sprites/recycler_item.png", "sprites/recycler_menu.png", {
    define = "recycler_define", -- defined below as a function
    draw = "recycler_draw", -- defined below as a function
    tick = "recycler_tick", -- defined below as a function
    change = "recycler_change" -- defined below as a function
  })

  return "Success"
end

-- the define script is called when a menu object instance is created
-- this means we can define properties on the menu object for the first time
function recycler_define(menu_id)

  -- create initial props
  api_dp(menu_id, "working", false)
  api_dp(menu_id, "p_start", 0)
  api_dp(menu_id, "p_end", 1)

  -- create gui for the menu
  api_define_gui(menu_id, "progress_bar", 49, 20, "recycler_gui_tooltip", "sprites/recycler_gui_arrow.png")
  
  -- save gui sprite ref for later
  api_dp(menu_id, "progress_bar_sprite", api_get_sprite("sample_mod_progress_bar"))

  -- add our p_start and p_end props to the default _fields list so the progress is saved 
  -- any keys in _fields will get their value saved when the game saves, and loaded when the game loads again
  fields = {"p_start", "p_end"}
  fields = api_sp(menu_id, "_fields", fields)

end

-- the change script lets us listen for a change in the menu's slots
-- it's called when a slot changes in the menu
function recycler_change(menu_id)

  -- if we have items in the first four slots let's get to work
  input_slot = api_slot_match_range(menu_id, {"ANY"}, {1, 2, 3, 4}, true)
  if input_slot ~= nil then 
    api_sp(menu_id, "working", true)
  end

end

-- the tick script lets us run logic we need for the menu object 
-- it's called every 0.1s (real-time)
function recycler_tick(menu_id)

  -- handle countdown if working
  if api_gp(menu_id, "working") == true then
    -- add to counter
    api_sp(menu_id, "p_start", api_gp(menu_id, "p_start") + 0.1)
    -- if we hit the end, i.e. 10s have passed
    if api_gp(menu_id, "p_start") >= api_gp(menu_id, "p_end") then

      -- reset the counter
      api_sp(menu_id, "p_start", 0)
      
      -- get the "input" slots to get an item
      input_slot = api_slot_match_range(menu_id, {"ANY"}, {1, 2, 3, 4}, true)
      -- assuming there is a slot width stuff
      if input_slot ~= nil then

        -- remove 1 from slot
        api_slot_decr(input_slot["id"])

        -- add seed to output
        seed_item = api_choose({"seed1", "seed2", "seed3"})
        output_slot = api_slot_match_range(menu_id, {"", seed_item}, {5, 6, 7, 8}, true)
        if output_slot ~= nil then
          -- if empty slot add 1 seed item
          if output_slot["item"] == "" then
            api_slot_set(output_slot["id"], seed_item, 1)
          -- otherwise add to existing seed item in slot
          else 
            api_slot_incr(output_slot["id"])
          end
        end

        -- recheck input, if nothing then stop working
        input_slot = api_slot_match_range(menu_id, {"ANY"}, {1, 2, 3, 4}, true)
        if input_slot == nil then api_sp(menu_id, "working", false) end

      end
    end
  end
end

-- the draw script lets us draw custom things on the menu when it's open
-- here we can draw GUI elements or buttons or other things
-- you should avoid putting complex logic in the draw script
function recycler_draw(menu_id)

  -- get camera
  cam = api_get_cam()

  -- draw gui progress here
  gui = api_get_inst(api_gp(menu_id, "progress_bar"))
  spr = api_gp(menu_id, "progress_bar_sprite")

  -- draw arrow "progress" block then cover up with arrow hole
  -- arrow sprite is 47x10
  gx = gui["x"] - cam["x"]
  gy = gui["y"] - cam["y"]
  progress = (api_gp(menu_id, "p_start") / api_gp(menu_id, "p_end") * 47)
  api_draw_sprite_part(spr, 2, 0, 0, progress, 10, gx, gy)
  api_draw_sprite(spr, 1, gx, gy)

  -- draw highlight if highlighted
  if api_get_highlighted("ui") == gui["id"] then
    api_draw_sprite(spr, 0, gx, gy)
  end

end

-- return text for gui tooltip
-- this method is called by the GUI instance when we hover over it
-- the text returned is shown in a tooltip
function recycler_gui_tooltip(menu_id) 
  progress = math.floor((api_gp(menu_id, "p_start") / api_gp(menu_id, "p_end")) * 100)
  percent = tostring(progress) .. "%"
  return {
    {"Progress", "FONT_WHITE"},
    {percent, "FONT_BGREY"}
  }
end

api_define_notification()

This let's you define your own notification type to use with api_set_notification(). Standard notification types have their own actions when clicked, some simply dismiss while others open books.
Using this method you can set your own action for when the player clicks on your notification!

Parameter Datatype Description
notification_type string a name for your notification - will be prepended by your mod ID, i.e. sample_mod_my_notification
notification_script string the script to run when the player clicks this type of notification - needs to be a method in your mod file

If this method worked it will return Success, otherwise if it fails it will return nil and will log an error in the Modding Console with one of the following errors:

Error Description
Notification Type Already Defined notification with this type name has already been used

Example code to make a notification type and then set a notification for that type:

function init() 

  -- define a notification type
  api_define_notification("alert", "alert_click")

  -- create a notification
  api_set_notification("sample_mod_alert", "axe1", "Hello World", "Click Me!")
  return "Success"

end

api_define_npc()

This let's you define your NPC, with their own dialogue and their own shop / stock. NPCs are just fancy menu objects that walk and talk!
You will need to handle adding in the NPC to the game yourself, whether in worldgen(), ready(), or somewhere else.

Parameter Datatype Description
npc_def npc_definition the definition obj for your NPC
standing_sprite string relative path to the sprite you want to use for the NPC standing animation, should be a 36x18 image with 2 frames (standing, standing_bob)
standing_h_sprite string relative path to the sprite you want to use for the NPC when standing and highlighted, should be a 36x18 image with 2 frames (standing, standing_bob)
walking_sprite string relative path to the sprite you want to use for the NPC walk animation, should be a 72x18 image with 4 frames (stand, step_1, stand, step_2)
walking_h_sprite string relative path to the sprite you want to use for the NPC when walking and highlighted, should be a 72x18 image with 4 frames (stand, step_1, stand, step_2)
head_sprite string relative path to the sprite you want to use for this NPCs map icon, should be a 64x16 image with 4 frames (normal, normal highlighted, undiscovered, undiscovered highlight)
bust_sprite string relative path to the sprite you want to use for this item, should be a 18x14 image with 1 frame
item_sprite string relative path to the sprite you want to use for this NPCs item (that you get when you hammer an NPC), should be a 64x16 image with 2 frames (normal, normal highlighted)
dialogue_menu_sprite string relative path to the sprite you want to use for this NPCs dialogue menu, should be a 648x138 image with 2 frames (normal, normal highlighted) but can technically be any size if you want to mess with it
shop_menu_image string relative path of the sprite you want to use for the NPCs shop menu, can be any size but needs to have 4 frames (normal, highlighted, dragging, help overlay)

If this method worked it will return Success, otherwise if it fails it will return nil and will log an error in the Modding Console with one of the following errors:

Error Description
Missing Required Key one of the required keys in the npc_definition is missing
NPC ID Must Be A Number the given id is not a number
NPC With This ID Already Defined npc with this id is already defined
Need To Specify At Least 3 Specials npc definition needs at least 3 specials
Failed To Load Sprite/s sprite path/s for the npc could not be found
Failed To Define NPC general catch-all for the method failing, check datatypes in your definition

Example code to define a new NPC:

--set npc definition
npc_def = {
  id = 69,
  name = "Gobbo",
  pronouns = "They/Them",
  tooltip = "Wassup pal?",
  shop = true,
  walking = true,
  stock = {"log", "log", "log", "log", "log", "log", "log", "log", "log", "log"}, -- max 10
  specials = {"log", "log", "log"}, -- must be 3
  dialogue = {
    "Wot ya mean av I gots anything other than logs to sell??",
    "Wot a stoopid question hoomie"
  },
  greeting = "Alright pal ow ya gettin' on"
}
-- define npc, damn thats a lot of sprites
api_define_npc(npc_def,
  "sprites/npc_standing.png",
  "sprites/npc_standing_h.png",
  "sprites/npc_walking.png",
  "sprites/npc_walking_h.png",
  "sprites/npc_head.png",
  "sprites/npc_bust.png",
  "sprites/npc_item.png",
  "sprites/npc_dialogue_menu.png",
  "sprites/npc_shop_menu.png"
)

api_define_object()

This let's you define your own object and add it to the game. Objects are things the player can place down, as well as pickup, use, or craft with. A good example of an object in the base game are Benches or Beds.
When you define an object the object oid will be the id you give prepended with your mod name, i.e sample_mod_my_object.

Parameter Datatype Description
object_def obj_definition an obj definition table
sprite_image string relative path to the sprite you want to use for this object, should be a 64x16 image with 4 frames (normal, normal highlighted, undiscovered, undiscovered highlight)
draw_script string [Optional] if specified this allows you to override the default object draw with your own draw script - this must be a method in your mod, and won't be called if you set the obj_definition "invisible" property to true

If this method worked it will return Success, otherwise if it fails it will return nil and will log an error in the Modding Console with one of the following errors:

Error Description
Missing Required Key a required key was missing from the definition
ID Already Defined an object with this oid has already been defined
Object Sprite Not Found the sprite path for this object was not found
Missing Required Key general catch-all for this method, check your definition and parameters

Example code to make a chair object:

-- defines a cool chair you can place down
api_define_object({
  id = "cool_chair",
  name = "Nice Chair",
  category = "Decoration",
  tooltip = "This is a nice chair",
  tools = {"hammer1"}
}, "sprites/cool_chair.png", "my_draw_script")

-- override the default draw
function my_draw_script(obj_id) 
  -- draw something else
end

api_define_property()

This allows you to define a new property onto any instance which you'll then be able to use with api_set_property() and api_get_property(). Most commonly you'll be using this in your menu object's define script. You can use "api_dp()" as a shorthand.
Potentially you might end up overriding an existing property so might be worth checking first before setting something generic!
If defining properties on a menu object, you will need to add them to the default _fields key for them to get saved + loaded if you need them to (see below)

Parameter Datatype Description
inst_id integer id of instance to set a property on
prop_name string key for the property to set
prop_value Any value to set the property to

If this method worked it will return Success, otherwise if it fails it will return nil and will log an error in the Modding Console with one of the following errors:

Error Description
Instance Doesn't Exist the instance specified either doesn't exist or has been deactivated

Example code:

-- define properties on a menu object for the first time
function some_menu_define_method(menu_id)
    -- add some properties to the menu object
    api_dp(menu_id, "working", false)
    api_dp(menu_id, "p_start", 0)
    api_dp(menu_id, "p_end", 1)
    -- save p_start and p_end keys so our menu keeps progress on save/load
    fields = {"p_start", "p_end"}
    api_dp(menu_id, "_fields", fields)
end

api_define_quest()

This method allows you to define your own quest that will be shown in the quest book with it's own requirements and rewards. Currently all modded quests show under their own seperate section at the bottom of the book.

Parameter Datatype Description
quest_def quest_definition the quest definition table you want to use
page1 list(quest_line) the lines for the left-hand side quest page
page2 list(quest_definition) the lines for the right-hand side quest page
claim_script string [Optional] call a script when the quest is completed

If this method worked it will return Success, otherwise if it fails it will return nil and will log an error in the Modding Console with one of the following errors:

Error Description
Missing Required Key a required key was missing from the definition
Quest With ID Already Defined a quest has already been defined with the given id
Failed To Define Quest general catch-all for this method, check your definition and parameters

Example code:

-- define gif
api_define_gif("sample_gif", "sprites/sample_gif.png", 2)

-- create quest definition
quest_def = {
  id = "my_new_quest",
  title = "My New Quest",
  reqs = {"planks1@10"},
  icon = "planks1",
  reward = "axe2@1",
  unlock = {},
  unlocked = true
}

-- create quest pages 
quest_page1 = {
  { text = "Hello this is my quest" },
  { text = "This line is BLUE", color = "FONT_BLUE" }
}
quest_page2 = {
  { text = "This is cool have a free reward" },
  { gif = "sample_gif", height = 46 }
}

-- define quest
api_define_quest(quest_def, quest_page1, quest_page2)

api_define_recipe()

This method allows you to define a new recipe for the Mod Workbench for a specific tab. Each mod has it's own section in the Mod Workbench, meaning you can define up to 100 recipes (20 recipes per 5 tabs).
You can use api_define_workbench() to define the tab names for your mod.

Parameter Datatype Description
tab string the tab in the workbench that this recipe will be shown in, options are t1, t2, t3, t4, and t5
item string the item oid that you want this recipe to be for (see OID Reference)
recipe recipe a recipe definition you want to use
amount integer [Optional] if specified, when crafting this recipe the player will get this amount instead of 1

If this method worked it will return Success, otherwise if it fails it will return nil and will log an error in the Modding Console with one of the following errors:

Error Description
Invalid Recipe Tab Name tab provided isn't one of the valid options
Invalid Recipe Ingredients invalid recipe definition, check your setup

Example code:

-- define a recipe definition
recipe = {
  { item = "boat", amount = 999 },
  { item = "mead", amount = 999 }
}

-- add the recipe to the mod workbench so that it crafts an "npc1" item (Skipper)
res = api_define_recipe("t1", "npc1", recipe, 1)

api_define_sprite()

This method allows you to define a custom sprite which you can then use in draw calls later. You can add any image you want but try not to add huge images as it can take longer to add your sprite to all the texture pages.
Whatever name you provide will be prepended with "sp_", i.e. sp_my_mod_sprite_name.
For all sprites, GameMaker will use the bottom left pixel as the "transparent" pixel!
All sprite names are global across mods so it's recommended to use your mod_id in the name provided.

Parameter Datatype Description
sprite_name string the name for this sprite, will be prepended with "sp_"
sprite_image string the path to the sprite you want to add, can be any size
frames integer the number of frames for the sprite - your image will be divided by the number of frames given

If this method worked it will return the sprite id which you can use later, otherwise if it fails it will return nil and will log an error in the Modding Console with one of the following errors:

Error Description
Failed To Find Path specified sprite path could not be found
Sprite Name Already Exists a sprite with this name already exists
Failed To Define Sprite general catch-all for this method, check your definition and parameters

Example code define a new sprite to draw with:

-- setup vars to store sprite and rotation
spr_bee = nil
rot = 0

-- define a sprite in the init hook()
function init() 
  spr_bee = api_define_sprite("sample_mod_sus_bee", "sprites/sus-bee.png", 1)
  return "Success"
end

-- update a value every tick to use in our draw cycle
function tick(init) 
  rot = rot + 10
  if rot > 360 then rot = 0 end
end

-- draw our sprite on top of the player, rotating each tick
function draw(init) 
  if spr_bee ~= nil then
    camera_pos = api_get_camera_position()
    player_pos = api_get_player_position()
    px = player_pos["x"] - camera_pos["x"]
    py = player_pos["y"] - camera_pos["y"]
    api_draw_sprite_ext(spr_bee, 0, px, py, 3, 3, rot, nil, 1)
  end
end

api_define_tank()

This method allows you to define a liquid storage tank for a given menu. This tank can then be used with standard methods like api_slot_fill(), api_slot_drain(), and api_draw_tank()

Parameter Datatype Description
menu_id integer the menu instance to add the tank too
tank_amount integer the default amount of liquid in the tank
tank_max integer the max amount of liquid this tank can have
tank_type string the type of tank this is, options are water, resin, honey or mead
tx integer the x position of this tank relative to the menu's top-left corner
ty integer the y position of this tank relative to the menu's top-left corner
tank_size string the size of the tank gui (unrelated to tank_max), options are small, medium, large or xlarge
tank_script string [Optional] the name of the function you want to call when the tank is clicked on - must be defined in your mod

If this method worked it will return Success, otherwise if it fails it will return nil and will log an error in the Modding Console with one of the following errors:

Error Description
Menu Instance Not Found specified menu instance doesn't exist or isn't active

Example code to setup a menu object that has a water tank and a slot you can drain the water from:

function init() 

  -- define new menu object
  api_define_menu_object({
    id = "water_purifier",
    name = "Water Purifier",
    category = "Tools",
    tooltip = "Let's you collect water from the ocean",
    layout = {
      {19, 63, "Liquid Output", {"canister1", "canister2"}}
    },
    buttons = {"Help", "Target", "Close"},
    info = {
      {"1. Water Tank", "GREEN"},
      {"2. Liquid Output", "RED"},
    },
    tools = {"mouse1", "hammer1"},
    placeable = true,
    aquatic = true,
    deep = true
  }, "sprites/recycler_item.png", "sprites/recycler_menu.png", {
    define = "water_purifier_define", -- defined below as a function
    draw = "water_purifier_draw", -- defined below as a function
    change = "water_purifier_change" -- defined below as a function
  })

  return "Success"
end

-- setup water purifier tank + gui
function water_purifier_define(menu_id) 
  -- define a tank gui
  api_define_tank(menu_id, 1000, 2000, "water", 4, 14, "xlarge")
  -- save the special tank props to our menu._fields so the values are saved/loaded
  fields = {"tank_amount", "tank_max", "tank_type"}
  fields = api_sp(menu_id, "_fields", fields)
end

-- handle slot change to drain water into a canister
function water_purifier_change(menu_id)
  -- check if we have a canister, if so try and drain to the canister
  slot = api_get_slot(menu_id, 1)
  if slot["item"] == "canister1" or slot["item"] == "canister2" then
    api_slot_drain(menu_id, 1)
  end
end

-- draw the tank 
function water_purifier_draw(menu_id)
  -- draw our water tank
  api_draw_tank(api_gp(menu_id, "tank_gui"))
end

api_define_trait()

This method allows you to define a completely new trait for all bees in the game. This trait will be passed down through dominent and recessive genes like all traits, and you'll be able to access the value of the trait through the slot's stats.

Parameter Datatype Description
trait_key string the name of this trait, will be prepended with your mod id, i.e. sample_mod_magic
trait_map table a table containing keys with a species name, and a value containing a list of available values for this species (see below for example). When a "new" bee is formed through mutation, it will pick randomly from it's trait ranges to get a value for itself.
default_value list(string) a value (or values) to use for any species not in the trait_map, or for any existing bee items when they're bred later

If this method worked it will return Success, otherwise if it fails it will return nil and will log an error in the Modding Console with one of the following errors:

Error Description
Trait Already Defined specified trait key has already been used
Trait Couldn't Be Defined general catch-all for this method, try checking your map or default value

Example code to add a "magical" trait to bees, defining some default values for a few specific bees, and getting that trait value from a slot when clicked:

-- setup the trait
function init() 

  -- add a magic level trait to bees, specifying trait ranges for some bees
  -- but adding a default for all other species
  api_define_trait("magic", {
    common = {"low"}, 
    dream  = {"low", "medium"}, 
    twilight = {"high"}
  }, {"none"}) -- default for all the other bees
  return "Success"

end

-- get trait when clicking a slot
function click(button, click_type)

  -- log stats when right clicking a slot
  if button == "RIGHT" and click_type == "PRESSED" then

    -- check slot highlight
    highlighted = api_get_highlighted("slot")
    if highlighted ~= nil

      -- only for bees
      slot = api_get_slot_inst(highlighted)
      if slot["item"] == "bee" then
        api_log("magic level?", slot["stats"]["d_traits"]["sample_mod_magic"])
      end

    end

  end

end

api_define_validation_icon()

This method allows you to define a custom icon to use with custom validations in layout's for slots.

Custom validations follow the format of "customX:thing" where "thing" is the oid you want to allow in the slot.

Parameter Datatype Description
validation string the custom validation, i.e. "customX:axe" - this has to match what you put in your layout
icon_sprite string the sprite to use for the validation, shown on slot hover. This should be a single 16x16 sprite.

If this method worked it will return Success, otherwise if it fails it will return nil and will log an error in the Modding Console with one of the following errors:

Error Description
Sprite Not Found sprite path not found, check your files
Sprite Already Defined sprite has already been defined for the validation string you gave, maybe you already defined it?

Example code to add a custom validation to a machine that only takes axes:

-- setup the trait
function init() 

  -- define a basic menu
  api_define_menu_object({
    id = "axe_eater",
    name = "Axe Eater",
    category = "Tools",
    tooltip = "Eats axes, I don't know why don't ask me",
    layout = {
      {7, 17, "Input", {"customX:axe"}},
    },
    buttons = {"Help", "Target", "Close"},
    info = {
      {"1. Axe Input", "GREEN"},
    },
    tools = {"mouse1", "hammer1"},
    placeable = true
  }, "sprites/axe_eater_item.png", "sprites/axe_eater_menu.png", {})

  -- define a validation icon for "customX:axe"
  api_define_validation_icon("customX:axe", "sprites/some_axe.png")

  return "Success"

end

api_define_wall()

This method allows you to define your own custom wall that can be placed in-game and act as a solid.

Parameter Datatype Description
wall wall_definition definition for your new wall
wall_sprite string the spritesheet for the new wall, needs to contain both the item sprites and wall variants, see the example in the Sample Mod

If this method worked it will return Success, otherwise if it fails it will return nil and will log an error in the Modding Console with one of the following errors:

Error Description
Missing Required Key Your definition is missing either "id" or "name"
Wall ID Already Defined There is already a wall defined with this ID, use a different one or check you haven't defined twice
Wall Sprite Not Found Couldn't resolve the path to the sprite specified
Failed To Define Wall Generic catch all, see the error message for clues

Example code to add a shiny custom wall:

-- setup the trait
function init() 

  -- define a basic wall
  api_define_wall({
    id = 17,
    name = "Cool Wall" 
  }, "/sprites/wall/wall_sprite.png")

  return "Success"

end

api_define_window()

This method allows you to define your own custom window that can be placed on walls.
A window could be literally anything, as it's just an item that when placed on a wall will have a special frame drawn, so you could use this to make lights, shelves, banners etc.

Parameter Datatype Description
window window_definition definition for your new window
window_sprite string the spritesheet for the new window, should be 5 frames (16x16), the first 4 like a normal item/obj sprite, the 5th frame is what will be drawn onto the wall when placed down

If this method worked it will return Success, otherwise if it fails it will return nil and will log an error in the Modding Console with one of the following errors:

Error Description
Missing Required Key Your definition is missing either "id" or "name"
Window ID Already Defined There is already a window defined with this ID, use a different one or check you haven't defined twice
Window Sprite Not Found Couldn't resolve the path to the sprite specified
Failed To Define Wall Generic catch all, see the error message for clues

Example code to add a shiny custom wall:

-- setup the trait
function init() 

  -- define a basic window
  api_define_wall({
    id = 69,
    name = "Bee Banner" 
  }, "/sprites/banner_sprite.png")

  return "Success"

end

api_define_workbench()

This method allows you to define a custom label for your mod to be shown in the Mod Workbench, along with custom labels for the tabs for your mod (shown when hovered).
If not specified the Mod Workbench will show your mod_id, and tabs will just be labelled "Tab 1", "Tab 2" etc.
The labels you give do not affect the tab parameter in api_define_recipe() which will still always use "t1", "t2", etc

Parameter Datatype Description
label string label to show for your mod in the Mod Workbench
tabs table a table with 5 keys, "t1", "t2", "t3", "t4", "t5". each key should have a string value that will be displayed when that tab is hovered.

If this method worked it will return Success, otherwise god knows how you messed that up!

Example code to set the tabs for our mod:

-- setup the trait
function init() 

  -- define name + tabs for our mod in the Mod Workbench
  api_define_workbench("Some Crap", {
    t1 = "Stuff",
    t2 = "Bits",
    t3 = "Crap",
    t4 = "Junk",
    t5 = "Dust"
  })

end

Sign Item.pngDescribe Methods

Describe methods allow you to get specific metadata about the game, both from base game and from mods.

Method Description
api_describe_bees() returns a list of all bees defined from either the base game or all mods
api_describe_commands() returns a list of all commands defined from either the base game or all mods
api_describe_dictionary() returns the entire dictionary for either the base game or all mods
api_describe_mods() returns a list of all mod_id's loaded
api_describe_oids() returns a list of all oids defined from either the base game or all mods
api_describe_recipes() returns a list of all crafting recipes defined from either the base game or all mods

api_describe_bees()

This method returns all the bee definitions for either the base game or for all mods loaded.The bee definitions are also a heckin' BIG table, so I wouldn't try api_log()ing it lol

Parameter Datatype Description
mods boolean if true will return results for mods instead of the base game

If the "mods" parameter is false, this method will return a table containing all the bee definitions for the base game, with a key for each bee species (i.e. "common"). See your "bees.json" file for the sorts of values on these definition tables.
If true, this method will return a table with a key for each mod_id loaded, and then have the mods own bee definitions underneath that.

Example code to get some specific oid definitions from dictionaries:

-- get a base game bee definition
game_dictionary = api_describe_bees(false)
common_definition = game_dictionary["common"]
api_log("common details!", common_definition)

-- get a mod bee definition
my_mod = "sample_mod"
mod_dictionary = api_describe_bees(true)
my_mod_dictionary = mod_dictionary[my_mod]
my_bee_definition = my_mod_dictionary["nightcrawler"]
api_log("nightcrawler details!", my_bee_definition)

api_describe_commands()

This method returns all the commands usable in-game for either the base game or for all mods loaded.

Parameter Datatype Description
mods boolean if true will return results for mods instead of the base game

If the "mods" parameter is false, this method will return a list of strings for each command, i.e. "/gimme".
If true, this method will return a table with a key for each mod_id loaded, and then have list of commands under each mod key.

Example code to get some specific oid definitions from dictionaries:

-- log all base game commands
game_commands = api_describe_commands(false)
api_log("game commands!", game_commands)

-- log all mod commands
my_mod = "sample_mod"
mod_commands = api_describe_commands(true)
my_mod_commands = mod_commands[my_mod]
api_log("mod commands!", my_mod_commands)

api_describe_dictionary()

This method returns the entire dictionary for either the base game or for all mods loaded.The dictionary is a heckin' BIG table, so I wouldn't try api_log()ing it lol

Parameter Datatype Description
mods boolean if true will return results for mods instead of the base game

If the "mods" parameter is false, this method will return a table containing the entire dictionary for the base game, with a key for each oid. See your "dictionary.json" file for the sorts of values on these dictionary tables.
If true, this method will return a table with a key for each mod_id loaded, and then have the mods own dictionary underneath that.

Example code to get some specific oid definitions from dictionaries:

-- get a base game item definition
game_dictionary = api_describe_dictionary(false)
axe_definition = game_dictionary["axe1"]
api_log("axe details!", axe_definition)

-- get a mod item definition
my_mod = "sample_mod"
mod_dictionary = api_describe_dictionary(true)
my_mod_dictionary = mod_dictionary[my_mod]
my_axe_definition = my_mod_dictionary["sample_mod_cool_axe"]
api_log("mod axe details!", my_axe_definition)

api_describe_mods()

This method returns a list of mod_id's for all the mods currently load.

Parameter Datatype Description
oid string filter results to a specific oid (ideally you should always provide a filter) (see OID Reference)

This method will return a list of strings for each mod loaded.

Example code to get all mods the user currently has:

-- get mods
all_mods = api_describe_mods()
has_mod = false
for i=1,#all_mods do
  if all_mods[i] == "my_mod" then
    has_mod = true
  end
end

api_describe_oids()

This method returns a list of oids defined for either the base game or for all mods loaded (see OID Reference).

Parameter Datatype Description
mods boolean if true will return results for mods instead of the base game

If the "mods" parameter is false, this method will return a list of strings for each oid in the base game.
If true, this method will return a table with a key for each mod_id loaded, with a list of stringss for each of the mods' oids underneath it.

Example code to get some oids:

-- base game oids
all_oids = api_describe_oids(false)

-- random mod oids
my_mod = "sample_mod"
mod_oids = api_describe_oids(true)
my_mod_oids = mod_oids[my_mod]
api_log("my_mod_oids", my_mod_oids)

api_describe_recipes()

This method returns all the crafting recipes in either the base game or for all mods loaded.

Parameter Datatype Description
mods boolean if true will return results for mods instead of the base game

If the "mods" parameter is false, this method will return a table for each recipe category (see api_define_recipe()), with a list of recipe under each one.
If true, this method will return a table with a key for each mod_id loaded, and then have the recipe categories under each mod key (with the recipe lists under those).

Example code to get some specific oid definitions from dictionaries:

-- get a base game recipe
game_recipes = api_describe_recipes(false)
first_crafting = game_recipes["crafting"][1]
api_log("first crafting recipe!", first_crafting)

-- get a mod recipe
my_mod = "sample_mod"
mod_recipes = api_describe_recipes(true)
my_mod_recipes = mod_recipes[my_mod]
my_mod_crafting = my_mod_recipes["crafting"]
api_log("mod crafting recipes!", my_mod_crafting)

Pencil Item.pngDraw Methods

Draw methods let you draw sprites or primitives. These methods will only work in the draw script of a menu object (defined in api_define_menu_object()), in the draw() hook or in the gui() hook
It's worth noting that due to the small scale resolution of APICO any primitives you draw will be aligned with the pixel grid.

Method Description
api_draw_button() helper to draw a button defined with api_define_button() automatically
api_draw_circle() draws a circle (solid or outlined) at a specific position
api_draw_line() draws a line at a specific position
api_draw_rectangle() draws a rectangle (solid or outlined) at a specific position
api_draw_slots() draws all the slots for a given menu
api_draw_sprite() draws a given sprite at a specific position
api_draw_sprite_part() draws part of a given sprite at a specific position
api_draw_sprite_ext() draws a sprite at a given position and allows for transformations (rotate, scale, color blend)
api_draw_text() draws text at a specific position
api_draw_tank() helper to draw a tank defined with api_define_tank() automatically

api_draw_button()

Utility method to quickly draw a button you've defined with api_define_button(). You could draw the button manually but this does a lot of boilerplate for you.

Parameter Datatype Description
button_id integer the button id to draw
show_text boolean if the button has text you can choose to draw it here

Example code to define and draw a button for a menu:

-- define a button in a menu define script
function some_menu_define_method(menu_id)
  -- create button for the menu
  api_define_button(menu_id, "my_button", 50, 50, "Hello world!", "button_click_script", "sprites/button_sprite.png")
end

-- draw the button in the menu draw script
function some_menu_draw_method(menu_id)
  api_draw_button(api_gp(menu_id, "my_button"), true)
end

api_draw_circle()

This lets you draw a circle (filled or outline) at a give position.

Parameter Datatype Description
cx integer the x position to draw at (this will be at the centre of the circle)
cy integer the y position to draw at (this will be at the centre of the circle)
rad integer the radius of the circle
outline boolean whether to draw an outline instead of a filled circle
col string [Optional] the color key to use for this circle color, either one you defined with api_define_color() or a name from the colors_ref.json game file, defaults to white if not specified
alpha integer [Optional] the alpha level to draw with (number between 0-1)

Example code to draw some concentric coloured circles:

camera_pos = api_get_camera_position()
player_pos = api_get_player_position()
px = player_pos["x"] - camera_pos["x"]
py = player_pos["y"] - camera_pos["y"]
api_draw_circle(px, py, 100, "FONT_RED", true)
api_draw_circle(px, py, 80, "FONT_ORANGE", true)
api_draw_circle(px, py, 60, "FONT_YELLOW", true)
api_draw_circle(px, py, 40, "FONT_GREEN", true)
api_draw_circle(px, py, 20, "FONT_BLUE", true)

api_draw_line()

This lets you draw a basic line between two points.

Parameter Datatype Description
x1 integer the x position to start the line at
y1 integer the y position to start the line at
x2 integer the x position to end the line at
y2 integer the y position to end the line at
col string [Optional] the color key to use for this circle color, either one you defined with api_define_color() or a name from the colors_ref.json game file, defaults to white if not specified
alpha integer [Optional] the alpha level to draw with (number between 0-1)

Example code to draw a green line between two points:

api_draw_line(0, 0, 100, 100, "FONT_GREEN")

api_draw_rectangle()

This lets you draw a basic rectangle shape, either outlined or filled.

Parameter Datatype Description
x1 integer the left x position of the rectangle
y1 integer the top y position of the rectangle
x2 integer the right x position of the rectangle
y2 integer the bottom y position of the rectangle
col string the color key to use for this circle color, either one you defined with api_define_color() or a name from the colors_ref.json game file, defaults to white if set as nil
outline boolean whether to draw an outline instead of a filled rectangle
alpha integer [Optional] the alpha level to draw with (number between 0-1)

Example code to draw a 100x100px blue rectangular outline:

api_draw_rectangle(0, 0, 100, 100, "FONT_BLUE", true)

api_draw_slots()

This lets you redraw all the slots for a given menu. This is useful if you're trying to draw custom background elements on your menu, as the menu_draw script is called AFTER the default slot/gui rendering.

By using this method you can then redraw the slots on top of whatever you have drawn in your menu_draw script.

Parameter Datatype Description
menu_id integer the menu instance to draw the slots for (NOT the menu object instance)

Example code to draw a 100x100px blue rectangle in a menu draw cycle then redraw the slots on top:

function my_custom_menu_draw(menu_id)

  mx = api_gp(menu_id, "rx")
  my = api_gp(menu_id, "ry")

  api_draw_rectangle(mx, my, mx+100, my+100, "FONT_BLUE", true)

  api_draw_slots(menu_id)
end

api_draw_sprite()

This let's you draw a sprite that you either created through api_define_sprite() or retrieved through api_get_sprite().
You should get your sprite indexes outside of the draw script to help performance.

Parameter Datatype Description
sprite_ref integer the sprite id to draw with
frame integer the sprite frame to draw
sx integer the x position to draw at
sy integer the y position to draw at

Example code to draw a sprite you defined earlier:

-- var to store the sprite for later
spr_id = nil

function init() 
  -- get the standard axe sprite
  spr_id = api_get_sprite("sp_axe1")
end

function draw()
  -- draw the sprite at a position
  api_draw_sprite(spr_id, 0, 100, 50)
end

api_draw_sprite_part()

This is the same as api_draw_sprite() except you can draw a part of the sprite instead of the whole sprite.

Parameter Datatype Description
sprite_ref integer the sprite id to draw with
frame integer the sprite frame to draw
left integer the x position on the sprite image to draw the part from
top integer the y position on the sprite image to draw the part from
width integer the width of the part
height integer the height of the part
sx integer the x position to draw at
sy integer the y position to draw at

Example code to draw a small part of a sprite:

  -- var to store the sprite for later
  spr_id = nil
  
  function init() 
    -- get the standard axe sprite
    spr_id = api_get_sprite("sp_axe1")
  end
  
  function draw()
    -- draw the sprite at a position
    -- this will draw the bottom right 8x8 portion of the axe sprite
    api_draw_sprite_part(spr_id, 0, 8, 8, 8, 8, 100, 50)
  end

api_draw_sprite_ext()

This is the same as api_draw_sprite() except you can apply scale transformations, rotations and color blending.

Parameter Datatype Description
sprite_ref integer the sprite id to draw with
frame integer the sprite frame to draw
sx integer the x position to draw at
sy integer the y position to draw at
x_scale integer the x scale to apply
y_scale integer the y scale to apply
rot integer the rotation angle to draw at
col string the color blend to apply, use nil to apply no color blending
alp decimal the alpha level to draw with, a number between 0-1

Example code to draw our axe again but this time 3x the size:

-- var to store the sprite for later
spr_id = nil

function init() 
  -- get the standard axe sprite
  spr_id = api_get_sprite("sp_axe1")
end

function draw()
  -- draw the sprite at a position
  -- this will draw the axe at 3x the size
  api_draw_sprite_ext(spr_id, 0, 100, 100, 3, 3, 0, nil, 1)
end

api_draw_text()

This allows you to draw any amount of text, either on 1 line or wrapped based off a width

Parameter Datatype Description
tx integer the x position to draw at
ty integer the y position to draw at
text integer the text to draw
card boolean whether to show a card background behind the text (like tooltips)
col string [Optional] the color key to use for this circle color, either one you defined with api_define_color() or a name from the colors_ref.json game file, defaults to white if not specified
tw integer [Optional] a width to apply to the text, causing extra text to wrap onto the next line

Example code to draw a blue text tooltip ontop of the player:

-- get relative position of player
camera_pos = api_get_camera_position()
player_pos = api_get_player_position()
px = player_pos["x"] - camera_pos["x"]
py = player_pos["y"] - camera_pos["y"]

-- draw text
api_draw_text(px, py, "Hello World!", true, "FONT_BLUE", nil)

api_draw_tank()

Utility method to quickly draw a tank you've defined with api_define_tank(). You could draw the tank manually but this does a lot of boilerplate for you, including the liquid colour, liquid amount, liquid texture, highlights and more.

Parameter Datatype Description
tank_id integer the tank gui id to draw

Example code to define and draw a tank for a menu:

-- setup a water tank that can store up to 2000bl
function sample_menu_define(menu_id) 
  -- define a tank gui
  -- tank props are automatically saved for you so you dont need to add anything to _fields
  api_define_tank(menu_id, 1000, 2000, "water", 4, 14, "xlarge")
end

-- draw the tank 
function sample_menu_draw(menu_id)
  -- draw our water tank
  api_draw_tank(api_gp(menu_id, "tank_gui"))
end

Stone Hammer Item.pngGet Methods

Get methods allow you to retrieve information or instances from the game. All get methods start with api_get_*.

Method Description
api_get_boundary() returns a boundary for a given instance
api_get_camera_position() api_get_cam returns a coordinate of the current camera position
api_get_data() returns the mods own JSON datafile
api_get_definition() returns the dictionary definition for a given oid
api_get_equipped() returns the currently equipped item (mouse or hotbar), if any
api_get_filename() returns the file the player is currently playing in
api_get_floor() returns the floor tile oid of the flooring at a given position, if any
api_get_flowers() returns a list of instances for all the active flowers onscreen
api_get_game_size() returns the current size of the game window, taking game scale into account
api_get_ground() returns the ground oid of the ground at a given position
api_get_highlighted() returns a currently highlighted instance, if any
api_get_inst() returns an instance specified by id
api_get_inst_in_rectangle() returns a list of instance in a given rectangle boundary
api_get_inst_in_circle() returns a a list of instance in a given circle boundary
api_get_key_down() returns if a key is currently being held down
api_get_key_pressed() returns if a key is currently being pressed
api_get_language() returns the current player's selected language, i.e. "en"
api_get_menu_objects() returns a list of instances for all active menu objects, both onscreen and "working" offscreen
api_get_menus_obj() returns the menu object inst for a given menu inst
api_get_mouse_inst() returns the mouse inst id for the global mouse instance
api_get_mouse_position() returns a coordinate of the current mouse position
api_get_mouse_tile_position() returns a coordinate of the current mouse tile
api_get_objects() returns a list of instances for all active objects onscreen
api_get_player_instance() returns the player instance id
api_get_player_position() returns a coordinate of the player's current position
api_get_player_tile_position() returns a coordinate of the player's current tile
api_get_property() api_gp returns a property value for a given instance
api_get_slot() returns a slot for a specific index from a menu object
api_get_slot_inst() returns a slot for a speicifc slot inst id
api_get_slots() returns a list of slots for a menu object
api_get_sprite() returns a sprite reference for a given oid
api_get_time() returns a time of the current game time
api_get_trees() returns a list of instances for all the active trees onscreen
api_get_weather() return a weather of the current game weather

api_get_boundary()

This method allows you to get a bounding box for a given instance - bounding boxes are not always the same as the image themselves for base game objects, but with sprites you have created the box will be automatically created based on the sprite.

Parameter Datatype Description
inst_id integer the instance you want to get the boundary for

Returns either a boundary or nil with one of the following errors logged in the Modding Console:

Error Description
Invalid Instance ID instance id provided is not valid
Instance Not Active instance provided is not active

Example code to get the bounding box of the player:

player_inst = api_get_player_instance()
bounding_box = api_get_boundary(player_inst)

api_get_camera_position()

This method lets you get the camera position. The entire world is made up of objects with a coordinate relative to 0,0 in the top left of the world, but the camera follows around the player to show the view that you see as you walk around.
If you want to draw something within the view you'll need to take into account the camera position.

This method will return a coordinate for the camera position.

Example code to draw a red circle on top of the player:

camera_pos = api_get_camera_position()
player_pos = api_get_player_position()
px = player_pos["x"] - camera_pos["x"]
py = player_pos["y"] - camera_pos["y"]
api_draw_circle(px, py, 100, "FONT_RED", false)

api_get_data()

This method lets you retrieve your mods' data.json file. As file loading needs to be asynchronous, this will callback to the data() hook, so you will need to handle the processing of your data file to do whatever you want to do there.

Example code to get a key from your datafile:

-- call out get data on init()
function init() 
  api_get_data()
end

-- handle callback 
function data(ev, data)
  if ev == "LOAD" then
    my_val = data["my_key"]
  end
end

api_get_definition()

This method lets you get the definition for a given oid from the dictionary based on a given oid.
See your "dictionary.json" file for the sorts of values on these dictionary tables.

Parameter Datatype Description
oid integer the oid to retrieve a dictionary definition for

This function will return either a table or nil if no definition was found.

Example code to get the tooltip from the standard wooden axe:

axe_def = api_get_definition("axe1")
tooltip = axe_def["tooltip"]
api_create_log("axe_tooltip", tooltip)

api_get_equipped()

This allows you to get whatever item is currently equipped by the player - either held in the mouse or in the active hotbar slot. Like in the game, the held mouse item is prioritised over the hotbar.

This method will return a string, with either an oid or empty if there's nothing equipped.

Example code to do something if the player clicks with an axe:

function click()
  -- check whats equipped
  equipped_item = api_get_equipped()
  if equipped_item == "axe1" then
    -- do something with the axe
  end
end

api_get_filename()

This allows you to get the current filename for the file the player is playing. Mods are not file specific so any data you need to store should be based off filename rather than generic.

This method will return a integer, with either 1, 2 or 3.

Example code to do get the current file:

function ready()
  -- check what file we are in
  file = api_get_filename()
end

api_get_floor()

This method gets you the current flooring at a given position.

Parameter Datatype Description
tx integer the x position to check
ty integer the y position to check

This method will return a string with the following values:

Floor OID Description
tile0 empty tile, no floor was found
tile1 wood flooring tile
tile2 wood decoration tile
tile3 wood edging tile
tile4 stone flooring tile
tile5 stone decoration tile
tile6 stone edging tile
tile7 pier flooring tile

Example code to check automatically place pier tiles under the player as they walk if it's empty:

-- get current tile
current_position = api_get_player_tile_position()
current_tile = api_get_floor(current_position["x"], current_position["y"])

-- if not tile7, set to tile7
if current_tile ~= "tile7" then
  api_set_floor("tile7", current_position["x"], current_position["y"])
end

api_get_flowers()

This method gets a list of all the flowers currently onscreen.

Parameter Datatype Description
radius integer [Optional] if specified this method will get all objects within this radius from the player, rather than get all onscreen

This method will return a list of instances, empty if there are no flowers onscreen.

Example code to check how many Honeyrose flowers are around:

flowers = api_get_flowers()
total = #flowers
count = 0
for i=1,total, do
  if flowers[i]["oid"] == "flower1" then 
    count = count + 1
  end
end

api_get_game_size()

This method gets the current game size, taking into account the scaling of the game. You can use this to draw things with the same height or width as the game screen, i.e. for an overlay in the gui() hook.

This method will return an table with a key for width and height, both are an integer.

Example code to draw a black overlay to the game:

function gui()

  -- get sizes
  game = api_get_game_size()

  -- draw black rectangle at 0.9 alpha over entire screen
  api_draw_rectangle(0, 0, game["width"], game["height"], "BLACK", false, 0.9)

  -- draw something on top!

end

api_get_ground()

This method gets the ground oid at the given position. This is the actual land/water oid for the biome at that position.

Parameter Datatype Description
tx integer the x position to check
ty integer the y position to check

This method will return a string with the following values:

Ground OID Description
empty ground, used during worldgen so you shouldn't see this
grass1 grass (forest)
water1 shallow water (forest)
deep1 deep water (forest)
grass2 grass (swamp)
water2 shallow water (swamp)
deep2 deep water (swamp)
grass3 grass (tundra)
water3 ice (tundra)
deep3 deep water (tundra)
grass4 grass (hallow)
water4 shallow water (hallow)
deep4 deep water (hallow)

Example code to turn the ground under the player to water as they walk:

-- get current tile
current_position = api_get_mouse_tile_position()
current_tile = api_get_ground(current_position["x"], current_position["y"])

-- set the forest water if not forest water
if current_tile ~= "water1" then
  api_set_ground("water1", current_position["x"], current_position["y"])
end

api_get_highlighted()

At any given time something is probably being highlighted by the player - this allows you to find out what!
It's worth noting that items are the floating items on the ground - not items in your menus/inventory. For that you want to use slots.

Parameter Datatype Description
inst_type string the type of instance you want to check is highlighted, options are item, obj, menu_obj, menu, slot, ui, wall, carpet, and ground

This method will return an integer of the instance highlighted if any was found, otherwise it will return nil

Example code to check if we are highlighting a sawbench, and add logs to it if we are:

-- check for highlighted menu object
highlighted = api_get_highlighted("menu_obj")

if highlighted ~= nil then 

  -- check if highlighted menu is a sawbench
  inst = api_get_inst(highlighted)
  if inst["oid"] == "sawbench" then 

    -- fill first slot with logs
    api_set_slot(inst["menu_id"], 1, "log", 99)

  end

end

api_get_inst()

This method lets you access an instance's properties by giving its id. GMS is very ID based so a lot of things just rely on IDs in-game, so this method is exposed so you can access the properties we can just get from the ID in GMS internally.

Parameter Datatype Description
inst_id integer an instance id to get the properties for

This method will return a instance if a match is found, otherwise it will return nil

Example code to get the properties of whatever is being highlighted:

-- check for highlighted object
highlighted = api_get_highlighted("obj")

-- get props if object is highlighted
if highlighted ~= nil then
  props = api_get_inst(highlighted)
  oid = props["oid"]
end

api_get_inst_in_rectangle()

This method lets you get a list of instances in a given rectangle boundary.

Parameter Datatype Description
inst_type string the type of instance you want to check is highlighted, options are item, obj, tree, flower and menu_obj
x1 integer left x position of the rectangle box
y1 integer top y position of the rectangle box
x2 integer right x position of the rectangle box
y2 integer bottom y position of the rectangle box

This method will return a list of instances, empty if none are found or if inst_type was invalid

Example code to get all flowers in the 3x3 tile area around the player:

-- get tile to the top-left of player tile
tile = api_get_player_tile_position()
tx = tile - 16;
ty = tile - 16;
-- get flowers in the 3x3 tile area
flowers = api_get_inst_in_rectangle("flower", tx, ty, tx + 32, ty + 32)

api_get_inst_in_circle()

This method lets you get a list of instances in a given circle boundary.

Parameter Datatype Description
inst_type string the type of instance you want to check is highlighted, options are item, obj, tree, flower and menu_obj
x1 integer x center position of the circle
y1 integer y center position of the circle
rad integer radius of the circle

This method will return a list of instances, empty if none are found or if inst_type was invalid

Example code to get all trees in a circle from the mouse when clicked:

function click()
  mouse = api_get_mouse_position()
  trees = api_get_inst_in_circle("tree", mouse["x"], mouse["y"], 64)
end

api_get_key_down()

This method checks if a given key is being held down by the player.

Parameter Datatype Description
key_label string either a key character like "A" or one of the following special labels: LEFT, RIGHT, UP, DOWN, ENTER, ESC, SPACE, SHFT, CTRL, ALT, TAB

This method returns a boolean for whether the key is down or not.

Example code to check if the "Shift" + "A" key is being held down:

a_key_down = api_get_key_down("A")
shift_key_down = api_get_key_down("SHFT")
if a_key_down == 1 and shift_key_down == 1 then
  api_create_log("key_down", "do a shortcut thing!")
end

api_get_key_pressed()

This method checks if a given key has been pressed. This is only triggered once after the player pressed the key - it will not trigger again until the key is released.

Parameter Datatype Description
key_label string either a key character like "A" or one of the following special labels: LEFT, RIGHT, UP, DOWN, ENTER, ESC, SPACE, SHFT, CTRL, ALT, TAB

This method returns a boolean for whether the key was pressed or not.

Example code to check if the "F" key was pressed:

key_pressed = api_get_key_pressed("F")
if key_pressed == 1 then
  api_create_log("key_pressed", "F's in chat")
end

api_get_language()

This method returns the current player's language selection as a 2-digit language code, i.e. "en".

This method returns the current language code, which can be one of the following: en, fr, it, de, es, br, or jp.

Example code to see if the current language is German:

current_lan = api_get_language()
if current_lan == "de" then
  -- hallo!
end

api_get_menu_objects()

This method gets a list of all menu objects either onscreen or "working". All menu objects have a working property, usually set by activity (a queen for Beehives, or logs in a Sawmill) - while working these objects stay active.

Parameter Datatype Description
radius integer [Optional] if specified this method will get all objects within this radius from the player, rather than get all onscreen
oid string [Optional] if specified this method will only return objs with a matching oid (see OID Reference)
coordinate coordinate [Optional] if using a radius, this allows you specify the center point to use. If not given, will default to the player

This method will return a list of instances, empty if there are no menu objects onscreen or working.

Example code to find any basic apiaries nearby:

-- find out how many hives are nearby
objs = api_get_menu_objects()
total = #objs
count = 0
for i=1,total, do
  if objs[i]["oid"] == "hive1" then 
    count = count + 1
  end
end

-- we could do this quicker by specifiying an oid
objs = api_get_menu_objects(nil, "hive1")
count = #objs

api_get_menus_obj()

This method gets the menu object instance from a given menu instance. As you probably realised these are two different things! Menu objects are the objects in the overworld you click on, and when you click on them they open their menu instance.

Parameter Datatype Description
menu_id integer the menu instance to get the menu object inst for

This method will return either the menu object instance ad as a integer, otherwise it will return nil if not valid.

Example code to set an object as immortal when it's menu define is called:

function menu_define(menu_id)
  obj_id = api_get_menus_obj(menu_id)
  api_set_immortal(obj_id, true)
end

api_get_mouse_inst()

This method gets the global mouse instance id, so that you can get or set its properties.
For all purposes you can consider the mouse inst as just a slot, as it has most of the same properties.

This method will return the mouse instance as an instance.

Example code to get the mouse inst and then set the held item to something else:

mouse = api_get_mouse_inst()
api_sp(mouse["id"], "item", "my_fancy_axe")

api_get_mouse_position()

This method gets the current mouse position.

This method will return a coordinate of the current mouse position.

Example code to teleport the player to the mouse position when you click:

function click()
  mouse = api_get_mouse_position()
  api_set_player_position(mouse["x"], mouse["y"])
end

api_get_mouse_tile_position()

This method gets the position of the tile currently underneath the mouse

This method will return a coordinate of the tile under the current mouse position.

Example code to create a crate on the grid under the mouse when you click:

function click()
  mouse_tile = api_get_mouse_tile_position()
  api_create_obj("crate1", mouse_tile["x"], mouse_tile["y"])
end

api_get_objects()

This method gets a list of all objects currently onscreen.

Parameter Datatype Description
radius integer [Optional] if specified this method will get all objects within this radius from the player, rather than get all onscreen
oid string [Optional] if specified this method will only return objs with a matching oid (see OID Reference)
coordinate coordinate [Optional] if using a radius, this allows you specify the center point to use. If not given, will default to the player

This method will return a list of instances, empty if there are no objects onscreen.

Example code to find the first bed nearby, if any, and teleport the player there:

-- get nearby
objs = api_get_objects(nil, "bed")
total = #objs
nearest_bed = nil
if total > 0 then nearest_bed = objs[1]

-- teleport if one was found
if nearest_bed ~= nil then 
  api_set_player_position(nearest_bed["x"], nearest_bed["y"]) 
end

api_get_player_instance()

This method gets the player instance. For pretty much all intents and purposes the player counts as a very fancy menu object that you can retrieve the slots for as you would any other menu object.
There's a whole bunch of properties on the player instance needed to run the game, set properties on this instance at your own risk!
Here's some default properties that might be useful to retrieve with api_get_property():

Property Datatype Description
name string the player's name
money integer the amount of rubees the player has
honeycore integer the amount of honeycore the player has
dir string the direction the player is facing, either left or right
sitting boolean whether the player is sitting on a bench
sleeping boolean whether the player is sleeping
sailing boolean whether the player is in a boat
hotbar integer the index of the slot the player has active in their hotbar, from 0-9
current_tile string the current ground oid beneath the player (see [[#{{{i}}}|{{{i}}}]] for oid names)

This method will return a integer of the player instance id.

Example code to get all the slots of the player inventory:

player = api_get_player_instance()
slots = api_get_slots(player)

api_get_player_position()

This method gets the player position, relative to 0,0 in the top left of the world.

This method will return a coordinate of the current player position

Example code to put a workbench near the current player position:

player = api_get_player_position()
api_create_obj("workbench", player["x"] + 16, player["y"] - 32)

api_get_player_tile_position()

This method gets the position of the tile the player is currently on, relative to 0,0 in the top left of the world.

This method will return a coordinate of the tile under the current player position

Example code to put a workbench on the tile under the player position:

player = api_get_player_tile_position()
api_create_obj("workbench", player["x"], player["y"])

api_get_property()

This method will get a given property from an instance. You can also use the shorthand "api_gp()" for this method.
See Instance Properties for a full list of all built-in properties for all types of instances.

Parameter Datatype Description
inst_id integer instance id to get a property for
prop_name string name of the property to try and get

This method could return any datatype, depending on the property that you ask for. If it fails for some reason it will return nil and log one of the following errors to the Modding Console:

Error Description
Instance Doesn't Exist instance id provided doesn't exist, or is not active
Instance Property Doesn't Exist instance property with the name given doesn't exist

Example code to find out how much money the player has, and give them $100 if they don't have any:

player = api_get_player_instance()
money = api_gp(player, "money")
if money == 0 then
  api_give_money(100)
end

api_get_slot()

This method will get a slot from a given menu based on it's slot index. To make things easier, all slot indexes in the API start at 1, to match LUA lists starting at 1.

Parameter Datatype Description
menu_id integer menu instance to get a slot from
slot_index integer index of the slot to get, starting at 1

This method will return a slot_instance if found, otherwise it will return nil

Example code to get the first player slot:

player = api_get_player_instance()
first_slot = api_get_slot(player, 1)
api_log("player_first_slot", first_slot["item"])

api_get_slot_inst()

This method will get a slot based on it's instance id, instead of needed to provide a menu_id and slot_index like the method above.
This is useful for using it with api_get_highlighted to save you getting the menu details first.

Parameter Datatype Description
slot_id integer slot instance to get properties for

This method will return a slot_instance if found, otherwise it will return nil

Example code to check if the slot we are highlighting contains an axe:

highlight = api_get_highlighted("slot")
if highlight ~= nil then
  slot = api_get_slot_inst(highlight)
  -- now we have slot details
  if slot["item"] == "axe1" then
    -- do something
  end
end

api_get_slots()

This method is similar to the previous one, except it gets all of the slots for a given menu.

Parameter Datatype Description
menu_id integer menu instance to get a slot from

This method will return a list of slot_instance if a valid menu object, otherwise it will return nil

Example code to get all of the player slots and fill them with logs, then set the first slot to be a bee:

-- get player slots
slots = api_get_slots(api_get_player_instance())

-- set all slots to be filled with logs (you're welcome)
for i=1,30 do
  api_slot_set(slots[i]["id"], "log", 99)
end

-- set first slot to be a common bee
api_slot_set(slots[1]["id"], "bee", 0, api_create_bee_stats("common", false))

api_get_sprite()

This method will return a sprite id for a given oid. This can be for an item/object you have defined, a sprite you have defined, or for a standard game oid.
You need to prepend the oid with "sp_", for example sp_axe1.
You can get bee sprites with by using the following format: sp_bee_common

Parameter Datatype Description
oid string sprite to get the reference for (see OID Reference)

This method will return a integer for the sprite id if found otherwise it will return nil

Example code to get the common bee sprite and draw with it:

-- var to store the sprite for later
spr_id = nil

function init() 
  -- get the common bee sprite
  spr_id = api_get_sprite("sp_bee_common")
end

function draw()
  -- draw the sprite at a position
  api_draw_sprite(spr_id, 0, 100, 50)
end

api_get_time()

This method will get the current game time, current day, as well as some other useful information.

This method will return a time.

Example code to get the current day:

time = api_get_time()
day = time["day"]
if day == 7 then 
  api_log("time", "it's day 7!")
end

api_get_trees()

This method will get all the trees currently onscreen.

Parameter Datatype Description
radius integer [Optional] if specified this method will get all objects within this radius from the player, rather than get all onscreen

This method will return a list of instances, empty if there are no trees onscreen (Hivemother forbid).

Example code to see how many trees are onscreen:

trees = api_get_trees()
total = #trees

api_get_weather()

This method will get the current weather, and the weather duration. Weather is generic and either on or off - the biome decides the type of weather visuals to show.

This method will return a weather

Example code to get see if it's raining or snowing:

weather = api_get_weather()

-- get current tile under player
player = api_get_player_tile_position()
current_tile = api_get_ground(player["x"], player["y"])

-- check rain or snow
if current_tile == "grass3" or current_tile == "water3" or current_tile == "deep3" then
  -- it's snowing
else
  -- it's raining
end

Mainlander Money Item.pngGive Methods

Give methods allow you to give things directly to the player, be it items or money.

Method Description
api_give_honeycore() gives an amount of Honeycore to the player
api_give_item() gives an amount of a specific item to the player
api_give_money() gives an amount of Rubees to the player

api_give_honeycore()

Gives a certain amount of Honeycore to the player.

Parameter Datatype Description
amount integer the amount to give
-- give 10 honeycore
api_give_honeycore(10)

api_give_item()

Gives a certain amount of a specific item to the player.

Parameter Datatype Description
item_oid string the item oid to give
amount integer the amount to give
-- give 9999 logs
api_give_item("log", 9999)

api_give_money()

Gives a certain amount of Rubees to the player.

Parameter Datatype Description
amount integer the amount to give
-- give 420 money
api_give_money(420)

Skipper.pngMisc Methods

These are misc. methods that don't fit in with one general theme and act as helpers.

Method Description
api_add_slot_to_menu() tries to add the contents of a given slot to a given menu
api_blacklist_input() blacklists a specific object oid from input meaning normal key presses are ignored while its menu is highlighted
api_check_discovery() checks if a player has discovered (picked up) a given item
api_choose() picks randomly from a list of items and returns the result
api_destroy_inst() destroys an instance permanently
api_http_request() sends a HTTP request to a specific endpoint
api_inst_exists() checks if an inst exists
api_library_add_book() adds a book button to the bottom library bar, with custom click script (this does not define a book for you)
api_play_sound() plays a given game sound
api_random() returns a random number between 0-X, where X is given
api_random_range() returns a random number between a range or X-Y, where X and Y are given
api_refresh_tooltip() refreshes the tooltip cache to update with new values (if any)
api_remove_gui() removes a menu gui instance made with api_define_gui()
api_toggle_menu() toggles a menu instance to be open or closed
api_unlock_quest() unlocks a specified quest based on it's given quest id

api_add_slot_to_menu()

This method lets you attempt to add the contents of a slot to a given menu. If there is any "leftover" it will remain in the slot - for example if you tried adding 99 logs to the player menu, but could only fit 50, the remaining 49 logs would still be in the slot.

This method will validate the contents of your slot for you, and find the first valid slot to try and add the item to (this is the method that default shift-clicking uses in-game)

Parameter Datatype Description
slot_id integer the slot id of the slot you want to move the contents for
menu_id integer the menu id of the menu inst you want to try and move the slot contents to

Example code to move the contents of the player's first slot into another menu:

player = api_get_player_instance()
player_slots = api_get_slots(player)

api_add_slot_to_menu(player_slots[1]["id"], MY_OTHER_MENU_ID)

api_blacklist_input()

This method lets block standard input while a specific object's menu is open. This is useful for being able to handle your own keyboard input without various key presses opening menus or books.
The "Escape" key (or whatever is mapped to menu close) is the only exception not blacklisted.

Parameter Datatype Description
oid string the object oid you want to blacklist from input, should be a menu_object oid (see OID Reference)

Example code to blacklist input on a custom defined menu object:

api_blacklist_input("custom_sign")

api_check_discovery()

This method lets you check if the player has discovered a given item based on it's oid. This lets you know if they've ever picked up a specific item or gives an idea of rough progress.

Parameter Datatype Description
oid string the item oid you want to check discovery for (see OID Reference)

This method will return a boolean based on whether the item is discovered or not.

Example code to check the discovery of a few items:

unlocked_dream_bee = api_check_discovery("bee:dream")

unlocked_honeycore_axe = api_check_discovery("axe3")

unlocked_bee_book = api_check_discovery("book2")

api_choose()

This method picks randomly from a list of items you give it and returns the result.

Parameter Datatype Description
items list list of items you want to pick from

Example code to pick from 3 items:

-- pick a random item from a pool
item_to_give = api_choose({"axe1", "log", "planks1"})

api_destroy_inst()

This method will destroy a given instance, assuming it exists.

Parameter Datatype Description
inst_id integer the id of the instance you want to destroy

This method either returns Success if the request was sent, otherwise if it fails it will return nil and will log an error in the Modding console with one of the following errors:

Error Description
Invalid Instance ID instance given does not exists

Example code to delete all trees onscreen as you walk:

function tick()
  trees = api_get_trees()
  len = #trees
  for i=1,len do
    api_destroy_inst(trees[i]["id"])
  end
end

api_http_request()

This method will send a HTTP request to a given endpoint.

You will need to implement the http() hook to handle the response as this is an asynchronous call.

Parameter Datatype Description
url string the full URL to send the HTTP request to
method_type string the HTTP method type, i.e. GET or POST
headers table a map of headers to apply to your request
body string a body to send with the request (can just be an empty string)

This method either returns Success, otherwise if it fails it will return nil and will log an error in the Modding console with one of the following errors:

Error Description
Failed To Send Request generic catch-all, check your parameters

Example code to handle some random HTTP call to get the APICO website homepage:

-- call our HTTP req whereever we like
function init()
  api_http_request("https://apico.buzz", "GET", {}, "", "my_request")
  return "Success"
end

-- http requests are async so you'll need the http() hook to handle the response
function http(response_id, status, response)

  -- check the response_id and status before handling the response body
  if response_id == "my_request" and status == "Success" then
    api_log("http", response)
  end
  
end

api_inst_exists()

This method will check if a given instance ID exists or not. This method will also return false if the instance in question has been deactivated off screen, as for all intents and purposes GMS sees this as not existing too.

Parameter Datatype Description
inst_id integer the id of the instance you want to check exists

This method returns a boolean based on if the instance was found or not.

Example code to check a saved instance id exists still:

inst = MY_SAVED_INST
if (api_inst_exists(inst)) then
  -- do something cool
end

api_library_add_book()

This method will create a book "button" and add it to the bottom library bar. Clicking this button will run the script given to it.

Note: This will NOT define a book for you, you must handle that yourself. See the Sample Mod for an example book implementation.

Parameter Datatype Description
book_name string a unique name for the book across all mods, used to identify the script to run so can be anything you like
book_script string script to be run when the book is clicked, must be in your mod code somewhere
book_sprite string relative path of the sprite you want to use for the book button, should be a 32/18 image with 2 frames (normal, undiscovered)

This method either returns Success, otherwise if it fails it will return nil and will log an error in the Modding console with one of the following errors:

Error Description
Book Sprite Not Found sprite path could not be resolved
Book Name Already Used book name parameter already used by another mod (or you called this method twice)

Example code to add a book button that calls a custom script:

-- define a new book somewhere
api_library_add_book("my_sweet_book", "book_open", "sprites/book_button.png")

-- run your book "logic" when clicked, in this case we are using a custom menu object
-- that has been defined and stored as MY_BOOK_MENU, which we toggle to be open
function book_open()
  api_toggle_menu(MY_BOOK_MENU, true)
end

api_play_sound()

This method will play a given sound from the base game sounds.

Parameter Datatype Description
name string the sound name to play, current options are break, click, confetti, error, jingle, open, plop, pop, or rollover

This method either returns Success, otherwise if it fails it will return nil and will log an error in the Modding console with one of the following errors:

Error Description
Invalid Instance ID instance given does not exist

Example code to delete all trees onscreen as you walk:

function tick()
  trees = api_get_trees()
  len = #trees
  for i=1,len do
    api_destroy_inst(trees[i]["id"])
  end
end

api_random()

This returns a random number between 0 and the number you give it

Parameter Datatype Description
max integer the max number to be returned

Example code to get a number between 0 and 9:

-- get a number between 0-9
random_number = api_random(9)

api_random_range()

This returns a random number between a given range of numbers.

Parameter Datatype Description
start_num integer number for range to start at
end_num integer number for range to end at

Example code to get a number between 5 and 10:

-- get a random number between 5 and 10
random_number = api_random_range(5, 10)

api_refresh_tooltip()

Tooltips get cached and don't update unless the mouse moves onto something new, which can be a problem with directly changing slot or object values.
Calling this method will reset the cache and make a new tooltip.

Example code to refresh the tooltip after a click:

function click()

  api_refresh_tooltip()

end

api_remove_gui()

This destroys a GUI instance created with api_define_gui(). This is seperate to api_destroy_inst because we need to dereference the "gui_key" off of the menu that you defined the GUI on in the first place.

Parameter Datatype Description
menu_id integer the menu inst ID that you defined the GUI on in the first place
gui_key string the gui key you used when defining the GUI

This method either returns Success, otherwise if it fails it will return nil and will log an error in the Modding console with one of the following errors:

Error Description
Menu Instance Not Found instance given does not exist
GUI Key Empty/Undefined no GUI instance found (already removed) or gui key is incorrect

Example code to remove an existing custom GUI:

api_remove_gui(MY_MENU_ID, "custom_button_thing")

api_toggle_menu()

This lets you force a menu to be open or closed. Note: this needs the menu_id not the menu_obj_id so be sure to pass the correct id for it to work!

Parameter Datatype Description
menu_id integer the menu instance to open or close
toggle string how you want to toggle the menu, either open or close

Example code to open a menu when highlighting the object and pressing "X":

function click(button, click_type)
  -- check we pressed the x key
  if api_get_key_pressed("X") == 1 then

    -- open the highlighted menu obj with x
    highlight = api_get_highlighted("menu_obj")
    if highlight ~= nil then
      -- toggle menu needs a menu id, this is automatically stored as "menu" on a menu obj inst
      menu_id = api_gp(highlight, "menu");
      api_toggle_menu(menu_id, true)
    end

  end
end

api_unlock_quest()

This lets you force unlock a quest you have defined (or a vanilla one!)
Note: This will always fail in the init() hook for custom quests! You need to use it in the ready() hook or later hooks, as the custom quest is only given progress values once the init is finished for all mods.

Parameter Datatype Description
quest_id string the quest id used when defining your quest

This method either returns Success, otherwise if the quest id wasn't found it will return nil.

Example code to unlock a defined quest:

function init() 
  -- create quest definition
  quest_def = {
    id = "my_new_quest",
    title = "My New Quest",
    reqs = {"planks1@10"},
    icon = "planks1",
    reward = "axe2@1",
    unlock = {},
    unlocked = true
  }
  
  -- create quest pages 
  quest_page1 = {
    { text = "Hello this is my quest" },
    { text = "This line is BLUE", color = "FONT_BLUE" }
  }
  quest_page2 = {
    { text = "This is cool have a free reward" }
  }
  
  -- define quest
  api_define_quest(quest_def, quest_page1, quest_page2)

  return "Success"
end

function ready()
  -- unlock quest
  unlock = api_unlock_quest("my_new_quest")
end

Workbench Item.pngMod Methods

Mod methods let you call other mods that may or not be loaded. You should check a mod exists first in the ready() hook before attempting to interact with it.

Method Description
api_mod_exists checks if a given mod exists / is loaded
api_mod_call calls a function from another mod and returns the result

api_mod_exists()

This checks is a given mod exists and is registered and initialised correctly.

Parameter Datatype Description
mod_name string the unique mod name for the mod

This method returns a boolean based on whether the mod exists or not.

Example code to check if another mod exists:

-- check in the ready hook as we know at that point all mods that can load are loaded
function ready() 
  -- check if mod exists
  if api_mod_exists("my_other_mod") == nil then
    api_log("ready", "mod doesn't exist oh no what do we do!")
  end
end

api_mod_call()

This lets you call a function from another mod assuming that mod exists

Parameter Datatype Description
mod_name string the unique mod name for the mod
method_name string the method to call in the other mod's file
args list [Optional] a list of args to pass in

This method either returns whatever the other mods method returns, otherwise if it fails it will return nil and will log an error in the Modding console with one of the following errors:

Error Description
Failed To Invoke Method if the function call fails this will detail the issue it came across

Example code to call a function from another mod:

-- check in the ready hook as we know at that point all mods that can load are loaded
function ready() 
  -- check if mod exists
  if api_mod_exists("my_other_mod") ~= nil then
    data = api_mod_call("my_other_mod", "some_other_method", {1, 2})
  end
end

Stone Axe Item.pngSet Methods

Set methods let you set properties or values, like setting the player position or changing the time of day.

Method Description
api_set_blueprint() overrides the worldgen blueprints with your own custom blueprint
api_set_data() sets the mods own JSON datafile
api_set_devmode() toggles devmode in the game, turning on FPS meter + allowing inline commands
api_set_floor() sets the floor tile at a given position
api_set_ground() sets the ground at a given position
api_set_immortal() sets a menu object to be "immortal" meaning it'll stay active regardless of it it's no longer working
api_set_menu_position() sets the position of a menu instance, updating any gui/buttons for you
api_set_notification() sets a notification to show to the player
api_set_player_position() sets the player's position
api_set_position() sets the position for a given instance id
api_set_property() api_sp sets a property on a given instance id
api_set_spawn() sets the player spawn position which is used if the player gets stuck
api_set_time() sets the game time
api_set_tooltip() sets the tooltip for a given oid's dictionary definition
api_set_weather() sets the game weather

api_set_blueprint()

This method allows you to override the default worldgen pattern with your own blueprint, meaning you can create custom worlds - even more so when used alongside custom logic in a worldgen() hook.
For reference, game worlds are 350x350 tiles, with 290x290 being visible on the map and rest being reserved for secret areas.
This must be called in the init() hook to work.

Parameter Datatype Description
blueprints list(blueprint) the blueprints you want to use, each blueprint being a "blob" of land you define
blank list(boolean) if true this will mean that no objects are created during the worldgen, giving you an entirely blank world with only grass/water

Example code to change the worldgen to just be one big tundra island:

blueprint = {}
blueprint[1] = {
  width = 200,
  height = 200,
  x = 50,
  y = 50,
  type = "snow",
  dye = 15
}
api_set_blueprint(blueprint, false)

api_set_data()

This method allows you to set the contents of your mods data.json file that you can retrieve through api_get_data(). This lets your store data across sessions - you can use the save() hook to check when the player or game has saved.
As file load/save is asynchronous you will need to use the data() hook to handle the response to check if it worked.

Parameter Datatype Description
json_data table a table of data that will be turned into JSON

This method will either return Success if everything worked, otherwise if it fails it will return nil and will log an error in the Modding console with one of the following errors:

Error Description
Invalid JSON String the table you provided couldn't be parsed into valid JSON

Example code to save some data to the data.json file:

-- function that saves the data
function save_data() 
  my_json = {hello="World"}
  api_set_data(my_json)
end

-- handle data hook response
function data(ev, data)
  if ev == "SAVE" then
    if data == nil then
      -- failed to save!
    end
  end
end

api_set_devmode()

Your other best friend along with api_create_log(), this method toggles the devmod. We'd recommend just having this on the whole time you work on your mod as it gives you access to the In-Game Console which can be opened with / and let's you run commands like /gimme log 5 or /weather on.
It will also show the FPS meter so you can check performance.

Parameter Datatype Description
dev_mode boolean whether to turn dev mode on or off.

Example code to turn on devmode when the mod initialises:

function init()
  api_set_devmode(true)
end

api_set_floor()

This method sets the floor tile at a given position.

Parameter Datatype Description
floor_oid string the floor oid to set, see below for details
tx integer the x position to set the tile, will be rounded to the grid
ty integer the y position to set the tile, will be rounded to the grid

This following floor oids are available to use:

Floor OID Description
tile0 empty tile, no floor
tile1 wood flooring tile
tile2 wood decoration tile
tile3 wood edging tile
tile4 stone flooring tile
tile5 stone decoration tile
tile6 stone edging tile
tile7 pier flooring tile

If this method fails it will log an error in the Modding console with one of the following errors:

Error Description
Invalid Floor ID you didn't use one of the floor oids listed above

Example code to set the floor underneath the player to tiles (auto-tiler, nice!):

-- get current tile
current_position = api_get_player_tile_position()
current_tile = api_get_floor(current_position["x"], current_position["y"])

-- set to pier tiles if there is no tile
if current_tile == "tile0" then
  api_set_floor("tile7", current_position["x"], current_position["y"])
end

api_set_ground()

This method lets you set the actual ground at a given position. The ground oid is what determines the biome the player or bees are in.

Parameter Datatype Description
ground_oid string the ground oid you want to set
tx integer the x position to set the tile, will be rounded to the grid
ty integer the y position to set the tile, will be rounded to the grid

This following ground oids are available to use:

ground OID Description
empty ground, used during worldgen so you shouldn't see this
grass1 grass (forest)
water1 shallow water (forest)
deep1 deep water (forest)
grass2 grass (swamp)
water2 shallow water (swamp)
deep2 deep water (swamp)
grass3 grass (tundra)
water3 ice (tundra)
deep3 deep water (tundra)
grass4 grass (hallow)
water4 shallow water (hallow)
deep4 deep water (hallow)

If this method fails it will log an error in the Modding console with one of the following errors:

Error Description
Invalid Tile ID you didn't use one of the ground oids listed above

Example code to set the ground beneath the player to swamp grass:

-- get player position
current_position = api_get_mouse_tile_position()
current_tile = api_get_ground(current_position["x"], current_position["y"])

-- set to swamp grass if its not already
if current_tile ~= "grass2" then
  api_set_ground("grass2", current_position["x"], current_position["y"])
end

api_set_immortal()

All instances in the game get deactivated offscreen - with the exception of menu objects if they are still "working". If you have a menu object that needs to stay active regardless of whether it is onscreen or working, you can set this property to true.
The more menu objects active the lower the performance over time - do not have 100s of menu objects immortal if you want a good time.

Parameter Datatype Description
menu_obj_id integer the id of the menu object instance you want to immortalise
bool boolean whether to set the property to true or false

This method will either return Success if everything worked, otherwise if it fails it will return nil and will log an error in the Modding console with one of the following errors:

Error Description
Instance Doesn't Exist given instance id does not exist, or isn't active (which would be ironic)
Instance Is Not A Menu Object given instance id is not a menu object - only menu objects can be immortal

Example code to click on a crate with a special item to make the crate immortal so we can access it anywhere in the world:

function click()

  -- get highlighted obj
  menu_obj = api_get_highlighted("menu_obj")

  -- get equipped
  equip = api_get_equipped()

  -- if we click on a crate with a custom item we defined make it immortal
  if menu_obj ~= nil and equip == "sample_mod_magic_wand" then
    inst = api_get_inst(menu_obj)
    if inst["oid"] == "crate1" then
      api_set_immortal(inst["id"], true)
    end
  end
end

api_set_menu_position()

This method lets you manually set the position of a menu if you need to. Usually the menu position is set when the object is clicked on and the menu will either be opened next to the object, or in the centre of the screen depending on the [[#{{{i}}}|{{{i}}}]]'s "center" property.
Combined with [[#{{{i}}}|{{{i}}}]] this would allow you to open a menu object from anywhere and show the menu anywhere.

Parameter Datatype Description
menu_id integer the menu you want to move (note: not the menu object id)
mx integer the x position you want to move the menu to
my integer the y position you want to move the menu to

This method will either return Success if everything worked, otherwise if it fails it will return nil and will log an error in the Modding console with one of the following errors:

Error Description
Menu Instance Doesn't Exist given menu instance id

Example code to open and move a previously created menu objects menu:

-- toggle a previous created and stored menu object
api_toggle_menu(my_menu_obj, "open")

-- move the now open menu to the camera position
cam = api_get_camera_position()
menu_id = api_gp(my_menu_obj, "menu")
api_set_menu_position(menu_id, cam["x"], cam["y"])

api_set_notification()

This method lets you set your own notification, either with a standard notification type of your own custom notification type.
The standard notifications just have their own click actions, i.e. clicking a flower notification opens the flower book. Your own notification type can have it's own click action when defined in api_define_notification()

Parameter Datatype Description
notification_type string a notification type, either your own or one of the standard types: workbench, quest, bees, microscope, flowers, weather, altar, buff, mag, notice
item_oid string the item oid to show in the notification icon (see OID Reference)
title string the title to show in the notification
msg string the message to show in the notification

Example code to piggyback the "notice" type notification to show our own message:

api_set_notification("notice", "axe3", "You are cool", "You are so damn cool")

api_set_player_position()

This method lets you set the players current position. After moving the player it will automatically update the camera, like the game does when using beds or gates.

Parameter Datatype Description
px integer the x position you want to set
py integer the y position you want to set

Example code to teleport the player the mouse position when clicking:

function click()
  mouse = api_get_mouse_tile_position
  api_set_player_position(mouse["x"], mouse["y"])
end

api_set_position()

This method lets you set the position of any given instance.

Parameter Datatype Description
inst_id integer the instance you want to move
px integer the x position you want to set
py integer the y position you want to set

This method will either return Success if everything worked, otherwise if it fails it will return nil and will log an error in the Modding console with one of the following errors:

Error Description
Instance Doesn't Exist instance id given doesn't exist, or isn't active

Example code to move whatever is highlighted to a random position on the map:

-- get a random tile on the map
random_x = api_random(290)*16
random_y = api_random(290)*16

-- move the highlighted object, if any, to that position
highlighted = api_get_highlighted("obj")
api_set_position(highlighted, random_x, random_y)

api_set_property()

This method allows you to set a property on an instance so you can use it later. You can also use the "api_sp()" shorthand.
When setting custom properties on menu objects you should add the prop_name to the related menu's menu._fields list key if you want to keep it persistent when the player saves (see api_define_menu_object() for an example)
See Instance Properties for a full list of all built-in properties for all types of instances.

Parameter Datatype Description
inst_id integer the instance you want to set a property for
prop_name string the name of the property you want to set
prop_value Any the value for the property

This method will either return Success if everything worked, otherwise if it fails it will return nil and will log an error in the Modding console with one of the following errors:

Error Description
Instance Doesn't Exist given instance id doesn't exist or isn't active
Instance Property Doesn't Exist property you want to set does not exist
Invalid Value For Property property value given wasn't valid - not sure why you'd get this but good to know I guess?

Example code to cycle through the highlighted objects sprite frames:

function tick() 
  highlighted = api_get_highlighted("obj")
  if highlighted ~= nil then
    api_sp(highlighted, "image_index", api_gp(highlighted, "image_index") + 1)
  end
end

api_set_spawn()

This method sets the spawn position for the player. The spawn is used whenever the player is stuck in deep water, and by default is on the pier by Skipper and then set when a bed is used.

Parameter Datatype Description
px integer the x position you want to set
py integer the y position you want to set

Example code to set the spawn position:

api_set_spawn(100, 100)

api_set_time()

This method lets you update the in-game time, either to a set time or a raw time in ms

Parameter Datatype Description
time string a preset time point in the day to use, options are dawn_start, dawn_mid, day_start, dusk_start, dusk_mid, night_start, or night_end
raw_ms integer [Optional] instead of a preset you can set a raw time in ms - see time for more info

This method will either return Success if everything worked, otherwise if it fails it will return nil and will log an error in the Modding console with one of the following errors:

Error Description
Invalid Time Value time value set wasn't from the list of options above

Example code to the time to 8am:

-- one game hour is 60000ms (1 minute)
time = 60000 * 8
api_set_time("", time)

api_set_tooltip()

This method lets change the dictionary tooltip for a given oid's definition. You can use this to make dynamic tooltips for different objects.

Parameter Datatype Description
oid string the oid of the definition you want to update, i.e. axe1
tooltip string the tooltip string you want to use instead

This method will either return Success if everything worked, otherwise if it fails it will return nil and will log an error in the Modding console with one of the following errors:

Error Description
Definition For OID Doesn't Exist given oid is not defined in the dictionary

Example code to change the tooltip for the spade:

api_set_tooltip("spade1", "Diggy diggy hole")

api_set_weather()

This lets you update the weather in game by specifying the start and end times of the weather. The weather is reset at the end of the day.
The type of weather is based on the biome the player is currently in, weather as a property is either on or off.

Parameter Datatype Description
start_time integer the time in ms for the weather to start - see time for more info
end_time integer the time in ms for the weather to end - see time for more info

Example code to make it rain between 7am and 10am:

-- one game hour is 60000ms (1 minute)
start_time = 60000 * 7
end_time = 60000 * 10
api_set_weather(start_time, end_time)

Frame1 Item.pngSlot Methods

Slot methods let you easily interact with slots, which is useful for any sort of custom menu object logic.

Method Description
api_slot_clear() clears a slot and makes it empty
api_slot_decr() decreases a slot amount, if reduced to 0 the slot will be cleared
api_slot_drain() starts a drain action with a given slot, draining the menu's tank into this slot
api_slot_fill() starts a fill action with a given slot, filling the menu's tank from this slot
api_slot_incr() increases a slot amount, capped at 99
api_slot_item_id() gets a special item data id for a given slot, mainly used by Ell in his weird mods
api_slot_match() finds a slot/slots that match certain criteria based on the items they have (or dont have)
api_slot_match_range() same as above but specifies a range of slots that the match will check instead of all menu slots
api_slot_set() sets a slot to have a specific item in it
api_slot_set_inactive() sets a slot to be inactive (no hover or click interactions)
api_slot_set_modded() sets a slot to be modded (hover interactions but no click interactions)
api_slot_redraw() redraws a slot and it's item
api_slot_validate() validates a given item/stats combination for a given slot

api_slot_clear()

This method will clear a given slot, making it empty.

Parameter Datatype Description
slot_id integer the slot id of the slot instance you want to clear

If this method worked it will return Success, otherwise if it fails it will return nil and will log an error in the Modding Console with one of the following errors:

Error Description
Failed To Clear Slot generic error catch, shouldn't really see this.

Example code to clear the first slot of the menu object that's been clicked on:

function click() 

  -- see if we clicked on a menu object
  menu_obj = api_get_highlighted("menu_object")
  if menu_obj ~= nil then

    -- get the menu object menu id
    menu_id = api_get_inst(menu_obj)["menu_id"]

    -- get the first slot and clear it
    slot_id = api_get_slot(menu_id, 1)
    api_slot_clear(slot_id)

  end

end

api_slot_decr()

This method will decrease a slot count by the amount given, or 1 if no amount specified. If the slot count is reduced to 0 the slot will be cleared automatically.

Parameter Datatype Description
slot_id integer the slot id of the slot instance you want to clear
amount integer [Optional] amount to decrease by, defaults to 1

If this method worked it will return Success, otherwise if it fails it will return nil and will log an error in the Modding Console with one of the following errors:

Error Description
Failed To Decrease Slot generic error catch, shouldn't really see this.

Example code to reduce the amount of the first player slot:

-- get player slots
slots = api_get_slots(api_get_player_instance())

-- reduce whatever is in the first slot by 2, if anything
api_slot_decr(slots[1]["id"], 2)

api_slot_drain()

This method will drain a menu's tank into the given slot, assuming the slot has something it can drain into (canister1 or canister2).
This method will only work with a slot that is part of a menu you defined a tank on with api_define_tank.

Parameter Datatype Description
menu_id integer the menu id for the slot you want to drain into, this menu must have a tank defined
slot_index integer the slot index in the menu you want to drain to, starting at 1

If this method worked it will return Success, otherwise if it fails it will return nil and will log an error in the Modding Console with one of the following errors:

Error Description
Menu Instance Doesn't Exist given menu instance doesn't exist.

Example code to drain water from a tank into a slot when the slot has a canister put in it:

function sample_menu_define(menu_id) 
  -- define a tank gui
  -- tank props are automatically saved for you so you dont need to add anything to _fields
  api_define_tank(menu_id, 1000, 2000, "water", 4, 14, "xlarge")
end

-- handle slot change to drain water into a canister
function sample_menu_change(menu_id)

  -- check if we have a canister, if so try and drain to the canister
  slot = api_get_slot(menu_id, 1)
  if slot["item"] == "canister1" or slot["item"] == "canister2" then
    api_slot_drain(menu_id, 1) -- handles the rest
  end

end

api_slot_fill()

This method will fill a menu's tank into the given slot, assuming the slot has something it can fill from (canister1 or canister2).
This method will only work with a slot that is part of a menu you defined a tank on with api_define_tank.

Parameter Datatype Description
menu_id integer the menu id for the slot you want to fill into, this menu must have a tank defined
slot_index integer the slot index in the menu you want to fill from, starting at 1

If this method worked it will return Success, otherwise if it fails it will return nil and will log an error in the Modding Console with one of the following errors:

Error Description
Menu Instance Doesn't Exist given menu instance doesn't exist.

Example code to drain water from a tank into a slot when the slot has a canister put in it:

function sample_menu_define(menu_id) 
  -- define a tank gui
  -- tank props are automatically saved for you so you dont need to add anything to _fields
  api_define_tank(menu_id, 1000, 2000, "water", 4, 14, "xlarge")
end

-- handle slot change to drain water into a canister
function sample_menu_change(menu_id)

  -- check if we have a canister, if so try and drain to the canister
  slot = api_get_slot(menu_id, 1)
  if slot["item"] == "canister1" or slot["item"] == "canister2" then
    api_slot_fill(menu_id, 1) -- handles the rest
  end

end

api_slot_incr()

This method will increase a slot count by the amount given, or 1 if no amount specified. It will cap out automatically at 99.

Parameter Datatype Description
slot_id integer the slot id of the slot instance you want to clear
amount integer [Optional] amount to increase by, defaults to 1

If this method worked it will return Success, otherwise if it fails it will return nil and will log an error in the Modding Console with one of the following errors:

Error Description
Failed To Increase Slot generic error catch, shouldn't really see this.

Example code to increase the amount of the second player slot:

-- get player slots
slots = api_get_slots(api_get_player_instance())
  
-- increase whatever is in the second slot by 2, if anything
api_slot_decr(slots[2]["id"], 2)

api_slot_item_id()

If you want to get the type of bee in a slot and have the slot instance already just look at the slot's stats property! This method is intended for situations where you have only have slot ID, and not the slot instance from say api_get_slot().
If you've ever dug around in the dictionary you've probably seen stuff like "bee:common" or "frame:filled". For some items we have some stat properties that are pretty important for game function, and we use these special "data id"s to represent that.

This method returns the slots current item as a data id, if applicable, saving you having to get the slot instance and read off it's stats prop.

Parameter Datatype Description
menu_id integer the menu inst that the slot belongs to
slot_index integer the index of the slot you want to get, starting at 1

If this method worked it will return a string with the data id or OID, empty if no item is present in this slot.

Example code to get the item id for the first slot in the players menu:

-- get player slots
slots = api_get_slots(api_get_player_instance())
  
-- get item id for this slot
item_id = api_slot_item_id(slots[1]["id"])
if (item_id == "bee:common") then
  -- do something with a common bee
end

api_slot_match()

This method allows you to find a slot or slots that match a given item criteria you define. This is useful to get slots that already have a given item, or say return the first slot that's empty.

Parameter Datatype Description
menu_id integer the menu instance you want to find matches on
match list(string) a list of item values you want to match on, can be an item oid, "ANY" (for any item), or "" for blank
first_only boolean [Optional] if true, this method will return the first slot only rather than a list of matches

If you specify "first" to be true, this method will either return a slot_instance or nil if no match was found. If you don't specify "first" or set it to be false this method will return a list of slot_instance, just empty if no matches were found.

Example code to get various slot matches from the player inventory:

-- get player inst
player_id = api_get_player_instance()

-- find the first slot with logs in
first_slot = api_slot_match(player_id, {"log"}, true)

-- find all empty slots
empty_slots = api_slot_match(player_id, {""})

api_slot_match_range()

This is the same as api_slot_match() except you can specify the range of slot indexes to match from rather than all the slots.

Parameter Datatype Description
menu_id integer the menu instance you want to find matches on
match list(string) a list of item values you want to match on, can be an item oid, "ANY" (for any item), or "" for blank (see OID Reference)
range list(integer) a list of slot indexes to check. Indices start at 1 like LUA lists do
first_only boolean [Optional] if true, this method will return the first slot only rather than a list of matches

If you specify "first" to be true, this method will either return a slot_instance or nil if no match was found. If you don't specify "first" or set it to be false this method will return a list of slot_instance, just empty if no matches were found.

Example code to get various slot matches from the player inventory:

-- get player inst
player_id = api_get_player_instance()

-- find the first slot from the first four slots with planks or sticks in
first_slot = api_slot_match_range(player_id, {"planks1", "sticks1"}, {1, 2, 3, 4}, true)

-- find all non-empty slots in between the 5th and 8th slots
empty_slots = api_slot_match(player_id, {"ALL"}, {5, 6, 7, 8})

api_slot_set()

This method lets you set the contents of a slot manually, overriding anything in that slot.

Parameter Datatype Description
slot_id integer the slot id of the slot instance you want to set
item_oid string the item oid you want to set in the slot (see OID Reference)
amount integer the amount of the item you want to set. If setting a singular item this will be ignored
stats stats [Optional] a stats obj to use, can be one you got from api_create_bee_stats() or a custom one

If this method worked it will return Success, otherwise if it fails it will return nil and will log an error in the Modding Console with one of the following errors:

Error Description
Failed To Set Slot Failed to set slot, potentially a bad item oid

Example code set all the slots in the player inventory to logs (you are welcome):

-- get player slots
slots = api_get_slots(api_get_player_instance())

for i=1,30 do
  api_slot_set(slots[i]["id"], "log", 99)
end

api_slot_set_inactive()

This method lets you set a slot to be inactive. Inactive slots can't be highlighted/hovered, are not drawn, and can't be clicked on.
A good use case would be one menu with two sets of slots you want to hide or show at any given time without having to re-create slots.

Parameter Datatype Description
slot_id integer the slot id of the slot instance you want to set
inactive boolean whether to set the slot as inactive or not

If this method worked it will return Success, otherwise if it fails it will return nil and will log an error in the Modding Console with one of the following errors:

Error Description
Slot Instance Doesn't Exist Failed to set slot property as slot doesn't exist

Example code set all the slots in the player inventory to inactive (you are welcome):

-- get player slots
slots = api_get_slots(api_get_player_instance())

for i=1,30 do
  api_slot_set_inactive(slots[i]["id"], true)
end

api_slot_set_modded()

This method lets you set a slot to be 'modded'. Modded slots CAN be highlighted/hovered but they can't be clicked on.
This allows you to handle your own click logic for the slot.

Parameter Datatype Description
slot_id integer the slot id of the slot instance you want to set
modded boolean whether to set the slot as modded or not

If this method worked it will return Success, otherwise if it fails it will return nil and will log an error in the Modding Console with one of the following errors:

Error Description
Slot Instance Doesn't Exist Failed to set slot property as slot doesn't exist

Example code set all the slots the first slot in the player inventory as modded:

-- get player slots
slots = api_get_slots(api_get_player_instance())
api_slot_set_modded(slots[1]["id"], true)

api_slot_redraw()

This method lets you redraw a given slot, which will redraw any highlighting and the item in the slot. This allows you to do custom draw logic in your menu_draw scripts, while then still being able to layer the slot drawing on top.

If wanting to redraw all the slots for a menu you should use api_draw_slots for performance reasons!

Parameter Datatype Description
slot_id integer the slot id of the slot instance you want to redraw

Example code to draw a sprite and then redraw a slot in a custom menu_draw script:

function my_custom_menu_draw(menu_id)

  -- get menu position
  mx = api_gp(menu_id, "rx")
  my = api_gp(menu_id, "ry")
  slots = api_get_slots(menu_id)

  -- draw a sprite on the menu
  api_draw_sprite(SPR_REF, 0, mx, my)

  -- redraw the first slot ontop
  api_slot_redraw(slots[1]["id"])

end

api_slot_validate()

You may have noticed that if you just use api_set_property() on a slot you can put anything in it - this method lets you validate a given item/stat combination to see if it is allowed in a given slot first. This lets you check if that slot can take this item (i.e. checking if Dye can go in the first slot of a Sawbench would fail, as only logs and planks are allowed in that slot).

This does not actually move the item into the slot, just a read-only check.

Parameter Datatype Description
slot_id integer the slot id of the slot instance you want to validate agaisnt
item string the item oid you want to put in the slot, i.e. "axe4" (see OID Reference)
stats table the stats for the item you want to put in the slot, can be an empty table if no stats needed

This method will return a boolean, true if the item/stats combination you passed can go in the slot.

Example code to see if we can add a Bee into a Sawbench (spoilers, you can't)

-- get our slots
sawbench_slots = api_get_slots(MY_SAWBENCH_MENU_ID)

-- check if we could put a bee in this slot
check = api_slot_validate(sawbench_slots[1]["id"], "bee", BEE_STATS)

-- if the test fails, do something
if (check == false) then
  api_log("test", "nope you can't do that")
end

Mainlander Money Item.pngTake Methods

Take methods allow you to take currency from the player.

Method Description
api_take_honeycore() takes an amount of Honeycore from the player
api_take_money() takes an amount of a money from the player

api_take_honeycore()

Takes a certain amount of Honeycore from the player.

Parameter Datatype Description
amount integer the amount to take
-- take 10 honeycore
api_take_honeycore(10)

api_take_money()

Takes a certain amount of Rubees from the player.

Parameter Datatype Description
amount integer the amount to take
-- take 69 money
api_take_money(69)

Paintbrush Item.pngUse Methods

Use methods let you mess around with the items a player has so that you can emulate items being used up, like when you craft an item or when dye is used by a paintbrush.

Method Description
api_use_item() uses up a certain amount of an item from the players inventory and open menus
api_use_total returns the total amount of an item currently in the players inventory and open menus

api_use_item()

This method will use up a certain amount of an item from the players inventory and open menus, like how the paintbrush uses up dye or the workbench uses up items while crafting.
You should use api_use_total() to check what the player has first!

Parameter Datatype Description
item_oid string the item to use up (see OID Reference)
amount integer the amount to use up

Example code to use up 1 log every second:

function clock()
  -- check if the player has logs to use
  if api_use_total("log") > 0 then
    -- sorry player your log is mine
    api_use_item("log", 1)
  end
end

api_use_total()

This method returns the total amount of an item currently in the players inventory and open menus.

Parameter Datatype Description
item_oid string the item to use up (see OID Reference)

This method returns an integer for the amount of the given item available.

Example code to check for an amount of planks and give the player more planks if under a certain amount:

-- find out how many sticks the player has and if less than 10 give them 10
if api_use_total("planks1") < 10 then
  api_give_item("planks1", 10)
end