Modding API

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, butterflies 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
Multiplayer Methods	Methods to check if the player is in a multiplayer game
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.

Standard 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

Custom 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
alchemy_count	Represents the current alchemy pot when checking combinations through api_define_incense()
bee_definition	Represents a definition for a new social bee
butterfly_definition	Represents a definition for a new butterfly
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
dialogue	Represents an NPCs dialogue tree
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 DEPRECATED	Represents a definition for a new NPC (deprecated in v2.1.0+)
npc_definition2	Represents a definition for a new NPC (v2.1.0+)
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
sbee_definition	Represents a definition for a new solitary bee
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

alchemy_count

Represents the current "counts" of each element in the alchemy bench

Key	Datatype	Description
f	integer	total "flower" elements - any flowers or seeds count as this element
b	integer	total "bee" element - any bee products count as this element
n	integer	total "nature" element - any naturally found items, logs, flora, acorns etc
m	integer	total "man-made" element - any man-made items (this is a catch all for any item not in the other element types)
h	integer	total "hallowed" element - any hallowed items, apise, dye10, dye18, honeycore, blessed pearls
g	integer	total "glitched" element - any glitched items, currently just cubes and random jelly

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

butterfly_definition

Represents a definition for a new butterfly. This will add an entry into the butterfly book.

Key	Datatype	Description
id	string	lowercase unique name for your butterfly, i.e. flutterby, used for progress
title	string	name of your butterfly for tooltips + books, i.e. Flutterby
latin	string	the latin name for your butterfly, 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
biome	string	the biome this butterfly spawns in, valid options are Forest, Swamp, Snow, Hallow, and Devland
lifespan	integer	a lifespan value to use for the butterfly, chrysalis lifespan is always half the butterfly species
behaviour	string	a behaviour trait this species will spawn with, valid options are Diurnal, Nocturnal, Crepuscular, Cathemeral
climate	string	a climate trait this species will spawn with, valid options are Temperate, Tropic, Polar, Any
rainlover	boolean	whether this species likes rain
snowlover	boolean	whether this species likes snow
flora	string	the OID of the specific flora item that this butterfly's caterpiller will eat as food
flowers	list(string)	a list of two flower OIDs that will represent the flower "likes" a butterfly has
chance	integer	the chance this butterfly will spawn naturally if the conditions are met
named	boolean	whether this butterfly is a "named" species - named species will not get "Butterfly" appended to their species name, i.e. Speckled Butterfly (not named) vs Lesser Dreamer (named)

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

dialoguetree

Dialogue Trees represents an NPCs dialogue tree. You can have as many keys as you want, however you need at least an "A" key to be valid. See the example in api_define_npc2()

Key	Datatype	Description
A	dialogue	the first dialogue option an NPC has
*	dialogue	as long as you have an "A" you can add as many new sections as you like

dialogue

Dialogue represents a section of dialogue in a tree. Each dialogue has a prompt, and then a list of NPC dialogue along with related actions. See the example in api_define_npc2()

Key	Datatype	Description
P	string	the prompt the player will see for this dialogue section
D	list(string)	a list of dialogue strings that will represent "screens" of dialogue the player can click through
A	list(string)	a list of dialogue actions to match each of the dialogue "screens" - you need to match the number of strings in D. Options are either $action01 (Next) or $action49 (Back) which should be the last action in the list. Yes I could of make this less complicated for a first pass however how does the idea of custom modded actions sound allowing you to give the player stuff when talking to an NPC? Yeah thats what I thought so shush you

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 wrapper representation of any instance. All instance types have the same properties, albeit some will be nil (and so won't be returned). See Instance Properties for more specific information on what special properties certain instance types have.

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 (see OID Reference). This will be nil on item/slot instances, you need to get the "item" property (see Instance Properties)
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
effect	string	[Optional] used by custom incense items defined in api_define_incense() to show the "effect" when the incense is in a burner

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", "canisterX", "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

This definition was deprecated in v2.1.0+ and you should use now use npc_definition2!
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

npc_definition2

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(dialoguetree)	a special table that represents an NPCs dialogue tree
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

sbee_definition

Represents a definition for a new solitary bee. This will add an entry into the solitary bee book.

Key	Datatype	Description
id	string	lowercase unique name for your bee, i.e. daycrawler, used for progress
title	string	name of your bee for tooltips + books, i.e. Daycrawler
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
biome	string	the biome this bee spawns in, valid options are Forest, Swamp, Snow, Hallow, and Devland
behaviour	string	a behaviour trait this species will spawn with, valid options are Diurnal, Nocturnal, Crepuscular, Cathemeral
climate	string	a climate trait this species will spawn with, valid options are Temperate, Tropic, Polar, Any
rainlover	boolean	whether this species likes rain
snowlover	boolean	whether this species likes snow
produce	string	the OID of the item this bee will leave as a gift when in habitats
specials	list(string)	a list of up to two item OIDs that the solitary bee will need along with flora to appear
chance	integer	the chance this bee will spawn naturally if the conditions are met

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

Hooks

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)
fields	table	a table containing the values a menu object's menu's "_fields" object (if the destroyed obj was a menu object) - limited to non-nested datatypes

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

function destroy(id, x, y, oid, fields) 

  -- 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, "BLACK", false)
  
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

All 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

Create 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_butterfly()	creates a butterfly instance that can be netted by the player
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_lightweight()	creates a "lightweight", a special type of instance used for batch drawing
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_butterfly()

As you (hopefully) have noticed by now, butterflies can spawn on other things - not just flowers. If you've defined a butterfly that you want to be non-traditional with it's flower choices, the default game handler is not going to naturally spawn these butterflies for you. To solve this problem, this method will let you spawn a butterfly onto a given object! Butterflies spawned this way will last for 5-10m unless despawned by the game (i.e. cos the weather changes)

Parameter	Datatype	Description
species	string	the species of butterfly to spawn, i.e. speckled
weather	string	the type of weather for this butterfly - once the game weather no-longer matches what you pass in, the butterfly will despawn. Values allowed are snow, rain or an empty string
inst_id	integer	the instance to spawn the butterfly on, can be a flower, tree, generic obj, menu obj, or a wall

Example code to spawn a speckled butterfly on whatever the player clicks on:

function click()

  -- check not using a net lol
  equipped_item = api_get_equipped()
  highlighted = api_get_highlighted("obj")
  if highlighted ~= nil and equipped_item ~= "net" then

    -- if an obj has a butterfly it has a property called butterfly that you can check
    -- if the value is nil there is currently no butterfly
    -- use this to prevent spawning multiple on the same instance (as a player will only be able to net the first one the rest will get stuck on the obj)
    has_butt = api_gp(highlighted, "butterfly")
    if has_butt == nil then 
      api_create_butterfly("speckled", "", highlighted)
    end

  end

end

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_lightweight()

When it comes to drawing stuff through the API, you might notice that drawing hundreds of sprites can quickly degrade performance. This is due to a couple of reasons but ultimately boils down to it not being very efficient to draw lots of sprites every frame through the API.

This is where lightweights come in - these are special "lightweight" instances that can be created on different layers and are drawn automatically by the game. You can create hundreds of lightweights and not have to worry about the performance hit you'd see if you just did a for loop with api_draw_sprite().

Lightweights are not saved/loaded, they are destroyed at the end of a session!

Parameter	Datatype	Description
type	string	the layer the lightweight should be drawn on, options are tile (above tiles but below objects), obj (above objects), or gui (above menus). This cannot be changed later
sprite_ref	integer	the sprite index to use for drawing, needs to be the actual index not a string
frame	integer	the frame of the sprite to draw (see Instance Properties for how to update this later)
x	integer	the x position to create the lightweight at
y	integer	the y position to create the lightweight at

This will return the newly created lightweight instance id as a integer, which you can use with api_get_property() to update the values later if you need to.

Example code to create 100 lightweights that will draw a bee randomly near the player:

-- get position
p = api_get_player_position()

-- get the bee particle sprite
bee_spr = api_get_sprite("sp_b_particle")

-- make 100 lightweights at random positions
-- we dont need to handle the drawing it's done automatically
-- doing this with api_draw_sprite() 100 times in a draw hook would be way worse for performance
for i=1,100 do
  api_create_lightweight(
    "obj", 
    bee_spr, 
    0, 
    p["x"] + api_random_range(-32, 32),
    p["y"] + 8 + api_random_range(-32, 32)
  )
end

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

Define 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 social 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_butterfly()	defines a new species of butterfly for the game
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_incense()	defines a new incense item, as well as it's alchemy recipe
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() DEPRECATED	defines a new menu object for the game like a Workbench or a Beehive (Deprecated in v2.1.0+)
api_define_menu_object2()	defines a new menu object for the game like a Workbench or a Beehive (v2.1.0+)
api_define_notification()	defines a new notification type along with a dismiss script for when it's clicked
api_define_npc() DEPRECATED	defines a custom npc with dialogue and optionally a shop (Deprecated in v2.1.0+)
api_define_npc2()	defines a custom npc with dialogue and optionally a shop (v2.1.0+)
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_solitary()	defines a new species of solitary bee for the game
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_butterfly()

This allows you to define a custom butterfly that can then be spawned in, either naturally by the game when the conditions are met, or manually via api_create_butterfly().

Parameter	Datatype	Description
butt_def	butt_definition	the butterfly definition to be used to create the new species
butt_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)
butt_golden_image	string	relative path of the sprite you want to use for the golden variant, should be a 72x18 image with 4 frames (normal, normal highlighted, undiscovered, undiscovered highlight)
butt_cat_image	string	relative path of the sprite you want to use for the caterpiller, should be a 18x18 image with 1 frame (normal)
butt_hd_image	string	relative path of the sprite you want to use for the "HD" butterfly image in the book, should be a 96x48 image with 2 frames (normal, undiscovered)
butt_color	color	a color to use for the butterfly, used in 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 (KEY)	a value is missing from your butt_definition
Butterfly With This ID Exists	there is already a butterfly defined with this ID
Biome specified is not valid	the biome given in your definition isn't valid
Butterfly Sprites Not Found (PATH)	One or more sprite paths could not be resolved
Failed To Map Keys	Generic catch all, will also log an exception error afterwards to explain the problem

Example code to create a new fancy butterfly:

-- set up our butterfly definition 
butt_def = {
  id = "flutterby",
  title = "Flutterby",
  latin = "Fluttery Buttery",
  hint = "Really likes green flowers but during a wet dawn!",
  desc = "This is just a cool damn butterfly",
  biome = "forest",
  lifespan = 120,
  behaviour = "Crepuscular",
  climate = "Temperate",
  rainlover = true,
  snowlover = false,
  flora = "flora1",
  flowers = {"flower4", "flower17"},
  chance = 50,
  named = true
}

-- actually define the butterfly 
api_define_butterfly(butt_def, 
  "sprites/bee/bee_item.png", "sprites/bee/bee_shiny.png", 
  "sprites/bee/bee_item.png",
  "sprites/bee/bee_hd.png",
  {r=100, g=100, b=100}
);

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_incense()

This allows you to define a custom incense item and add it to the game. You do not need to use api_define_item() to make the incense item as this method will do that for you.
The defined incense will NOT have your mod_name prepended to it, so it will be created as "incense777" not "my_mod_incense777".
This method does not create an effect, you must implement this yourself using methods like api_has_incense().

Parameter	Datatype	Description
item_def	item_definition	an item definition for your incense using standard definition keys (this is also where "effect" is used in the item_definition)
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)
alchemy_check	string	a method name defined in your mod code that will be used to check if the combination the player has in their alchemy bench will create your incense. This method will be passed the current incense oid that will be combined currently, along an alchemy_count table

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:

-- method to define your incense
function define_incense()

  item = {
    id = "incense777",
    name = "JACKPOT",
    category = "Incense",
    effect = "Money gained from sold items is doubled",
    tooltip = "Made from 4 greens and 1 red!",
    durability = 60,
    singular = true
  }

  api_define_incense(item, "sprites/item/axe_item.png", 'combine_incense777')


end

-- a function to decide if our incense should be made
-- this function must return a table containing an "oid" and a "level"
-- the "level" is used to set the duraction of the incense bottle (level*2*60s)
-- in vanilla the level is dictated by how much excess material you've added 
function combine_incense777(current_oid, counts)

  -- in this case if we have 4 or more "nature" items (green)
  -- and 1 or more "flower" items (red)
  -- then our incense will be made instead 
  if (counts.n >= 4 and counts.f >= 1) then
    return {
      oid = "incense777",
      level = 2 -- (2*2*60) = 240s duration 
    }
  end
  return nil

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 method was deprecated in 2.1.0+ and you should use now api_define_menu_object2()!
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.

Once the slots for your menu object are defined you can further modify their properties, see Instance Properties.

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

api_define_menu_object2()

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.

Once the slots for your menu object are defined you can further modify their properties, see Instance Properties.

Parameter	Datatype	Description
menu_def	menu_definition2	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 2 frames (normal, 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 method was deprecated in 2.1.0+ and you should use now api_define_npc2()!
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 18x14 image with 1 frame
bust_sprite	string	relative path to the sprite you want to use for this item, should be a 64x36 image with 2 frames (normal, bought "happy" face)
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 32x16 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

api_define_npc2()

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_definition2	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 18x14 image with 1 frame
bust_sprite	string	relative path to the sprite you want to use for this item, should be a 64x36 image with 2 frames (normal, bought "happy" face)
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 32x16 image with 2 frames (normal, normal highlighted)
dialogue_bg_sprite	string	relative path to the sprite you want to use for this NPCs dialogue menu bust background, should be a 48x38 image with 1 frame
shop_bg_image	string	relative path of the sprite you want to use for the NPCs shop menu bust background, should be a 39x39 image with 1 frame
dialogue_check	string	the name of a script in your mod code that will be called to decide which dialogue options to show (see example below)

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:

-- define the actual NPC
function define_npc()
  -- setup dialogue tree
  dialogue = {}
  dialogue["A"] = {
    P = "I am a prompt for dialogue A!",
    D = {
      "I am the first paragraph for dialogue A",
      "All NPCs need at least a dialogue A or they break",
      "This is a chance for you to introduce an NPC",
      "Goodbye!"
    },
    A = {
      "$action01",
      "$action01",
      "$action01",
      "$action49"
    }
  }
  dialogue["B"] = {
    P = "I am a new prompt for dialogue B!",
    D = {
      "Well done on getting a glossy pearl!"
    },
    A = {
      "$action49"
    }
  }
  
  -- define npc obj
  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", "log", "log"},
    specials = {"log", "log", "log"},
    dialogue = dialogue,
    greeting = "Default greeting!!"
  }
  
  -- define actual npc, damn thats a lot of sprites
  api_define_npc2(npc_def,
    "sprites/npc2/npc_standing.png",
    "sprites/npc2/npc_standing_h.png",
    "sprites/npc2/npc_walking.png",
    "sprites/npc2/npc_walking_h.png",
    "sprites/npc2/npc_head.png",
    "sprites/npc2/npc_bust.png",
    "sprites/npc2/npc_item.png",
    "sprites/npc2/npc_dialogue_bg.png",
    "sprites/npc2/npc_shop_bg.png",
    "npc69_dialogue_check"
  )
end

-- function used with the dialogue check 
-- by default "A" will always be selected
-- using this function you can return the other dialogue tree keys to return 
-- based on certain conditions, i.e. item discovery or progress
function npc69_dialogue_check()

  if api_check_discovery("glossypearl") then
    return {'B'}
  end
  return {}

end

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_solitary()

This method let's you define your own solitary 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
sbee_def	sbee_definition	the solitary 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_letter_image	string	relative path of the sprite you want to use for the bee's letter item, should be a 32x16 image with 2 frames (normal, highlighted)
bee_letter_text	string	text to show in the letter for this species

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 produce item given in the definition doesnt exist
Biome specified is not valid	the biome given is not a valid biome
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 
sbee_def = {
  id = "daycrawler",
  title = "Daycrawler",
  latin = "Crawly Daily",
  hint = "Found on only the lightest of days",
  desc = "This is just a cool damn bee",
  biome = "forest",
  behaviour = "Diurnal",
  climate = "Temperate",
  rainlover = false,
  snowlover = false,
  produce = "log",
  specials = {"log"},
  chance = 50
}

-- create new bee
-- in this example we have a "sprites" folder in our mod root
api_define_solitary(sbee_def, 
  "sprites/bee_item.png", "sprites/bee_shiny.png", 
  "sprites/bee_hd.png",
  {r=100, g=100, b=100},
  "sprites/bee/bee_letter.png",
  "This is some letter text!"
);

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

Describe 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_butterflies()	returns a list of all butterflies 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_butterflies()

This method returns all the butterfly definitions 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 table containing all the butterfly definitions for the base game, with a key for each butterfly species (i.e. "speckled"). See your "butterflies.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 butterfly definitions underneath that.

Example code to get some specific oid definitions from dictionaries:

-- get a base game bee definition
game_dictionary = api_describe_butterflies(false)
speckled_definition = game_dictionary["speckled"]
api_log("speckled details!", speckled_definition)

-- get a mod bee definition
my_mod = "sample_mod"
mod_dictionary = api_describe_butterflies(true)
my_mod_dictionary = mod_dictionary[my_mod]
my_butt_definition = my_mod_dictionary["flutterby"]
api_log("flutterby details!", my_butt_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)

Draw 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
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
outline	boolean	whether to draw an outline instead of a filled circle
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

Get 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_zoid_from_inst()	return a ZOID for a given instance ID, a unique identifier that works across sessions
api_get_inst_from_zoid()	returns an instance ID for a given ZOID

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

api_get_zoid_from_inst()

This method will get a ZOID for a given instance. A ZOID is a unique combination of an instances' X, Y, and OID (x-y-oid => zoid). This is used by multiplayer to handle the fact that GameMaker instance IDs are not unique across games (or even sessions in SP). By using ZOIDs you can ensure you always work with the same instance across multiple reloads.

This method will return a string containing a ZOID. The format of the ZOID depends on the instance type:
- Trees: "TREE-x-y"
- Items: "ITEM-oid-x-y"
- Walls: "WALL-oid-x-y"
- Objects: "oid-x-y"
- Menu Objects: "oid-x-y"

Example code to get the ZOID of something you have clicked on:

function click()

  equipped_item = api_get_equipped()
  highlighted = api_get_highlighted("obj")
  if highlighted ~= nil then
    zoid = api_get_zoid_from_inst(highlighted)
    api_log('clicked zoid is: ', zoid)
  end

end

api_get_inst_from_zoid()

This method will give you the instance ID that matches a given ZOID (if there is one). You should use api_get_zoid_from_inst() to get the ZOID in the first place rather than build the string manually.

This method will return a integer containing an instance ID.

Example code to get the instance ID from a ZOID and log it's OID:

zoid = "100-103-sawbench" -- retrieved from somewhere

inst_id = api_get_inst_from_zoid(zoid)

if inst_id ~= nil then
  inst = api_get_inst(inst_id)
  api_log('retrieved inst is: ', inst["oid"])
end

Give 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)

Misc 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_game_state()	returns the current game state (paused, saving etc)
api_get_progress()	returns the players current progress
api_has_incense()	returns whether there is a given scent as a certain position
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_measure_text()	measures some given text to give you the width/height it'll take up when drawn with api_draw_text()
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_game_state()

This method will return the "state" of the game, including if the game is paused, saving, generally loading, or a world is loading.

This method returns a table containing a key for game_paused, game_saving, game_loading, and world_loading.

Example code to ignore a hook when the game is loading:

function click()

  state = api_game_state()
  if state["game_loading"] ~= true then
    -- allow click if not loading
  end

end

api_get_progress()

This method will return the current progress of the player, including bees, butterflies, and flowers.

This method returns a table containing a lot of keys that I CBA explaining (just log them!), but the important info is q_* is quests, b_* is bees, f_* is flowers, bu_* is butterflies, and bb_* is solitary bees.

Example code to give the player a little treat if they've discovered 30 flowers:

progress = api_get_progress()

flowers_discovered = progress["f_count"]
if flowers_discovered > 30 then
  -- give a little treat
  api_give_item("log", 9999)
end

api_has_incense()

This method will return whether there is a given scent at a certain position. This is so you can implement your own incense effects when making new incense with api_define_incense().

Parameter	Datatype	Description
x	integer	x position to check
y	integer	y position to check
incense_oid	string	the oid of the incense you want to check for i.e. "incense1"

This method returns a boolean based on whether the scent was found at the given position.

Example code to check if the object that was clicked on has a given incense affecting it:

function click()

  highlighted = api_get_highlighted("obj")
  if highlighted ~= nil then
    has_incense = api_has_incense(api_gp(highlighted, "x"), api_gp(highlighted, "y"), "incense888")
    if has_incense then
      -- clicked object is being affected by incense888! wahoo!
    end
  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_measure_text()

This method will return the width and height of a given text string when drawn with api_draw_text(). This lets you easily handle drawing multiple different coloured texts across multiple lines by letting you know what space will be taken up when the text is drawn.

Parameter	Datatype	Description
text	integer	the text to draw
tw	integer	[Optional] a width to apply to the text, causing extra text to wrap onto the next line

This method returns a table containing a key for width and a key for height, both being the width and height that the text will take up when drawn at a given position.

Example code to draw 2 different coloured sentances at a fixed width across multiple lines:

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
  line1 = "This is a long line of text that will go over multiple lines!"
  line2 = "This is some more text!"
  api_draw_text(px, py, line1, false, "FONT_BLUE", 100)

  -- measure our first line to work out the offset to draw the next line
  size = api_measure_text(line1, 100)
  py = py + size["height"]
  api_draw_text(px, py, line2, false, "FONT_GREEN")

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	boolean	how you want to toggle the menu, true to open, false to 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

Mod 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

Multiplayer Methods

Multiplayer methods let you check the current status of the game to see if the player is part of a multiplayer game.

Method	Description
api_multiplayer_is_mp()	checks if player is in a multiplayer game (joining or hosting)
api_mutliplayer_is_joined()	checks if the player is currently in a hosted game
api_mutliplayer_is_hosting()	checks if the player is currently hosting a game
api_mutliplayer_get_host_uuid()	returns the host's UUID for a MP game

api_multiplayer_is_mp()

This method checks whether the player is currently in a multiplayer game.

This method returns a boolean that will be true if the player is currently in a hosted game or hosting a game.

Example code to check if we are in multiplayer:

-- if multiplayer
if api_multiplayer_is_mp() == true then

  -- run some MP specific logic
  define_fancy_party_item()

end

api_multiplayer_is_joined()

This method checks whether the player is currently in a multiplayer game, specifically that they have joined a game NOT hosting.

This method returns a boolean that will be true if the player is currently in a game hosted by another player.

Example code to check if we have joined a hosted game:

-- if joining a host game
if api_multiplayer_is_joined() == true then

  -- give the joining player some money, as a treat
  api_give_money(9999)

end

api_multiplayer_is_hosting()

This method checks whether the player is currently in a multiplayer game, specifically that they are hosting a game.

This method returns a boolean that will be true if the player is currently hosting their game.

Example code to check if we are hosting a game:

-- if we are hosting our game
if api_multiplayer_is_hosting() == true then

  -- give the host some money, as a treat
  api_give_money(9999)

end

api_multiplayer_get_host_uuid()

Every player has a UUID, which is used primarily in multiplayer to identify avatars. When you join a hosted game, your character progress is stored in your "players.json" file, under the UUID of the friend who's game you joined.

This method can be useful to help you store mod-specific data agaisn't a specific hosted game, as when joining a hosted game api_get_filename() just returns whatever file is pre-loaded without accounting for any multiplayer shenanigans.

This method returns a string, empty if the player is not in multiplayer game or if the player is hosting.

Example code to handle mod-specific data in SP vs MP:

data_key = ""

-- if we are joining a game
if api_multiplayer_is_joined() == true then
  data_key = api_mutliplayer_get_host_uuid()
else
  data_key = api_get_filename()
end

-- set some data to that key
GLOBAL_DATA[data_key] = "something to load later!"

Set 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)

Slot 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

Take 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)

Use 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