main.html

__NOTOC__
{{#seo:|
  description=Pssssstt hey kids wanna learn some APIs|
  image=https://static.miraheze.org/apicowiki/5/5f/Thumbnail-Modding.png|
}}
<div class="aw aw-api">

  <div class="aw-panel">

    <div class="aw-panel--left">
      <p>Welcome to the API reference for APICO! This API is split up into a bunch of sections listed below, each with an overview table.</p>
      <p>You can toggle the details of each section, which contain further information and examples, with the <nowiki>[Expand Details]</nowiki> button.</p>
      <p>If you're looking for info on how to start making mods, check out out [[Modding Guide|Getting Started]] section.</p>
      <p>For any of the {{I|i=api_define_*}} methods you can check out the [https://github.com/APICO-Modders/APICO-Sample-Mod Sample Mod] on GitHub for sprite examples.
    </div>

    <div class="aw-panel--right">
      <div class="aw-info">
        <p class="h"><i>Modding</i></p>
        <p class="sh">API Reference</p>
      </div>
    </div>

  </div>

  {| class="wikitable"
   ! Section !! Description 
   |-
   | [[#Standard Datatypes|Standard Datatypes]] || LUA datatypes that are referenced in the API
   |-
   | [[#Custom Datatypes|Custom Datatypes]] || Custom datatypes (LUA tables) that are referenced in the API
   |-
   | [[#Hooks|Hooks]] || Custom hooks your mod can implement to react to certain game events or cycles
   |-
   | [[#All Methods|All Methods]] || Methods to get all instances of specific types
   |-
   | [[#Create Methods|Create Methods]] || Methods to create new instances or effects
   |-
   | [[#Define Methods|Define Methods]] || Methods to define things like items, objects, bees, or recipes
   |-
   | [[#Describe Methods|Describe Methods]] || Methods to describe game metadata like dictionary definitions
   |-
   | [[#Draw Methods|Draw Methods]] || Methods to draw sprites or shapes in draw cycles
   |-
   | [[#Get Methods|Get Methods]] || Methods to get instances or properties
   |-
   | [[#Give Methods|Give Methods]] || Methods to give the player items or money
   |-
   | [[#Misc Methods|Misc Methods]] || Misc. helper methods you may find useful
   |-
   | [[#Mod Methods|Mod Methods]] || Methods to access and call other loaded mod methods
   |-
   | [[#Set Methods|Set Methods]] || Methods to set values or properties
   |-
   | [[#Slot Methods|Slot Methods]] || Methods to help manipulate menu slots
   |-
   | [[#Take Methods|Take Methods]] || Methods to take currency from the player
   |-
   | [[#Use Methods|Use Methods]] || Methods related to using up items the player has
  |}
  <p>Datatypes, like {{D|i=table}}, are in yellow and can be clicked on for more details.<br/>Hooks, like {{H|i=register()}}, are in blue and can also be clicked on for more details.<br/>Methods, like {{F|i=api_create_log()}}, are in orange and can also be clicked on for more details.<br/><br/>Whenever we mentiond an {{I|i=OID}} we are referring to the item's unique game ID, check the [[OID Reference]] for more info.</p>

  <div class="aw-api-section mw-customcollapsible-s1">
    <h1>[[File:Predictor_Item.png|32px]]Standard Datatypes</h1>
    <p>These are all the standard datatypes for LUA used by the API</p>
    {| class="wikitable"
     ! Datatype !! Description 
     |-
     | {{D|i=string}} || standard string datatype
     |-
     | {{D|i=integer}} || standard integer datatype
     |-
     | {{D|i=decimal}} || standard decimal datatype
     |-
     | {{D|i=boolean}} || standard boolean datatype
     |-
     | {{D|i=list}} || standard list/array datatype - list indices start at 1 in LUA!
     |-
     | {{D|i=table}} || 2D array / js object-like datatype, with key-value pairs
    |}
    <div class="mw-collapsible mw-collapsed" id="mw-customcollapsible-s1">
      <h2>string</h2>
      <p>This is a standard string represented by {{I|i="Quotes"}} as in most languages.</p><br/>
      <h2>integer</h2>
      <p>This is a standard integer</p><br/>
      <h2>decimal</h2>
      <p>This is a standard decimal number</p><br/>
      <h2>boolean</h2>
      <p>This is a true/false value, in these docs you will see 0 and 1 used</p><br/>
      <h2>list</h2>
      <p>A list is simply a list of values, represented by {{I|i=<nowiki>{1,2,3}</nowiki>}}. The values inside a list can be any datatype   and don't need to match each other.<br/><b>In LUA, the index for lists starts at 1!!!</b></p><br/>
      <h2>table</h2>
      <p>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 {{I|  i=<nowiki>{name="APICO"}</nowiki>}}.<br/>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"</p><br/>
      <h2>nil</h2>
      <p>This is the null or undefined value in LUA</p>
    </div>
  </div><br/>

  <div class="aw-api-section mw-customcollapsible-s2">
    <h1>[[File:Microscope_Item.png|32px]]Custom Datatypes</h1>
    <p>These are custom "datatypes" to help make the API clearer. In reality all of these datatypes are just {{D|i=table}} elements with different key values set that you can access with {{I|i=datatype["key"]}}</p>
    {| class="wikitable"
     ! Datatype !! Description 
     |-
     | {{D|i=bee_definition}} || Represents a definition for a new bee
     |-
     | {{D|i=blueprint}} || Represents a blueprint instruction for the worldgen
     |-
     | {{D|i=boundary}} || Represents a bounding box for an instance
     |-
     | {{D|i=color}} || Represents a custom RGB color
     |-
     | {{D|i=coordinate}} || Represents an x/y coordinate, relative to the top-left of the world
     |-
     | {{D|i=flower_definition}} || Represents a definition for a new flower
     |-
     | {{D|i=info}} || Represents the help information shown on a menu
     |-
     | {{D|i=ingredient}} || Represents an ingredient for a crafting recipe
     |-
     | {{D|i=instance}} || Represents a generic instance, used for items, objects, buttons, gui, and menu objects
     |-
     | {{D|i=item_definition}} || Represents a definition for a new item
     |-
     | {{D|i=layout}} || Represents a layout of slots for a menu definition
     |-
     | {{D|i=menu_definition}} || Represents a definition for a new menu object
     |-
     | {{D|i=npc_definition}} || Represents a definition for a new NPC
     |-
     | {{D|i=obj_definition}} || Represents a definition for a new object
     |-
     | {{D|i=quest_definition}} || Represents a definition for a new quest
     |-
     | {{D|i=quest_line}} || Represents a page of text for a quest
     |-
     | {{D|i=recipe}} || Represents a crafting recipe for the workbench
     |-
     | {{D|i=scripts}} || Represents a set of scripts for a menu definition
     |-
     | {{D|i=stats}} || Represents the stats property of a slot
     |-
     | {{D|i=slot}} || Represents a slot instance
     |-
     | {{D|i=time}} || Represents the game time
     |-
     | {{D|i=wall_definition}} || Represents a definition for a new wall
     |-
     | {{D|i=weather}} || Represents the game weather
     |-
     | {{D|i=window_definition}} || Represents a definition for a new window
    |}
    <div class="mw-collapsible mw-collapsed" id="mw-customcollapsible-s2">
      <h2>bee_definition</h2>
      <p>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.</p>
      {| class="wikitable"
       ! Key !! Datatype !! Description 
       |-
       | id || {{D|i=string}} || lowercase unique name for your bee, i.e. {{I|i=common}}, used for progress 
       |-
       | title || {{D|i=string}} || name of your bee for tooltips + books, i.e. {{I|i=Common}}
       |-
       | latin || {{D|i=string}} || the latin name for your bee, shown in the book
       |-
       | hint || {{D|i=string}} || the hint to show in the book when this species hasn't been discovered yet
       |-
       | desc || {{D|i=string}} || the description to show in the book when this species has been discovered
       |-
       | lifespan || list({{D|i=string}}) || a list of possible lifespan traits this species can spawn with, value options are {{I|i=Hyper}}, {{I|i=Rapid}}, {{I|i=Short}}, {{I|i=Normal}}, {{I|i=Long}}, {{I|i=Ancient}}, {{I|i=Eternal}}
       |-
       | productivity || list({{D|i=string}}) || a list of possible productivity traits this species can spawn with, value options are {{I|i=Sluggish}}, {{I|i=Slowest}},  {{I|i=Slow}}, {{I|i=Normal}}, {{I|i=Fast}}, {{I|i=Fastest}}, {{I|i=Brisk}}
       |-
       | fertility || list({{D|i=string}}) || a list of possible fertility traits this species can spawn with, value options are {{I|i=Sterile}}, {{I|i=Infertile}}, {{I|i=Unlucky}}, {{I|i=Fertile}}, {{I|i=Fecund}}, {{I|i=Prolific}}, {{I|i=Swarming}}
       |-
       | stability || list({{D|i=string}}) || a list of possible stability traits this species can spawn with, value options are {{I|i=Chaotic}}, {{I|i=Erratic}}, {{I|i=Unstable}}, {{I|i=Normal}}, {{I|i=Stable}}, {{I|i=Ordered}}, {{I|i=Pure}}
       |-
       | behaviour || list({{D|i=string}}) || a list of possible behaviour traits this species can spawn with, value options are {{I|i=Diurnal}}, {{I|i=Nocturnal}}, {{I|i=Crepuscular}}, {{I|i=Cathemeral}}
       |-
       | climate || list({{D|i=string}}) || a list of possible climate traits this species can spawn with, value options are {{I|i=Temperate}}, {{I|i=Tropic}}, {{I|i=Polar}}, {{I|i=Any}}
       |-
       | rainlover || {{D|i=boolean}} || whether this species can work while it's raining
       |-
       | snowlover || {{D|i=boolean}} || whether this species can work while it's snowing
       |-
       | grumpy || {{D|i=boolean}} || whether this species is grumpy and needs to be calmed before being worked with
       |-
       | produce || {{D|i=string}} || the item oid of the item this species' "special produce" that will be created when frames are extracted
       |-
       | chance || {{D|i=integer}} || the chance this bee can be formed when it's the mutation for a hybrid 
       |-
       | requirement || {{D|i=string}} || the requirement for how this bee can be formed when it's the mutation for a hybrid, shown in the Predictor
       |-
       | bid || {{D|i=string}} || a unique 2 character identifier for this species to use for the beebox / beebank storage. The identifier cannot be a number, i.e. {{I|i=01}} as these are reserved by the base game.<br/>This must be unique across all mods, so ask your fellow modders first!
       |-
       | calming || list({{D|i=string}}) || [Optional] if this species is grumpy, you can provide a list of flower oids that calm it, i.e. {{I|i=["flower1", "flower2"]}} (see [[OID Reference]])
       |-
       | tier || {{D|i=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
      |}<br/>
      <h2>blueprint</h2>
      <p>Blueprints represent an instruction for the worldgen. Each Blueprint defines an area in the world to create a blob of land.</p>
      {| class="wikitable"
       ! Key !! Datatype !! Description 
       |-
       | width || {{D|i=integer}} || the width of the blueprint, which effects the blob of land created
       |-
       | height || {{D|i=integer}} || the height of the blueprint, which effects the blob of land created
       |-
       | x || {{D|i=integer}} || the y position in the world to put this blueprint
       |-
       | y || {{D|i=integer}} || the y position in the world to put this blueprint
       |-
       | type || {{D|i=string}} || the type of biome to set for this blueprint, options are "forest", "swamp", "snow", "hallow"
       |-
       | dye || {{D|i=integer}} || [Optional] set a dye to apply to the land and nature items, valid number between 1-16
      |}<br/>
      <h2>boundary</h2>
      <p>Boundaries represent the bounding box for a given instance.</p>
      {| class="wikitable"
       ! Key !! Datatype !! Description 
       |-
       | top || {{D|i=integer}} || the top y position of the bounding box
       |-
       | left || {{D|i=integer}} || the left x position of the bounding box
       |-
       | bottom || {{D|i=integer}} || the bottom y position of the bounding box
       |-
       | right || {{D|i=integer}} || the right x position of the bounding box
      |}<br/>
      <h2>color</h2>
      <p>Colors represent an RGB color that can be defined or passed through the API.</p>
      {| class="wikitable"
       ! Key !! Datatype !! Description 
       |-
       | r || {{D|i=integer}} || the red value of the color
       |-
       | g || {{D|i=integer}} || the green value of the color
       |-
       | b || {{D|i=integer}} || the blue value of the color
      |}<br/>
      <h2>coordinate</h2>
      <p>Coordinates represent an x + y position</p>
      {| class="wikitable"
       ! Key !! Datatype !! Description 
       |-
       | x || {{D|i=integer}} || the x position of this co-ordinate
       |-
       | y || {{D|i=integer}} || the y position of this co-ordinate
      |}<br/>
      <h2>flower_definition</h2>
      <p>Represents a definition for a new flower. Flowers can be picked up, placed, crafted with, and visited by bees.<br/><b>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.</b></p>
      {| class="wikitable"
      ! Key !! Datatype !! Description 
      |-
      | id || {{D|i=string}} || unique ID for this flower - your oid will be a combination of "flower" and your id, i.e. {{I|i=flower69}}
      |-
      | species || {{D|i=string}} || lowercase unique name for your flower, i.e. {{I|i=waspbane}}, used for progress 
      |-
      | title || {{D|i=string}} || name of your flower for tooltips, i.e. {{I|i=Waspbane}}
      |-
      | latin || {{D|i=string}} || the latin name for your flower, shown in the book
      |-
      | hint || {{D|i=string}} || the hint to show in the book when this species hasn't been discovered yet
      |-
      | desc || {{D|i=string}} || the description to show in the book when this species has been discovered
      |-
      | aquatic || {{D|i=boolean}} || whether this flower can be planted / grow on shallow water
      |-
      | deep || {{D|i=boolean}} || [Optional] whether this flower can be planted / grow on deep water
      |-
      | shop_buy || {{D|i=integer}} || [Optional] the amount this flower can be bought for if sold by an NPC
      |-
      | shop_sell || {{D|i=integer}} || [Optional] the amount this flower can be sold for at an NPC
      |-
      | machines || list({{D|i=string}}) || [Optional] a list of object oids that this flower can be used in, i.e. {{I|i=  ["workbench", "sawmill"]}}, shown in tooltips (see [[OID Reference]])
      |-
      | tools || list({{D|i=string}}) || [Optional] a list of tools that can be used on this flower, i.e. {{I|i=["mouse1", "axe1"]}},   shown in tooltips
      |-
      | variants || {{D|i=integer}} || [Optional] specifies the number of variants in your sprite image, defaults to 1
      |-
      | chance || {{D|i=integer}} || [Optional] the chance this species will be formed as a mutation, defaults to 100
      |-
      | smoker || list({{D|i=string}}) || [Optional] a list of bee species that this flower can be used to calm in a smoker, i.e. {{I|i=["stubborn"]}}
      |-
      | has_lighting || {{D|i=boolean}} || [Optional] if true, the flower will light up at night like Pondshine
      |}<br/>
      <h2>info</h2>
      <p>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.<br/>Technically this is a list of values, hence the keys below being numbers.</p>
      {| class="wikitable"
      ! Key !! Datatype !! Description 
      |-
      | 0 || {{D|i=string}} || the tooltip to show, i.e. {{I|i=1. Input Slots}}
      |-
      | 1 || {{D|i=string}} || the color key to use for the tooltip, valid options are {{I|i=GREEN}}, {{I|i=BLUE}}, {{I|i=RED}}, {{I|i=YELLOW}}, or {{I|i=WHITE}}
     |}<br/>
     <h2>ingredient</h2>
     <p>Represents an ingredient for a recipe</p>
     {| class="wikitable"
      ! Key !! Datatype !! Description 
      |-
      | item || {{D|i=string}} || the item for this ingredient
      |-
      | amount || {{D|i=integer}} || the amount of this item needed for this ingredient
     |}<br/>
     <h2>instance</h2>
     <p>A generic representation of any instance. All instance types have the same properties, albeit some will be {{D|i=nil}}. See [[Instance Properties]] for more specific information.</p>
     {| class="wikitable"
      ! Key !! Datatype !! Description 
      |-
      | id || {{D|i=integer}} || the GMS id for this instance, to use in API methods
      |-
      | x || {{D|i=integer}} || the x position of this inst
      |-
      | y || {{D|i=integer}} || the y position of this inst
      |-
      | oid || {{D|i=integer}} || the APICO "id" value used with the Dictionary - will be nil on item/slot instances (see [[OID Reference]])
      |-
      | sprite_index || {{D|i=integer}} || the sprite image id used for this instance
      |-
      | image_index || {{D|i=integer}} || the sprite image "frame" currently set for this instance
      |-
      | image_xscale || {{D|i=integer}} || image xscale used in rendering, i.e. -1 to flip vertically
      |-
      | image_yscale || {{D|i=integer}} || image yscale used in rendering, i.e. -1 to flip horizontally
      |-
      | menu_id || {{D|i=integer}} || the menu instance for this instance - will be nil if not a menu object instance
      |-
      | slots || list({{D|i=slot}}) || a list of slot instances - will be nil if not a menu instance
     |}<br/>
     <h2>item_definition</h2>
     <p>Represents a definition for a new item. Items can be picked up, dropped, used, and crafted with.<br/>A good in-game example of an item would be Logs</p>
     {| class="wikitable"
      ! Key !! Datatype !! Description 
      |-
      | id || {{D|i=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 || {{D|i=string}} || the name of this item, shown in tooltips
      |-
      | category || {{D|i=string}} || the category for this item, shown in expanded tooltips
      |-
      | tooltip || {{D|i=string}} || the tooltip message for this item, shown in expanded tooltips
      |-
      | shop_key || {{D|i=boolean}} || [Optional] whether this is a "key" item and so cannot be sold
      |-
      | shop_buy || {{D|i=boolean}} || [Optional] the amount this item can be bought for if sold by an NPC
      |-
      | shop_sell || {{D|i=boolean}} || [Optional] the amount this item can be sold for at an NPC
      |-
      | machines || list({{D|i=string}}) || [Optional] a list of object oids that this item this can be used in, i.e. {{I|i=["workbench",   "sawmill"]}}, shown in tooltips (see [[OID Reference]])
      |-
      | placeable || {{D|i=boolean}} || [Optional] whether this item can be placed down on the ground, will use the object oid specified in "obj" if true
      |-
      | place_grass || {{D|i=boolean}} || [Optional] if placeable, this specifies if the item can only be placed on grass
      |-
      | place_water || {{D|i=boolean}} || [Optional] if placeable, this specifies if the item can only be placed on shallow water
      |-
      | place_deep || {{D|i=boolean}} || [Optional] if placeable, this specifies if the item can only be placed on deep water
      |-
      | singular || {{D|i=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 || {{D|i=boolean}} || [Optional] if specified, items created with this definition will have a durability, like tools
      |-
      | obj || {{D|i=string}} || [Optional] if placeable, this specifies the object oid that will be created when the item is used
      |-
      | honeycore || {{D|i=boolean}} || [Optional] if true, this item will be bought + sold for honeycore instead of rubees
      |-
      | bee_lore || {{D|i=string}} || [Optional] if set, this will be used as the "lore" in the bee book if this item is a bee's special produce
     |}<br/>
      <h2>layout</h2>
      <p>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.<br/>Technically this is a list of values, hence the keys below being numbers.</p>
      {| class="wikitable"
       ! Key !! Datatype !! Description 
       |-
       | 0 || {{D|i=string}} || the x position for the slot, relative to the menu's top left coordinate
       |-
       | 1 || {{D|i=string}} || the y position for the slot, relative to the menu's top left coordinate
       |-
       | 2 || {{D|i=string}} || [Optional] the type of slot this is, valid options are {{I|i=Input}}, {{I|i=Liquid Input}}, {{I|i=Output}}, {{I|i=Liquid Output}}, or {{I|i=Shop}}. Output slots cannot have items put in them.
       |-
       | 3 || list({{D|i=string}}) || [Optional] if the type of slot is {{I|i=Input}} or {{I|i=Liquid Input}}, this let's you define the items that are allowed in them, i.e. {{I|i=["log", "sticks1"]}}. You can also use some "specials" that allow any items of that same oid, namely: "seedX", "flowerX", "trackX", "dyeX", as well as "customX" (see {{F|i=api_define_validation_icon()}})
      |}<br/>
      <h2>menu_definition</h2>
      <p>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.<br/>They can be also given logic to run all the time so are a powerful tool for your mods.</p>
      {| class="wikitable"
       ! Key !! Datatype !! Description 
       |-
       | id || {{D|i=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 || {{D|i=string}} || the name of this object shown in tooltips
       |-
       | category || {{D|i=string}} || the category for this object, shown in expanded tooltips
       |-
       | tooltip || {{D|i=string}} || the tooltip message for this object, shown in expanded tooltips
       |-
       | shop_key || {{D|i=boolean}} || [Optional] whether this is a "key" object and so cannot be sold
       |-
       | shop_buy || {{D|i=boolean}} || [Optional] the amount this object can be bought for if sold by an NPC
       |-
       | shop_sell || {{D|i=boolean}} || [Optional] the amount this object can be sold for at an NPC
       |-
       | layout || list({{D|i=layout}}) || a list of layouts to set the slots for this objects menu
       |-
       | info || list({{D|i=info}}) || a list of information to show when the menu help button is pressed
       |-
       | buttons || list({{D|i=string}}) || a list of buttons for this objects menu to have, valid options are {{I|i=Help}}, {{I|i=Target}}, {{I|i=Sort}}, {{I|i=Move}}, {{I|i=Close}}
       |-
       | machines || list({{D|i=string}}) || [Optional] a list of object oids that this object this can be used in, i.e. {{I|i=  ["workbench", "sawmill"]}}, shown in tooltips (see [[OID Reference]])
       |-
       | tools || list({{D|i=string}}) || [Optional] a list of tools that can be used on this object, i.e. {{I|i=["mouse1", "axe1"]}},   shown in tooltips
       |-
       | nature || {{D|i=boolean}} || [Optional] this specifies if the object can only be placed on grass
       |-
       | aquatic || {{D|i=boolean}} || [Optional] this specifies if the object can only be placed on shallow water
       |-
       | deep || {{D|i=boolean}} || [Optional] this specifies if the object can only be placed on deep water
       |-
       | singular || {{D|i=boolean}} || [Optional] this specifies if the object can stack or can only be singular, like frames or bees
       |-
       | invisible || {{D|i=boolean}} || [Optional] if true, this object will not be drawn - it's bounding box will still be interactive though!
       |-
       | center || {{D|i=boolean}} || [Optional] if true, when this object's menu opens it will automatically be put in the center of the screen
       |-
       | item_sprite || {{D|i=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
      |}<br/>
      <h2>npc_definition</h2>
      <p>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.</p>
      {| class="wikitable"
       ! Key !! Datatype !! Description 
       |-
       | id || {{D|i=integer}} || id to use for the npc, must be unique across all mods
       |-
       | name || {{D|i=string}} || the name of this NPC, shown in tooltips and their dialogue
       |-
       | pronouns || {{D|i=string}} || the pronouns for this NPC, shown in their dialogue
       |-
       | tooltip || {{D|i=string}} || the tooltip message for this NPC, usually just a greeting message
       |-
       | specials || list({{D|i=string}}) || a list of at least 3 item oids that this NPC will have in it's special item pool 
       |-
       | stock|| list({{D|i=string}}) || a list of up to 10 item oids that this NPC will have as it's shop stock
       |-
       | greeting || {{D|i=string}} || the default greeting message shown in the dialogue menu when it opens
       |-
       | dialogue || list({{D|i=string}}) || a list of dialogue to show one after the other when a player clicks the "talk" button
       |-
       | walking || {{D|i=boolean}} || [Optional] whether this NPC will walk around or stay still
       |-
       | shop || {{D|i=boolean}} || [Optional] whether this NPC will have a shop or just be dialogue only
      |}<br/>
      <h2>obj_definition</h2>
      <p>Represents a definition for a new object. Objects can be picked up, dropped, placed, clicked on, and crafted with.<br/>A good   in-game example of an object would be the Bench</p>
      {| class="wikitable"
       ! Key !! Datatype !! Description 
       |-
       | id || {{D|i=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 || {{D|i=string}} || the name of this object shown in tooltips
       |-
       | category || {{D|i=string}} || the category for this object, shown in expanded tooltips
       |-
       | tooltip || {{D|i=string}} || the tooltip message for this object, shown in expanded tooltips
       |-
       | shop_key || {{D|i=boolean}} || [Optional] whether this is a "key" object and so cannot be sold
       |-
       | shop_buy || {{D|i=boolean}} || [Optional] the amount this object can be bought for if sold by an NPC
       |-
       | shop_sell || {{D|i=boolean}} || [Optional] the amount this object can be sold for at an NPC
       |-
       | machines || list({{D|i=string}}) || [Optional] a list of object oids that this object this can be used in, i.e. {{I|i=  ["workbench", "sawmill"]}}, shown in tooltips (see [[OID Reference]])
       |-
       | tools || list({{D|i=string}}) || [Optional] a list of tools that can be used on this object, i.e. {{I|i=["mouse1", "axe1"]}},   shown in tooltips
       |-
       | drops || list({{D|i=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 || {{D|i=boolean}} || [Optional] this specifies if the object can only be placed on grass
       |-
       | place_water || {{D|i=boolean}} || [Optional] this specifies if the object can only be placed on shallow water
       |-
       | place_deep || {{D|i=boolean}} || [Optional] this specifies if the object can only be placed on deep water
       |-
       | durability || {{D|i=boolean}} || [Optional] if specified, objects created with this definition will have a durability, like tools (this is NOT the same as health)
       |-
       | hp || {{D|i=boolean}} || [Optional] if specified, object created will have health, likes trees (this is NOT the same as durability)
       |-
       | singular || {{D|i=boolean}} || [Optional] if specified, objects created with this definition will not be able to stack, like frames
       |-
       | honeycore || {{D|i=boolean}} || [Optional] if true, this objects will be bought + sold for honeycore instead of rubees
       |-
       | invisible || {{D|i=boolean}} || [Optional] if true, this object will not be drawn - it's bounding box will still be interactive though!
       |-
       | bed || {{D|i=boolean}} || [Optional] if true, this object will act as a bed when clicked
       |-
       | bench || {{D|i=boolean}} || [Optional] if true, this object will act as a bench when clicked
       |-
       | has_lighting || {{D|i=boolean}} || [Optional] if true, this object will light up at night
       |-
       | has_shadow || {{D|i=boolean}} || [Optional] if true, a shadow will be automatically drawn under this object
       |-
       | pickable || {{D|i=boolean}} || [Optional] if true, you'll be able to pick up this item with the mouse
       |-
       | variants || {{D|i=integer}} || [Optional] for nature objects, like trees, this specifies the amount of variants within the sprite   for the object
       |-
       | growth || {{D|i=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 {{I|i="tree 360 560"}} to make a tree randomly after 360-560 seconds
       |-
       | item_sprite || {{D|i=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
      |}<br/>
      <h2>quest_definition</h2>
      <p>Represents a quest definition to make a new quest in the book.</p>
      {| class="wikitable"
       ! Key !! Datatype !! Description 
       |-
       | id || {{D|i=string}} || the unique id for your quest, for use with the progress handler
       |-
       | title || {{D|i=string}} || the title of your quest as shown in the book chapter list
       |-
       | reqs || list({{D|i=string}}) || the requirements needed for the quest to be ready, e.g. {{I|i=["axe1@2"]}} would mean 2 wooden axes are needed to complete
       |-
       | icon || {{D|i=string}} || the item oid of the item to use for the icon in the overview section of the book (see [[OID Reference]])
       |-
       | reward || {{D|i=string}} || the reward that will be given when the quest is handed in, e.g. {{I|i="honeycore1@10"}} would give 10 honeycore crystals
       |-
       | unlock || list({{D|i=string}}) || a list of quests ids to unlock when this quest is complete
      |}<br/>
      <h2>quest_line</h2>
      <p>Represents a line in a page of a quest, along with any text or images you want to show.</p>
      {| class="wikitable"
       ! Key !! Datatype !! Description 
       |-
       | text || {{D|i=string}} || the text for this line
       |-
       | color || {{D|i=string}} || [Optional] the color key for the text, defaults to "FONT_BOOK"
       |-
       | gif || {{D|i=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 || {{D|i=integer}} || [Optional] if a gif is specified this sets the height of the gif, should be 46, 66, or 86
      |}<br/>
      <h2>recipe</h2>
      <p>Represents a crafting recipe for the workbench.</p>
      {| class="wikitable"
       ! Key !! Datatype !! Description 
       |-
       | item || {{D|i=string}} || the item oid that this recipe will craft (see [[OID Reference]])
       |-
       | recipe || list({{D|i=ingredient}}) || the ingredients to use for this recipe
       |-
       | total || {{D|i=integer}} || [Optional] the total amount of the item you get when crafted, defaults to 1
      |}<br/>
     <h2>scripts</h2>
     <p>Represents a set of script definitions to use when defining a custom menu object. Each script must be a valid function found in your {{I|i=mod.lua}} file.</p>
     {| class="wikitable"
      ! Key !! Datatype !! Description 
      |-
      | define || {{D|i=string}} || a script to run when the menu object is first defined, allowing you to set custom properties and stuff
      |-
      | change || {{D|i=string}} || a script to run when a slot inside the menu object gets changed
      |-
      | tick || {{D|i=string}} || a script to run every tick (0.1s) for that menu object, as long as it's active
      |-
      | draw || {{D|i=string}} || a script to run every draw cycle for this menu object, only when the object's menu is actually open
     |}<br/>
     <h2>stats</h2>
     <p>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.<br>For bees, you can find the following properties from the stats property:</p>
     {| class="wikitable"
      ! Key !! Datatype !! Description 
      |-
      | species || {{D|i=string}} || the dominant species for the bee, i.e. {{I|i=common}}
      |-
      | queen || {{D|i=string}} || whether this bee is a queen or not
      |-
      | beetrice || {{D|i=boolean}} || whether this bee is a descendent of beetrice - the first bee you get from the book
      |-
      | microscoped || {{D|i=boolean}} || whether a bee has been microscoped (so people can't microscope the same bee 3 times)
      |-
      | shiny || {{D|i=boolean}} || whether this bee is a blessed variant
      |-
      | d_traits || {{D|i=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 {{F|i=api_define_trait()}} as well as the following standard traits: {{I|i=species}}, {{I|i=lifespan}}, {{I|i=productivity}}, {{I|i=fertility}}, {{I|i=behaviour}}, {{I|i=climate}}, {{I|i=stability}}, {{I|i=pluvioplhile}}, {{I|i=chionophile}} and {{I|i=aggressive}}. Dominent traits are what determines how the bee acts in beehives.
      |-
      | r_traits || {{D|i=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 {{F|i=api_define_trait()}} as well as the following standard traits: {{I|i=species}}, {{I|i=lifespan}}, {{I|i=productivity}}, {{I|i=fertility}}, {{I|i=behaviour}}, {{I|i=climate}}, {{I|i=stability}}, {{I|i=pluvioplhile}}, {{I|i=chionophile}} and {{I|i=aggressive}}.
     |}
     <p>For canisters, you can find the following properties from the stats property:</p>
     {| class="wikitable"
      ! Key !! Datatype !! Description 
      |-
      | type || {{D|i=string}} || the type of liquid in the canister, can be an empty string if empty or one of the following: {{I|i=water}}, {{I|i=resin}}, {{I|i=honey}}, or {{I|i=mead}}
      |-
      | amount || {{D|i=integer}} || the current amount in the canister
      |-
      | max || {{D|i=integer}} || the max amount this canister can hold
     |}
     <p>For frames, you can find the following properties from the stats property:</p>
     {| class="wikitable"
      ! Key !! Datatype !! Description 
      |-
      | filled || {{D|i=boolean}} || whether the frame has been filled from a hive
      |-
      | uncapped || {{D|i=boolean}} || whether the frame has been uncapped
      |-
      | flowers || {{D|i=string}} || a comma-separated list of flowers the bees who filled this frame visited
      |-
      | species || {{D|i=string}} || the species of bee that filled this frame
      |-
      | productivity || {{D|i=string}} || the dominant productivity trait value of the bee that filled this frame
     |}<br/>
     <h2>slot</h2>
     <p>Represents a slot instance that is part of a parent menu. Slots can be blank or hold items in them.</p>
     {| class="wikitable"
      ! Key !! Datatype !! Description 
      |-
      | id || {{D|i=integer}} || the GMS id for this instance, to use in API methods
      |-
      | index || {{D|i=integer}} || the index of this slot within a menu based on the menu layout, starting at 1
      |-
      | item || {{D|i=string}} || if this slot holds an item, this will be the item oid, otherwise it'll be blank, i.e. {{I|i=""}} (see [[OID Reference]])
      |-
      | count || {{D|i=integer}} || if this slot holds a non-singular item, this will store the count of the slot
      |-
      | current_health || {{D|i=integer}} || if this slot holds an item with durability, this will be the current durability amount
      |-
      | total_health || {{D|i=integer}} || if this slot holds an item with durability, this will be the full durability amount
      |-
      | stats || {{D|i=stats}} || used by frames, canisters and bees (or anything you might have set manually)
     |}<br/>
      <h2>time</h2>
      <p>Represents the current game time when retrieved through {{F|i=api_get_time}}.<br/>Dawn starts at 3am and ends at 7am. Dusk starts at 5pm and ends at 9pm.</p>
      {| class="wikitable"
      ! Key !! Datatype !! Description 
      |-
      | time || {{D|i=integer}} || the current time in the day, in ms. This is a number from 0 - 1440000.<br/>One hour in-game is 60000ms, or 1 minute.
      |-
      | day || {{D|i=integer}} || the current day that the player is on
      |-
      | name || {{D|i=string}} || the "name" for the time of day, either {{I|i=Day}}, {{I|i=Dawn}}, {{I|i=Dusk}}, or {{I|i=Night}}
      |-
      | clock || {{D|i=string}} || the current "clock" for the time of day, i.e. {{I|i=12:04}}
     |}<br/>
     <h2>wall_definition</h2>
     <p>Represents a definition for a new wall. Walls can be placed down and picked up with a hammer.</p>
     {| class="wikitable"
      ! Key !! Datatype !! Description 
      |-
      | id || {{D|i=string}} || id to use to create an oid for this item, must be unique across all mods (i.e. wall90001)
      |-
      | name || {{D|i=string}} || the name of this item, shown in tooltips
      |-
      | shop_buy || {{D|i=boolean}} || [Optional] the amount this item can be bought for if sold by an NPC
      |-
      | shop_sell || {{D|i=boolean}} || [Optional] the amount this item can be sold for at an NPC
     |}<br/>
     <h2>window_definition</h2>
     <p>Represents a definition for a new window. Windows can be placed on walls and picked up with a hammer.</p>
     {| class="wikitable"
      ! Key !! Datatype !! Description 
      |-
      | id || {{D|i=string}} || id to use to create an oid for this item, must be unique across all mods (i.e. window90001)
      |-
      | name || {{D|i=string}} || the name of this item, shown in tooltips
      |-
      | shop_buy || {{D|i=boolean}} || [Optional] the amount this item can be bought for if sold by an NPC
      |-
      | shop_sell || {{D|i=boolean}} || [Optional] the amount this item can be sold for at an NPC
     |}<br/>
      <h2>weather</h2>
      <p>Represents the current weather when retrieved through {{F|i=api_get_weather}}. Weather is simply either on or off - the weather effects shown are based on the biome the player is currently in.<br/>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)</p>
      {| class="wikitable"
      ! Key !! Datatype !! Description 
      |-
      | active || {{D|i=boolean}} || whether weather is current "on" or not
      |-
      | start_time || {{D|i=integer}} || the time weather will start today, in ms
      |-
      | end_time || {{D|i=integer}} || the time weather will end today, in ms
     |}
    </div>
  </div><br/>

  <div class="aw-api-section mw-customcollapsible-s1">
    <h1>[[File:Standard_Boat_Item.png|32px]]Hooks</h1>
    <p>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.<br/>Both {{H|i=register()}} and {{H|i=init()}} are required for your mod to run.<br/>You can only have one function for each hook (i.e. you can't have two "click()" hooks).</p>
    {| class="wikitable"
     ! Hook !! Description 
     |-
     | {{H|i=click()}} || this hook is called whenever the player clicks on something with the mouse (or uses "action" on a gamepad)
     |-
     | {{H|i=clock()}} || this hook is called every 1s of real-time
     |-
     | {{H|i=create()}} || this hook is a called whenever an object (tree, flower, generic object, menu object) or item is created
     |-
     | {{H|i=data()}} || this hook is a callback used whenever you call {{F|i=api_get_data()}} or {{F|i=api_set_data()}} due to file load being async
     |-
     | {{H|i=destroy()}} || this hook is a called whenever an object (tree, flower, generic object, menu object) is destroyed
     |-
     | {{H|i=draw()}} || this hook is called every draw cycle, on the overworld layer (above objects)
     |-
     | {{H|i=gui()}} || this hook is called every draw cycle, on the gui layer
     |-
     | {{H|i=http()}} || this hook is called when a HTTP response is returned from {{F|i=api_http_request()}}
     |-
     | {{H|i=init()}} || this hook is called when the mod is first initialised, allowing you to setup mod code for the first time
     |-
     | {{H|i=key()}} || this hook is called whenever a key is pressed
     |-
     | {{H|i=pdraw()}} || this hook is called every draw cycle, on the player layer
     |-
     | {{H|i=ready()}} || this hook is called when all mods have been both registered and initialised and after all objects are loaded in
     |-
     | {{H|i=register()}} || this hook is called first to register the mod with a unique name and setup required hooks
     |-
     | {{H|i=save()}} || this hook is called whenever the player saves or the autosave is called
     |-
     | {{H|i=scroll()}} || this hook is called when the mouse wheel is scrolled
     |-
     | {{H|i=tdraw()}} || this hook is called every draw cycle, on the overworld layer (above tiles but below objects)
     |-
     | {{H|i=tick()}} || this hook is called ever 0.1s of real time
     |-
     | {{H|i=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
    |}
    <div class="mw-collapsible mw-collapsed" id="mw-customcollapsible-s1">
      <h2>click()</h2>
      <p>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 {{F|i=api_get_key_down()}} or {{F|i=api_get_key_pressed()}} methods.<br/>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.</p>
      <p>This hook is called with the following parameters:</p>
      {| class="wikitable"
      ! Parameter !! Datatype !! Description 
      |-
      | button || {{D|i=string}} ||  the button of the mouse, will be {{I|i=LEFT}}, {{I|i=RIGHT}} or {{I|i=MIDDLE}}
      |-
      | click_type || {{D|i=string}} || the type of click, will be {{I|i=PRESSED}} or {{I|i=RELEASED}}, 
     |}
      <p>Example code to do something if a player clicks on a tree:</p>
<syntaxhighlight lang="lua">
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
</syntaxhighlight><br/>
      <h2>clock()</h2>
      <p>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.</p>
      <p>Example code to give the player 1 log every second:</p>
<syntaxhighlight lang="lua">
function clock()
  api_give_item("log", 1)
end
</syntaxhighlight><br/>
      <h2>create()</h2>
      <p>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!<br/><b>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)</b></p>
      {| class="wikitable"
      ! Parameter !! Datatype !! Description 
      |-
      | id || {{D|i=integer}} ||  the instance id of the inst that just got destroyed
      |-
      | x || {{D|i=integer}} || the x position of the inst that just go destroyed
      |-
      | y || {{D|i=integer}} || the y position of the inst that just go destroyed
      |-
      | oid|| {{D|i=string}} || the oid of the inst that just go destroyed (see [[OID Reference]])
      |-
      | inst_type || {{D|i=string}} || the "type" of inst created, can be one of the following: {{I|i=tree}}, {{I|i=flower}}, {{I|i=obj}}, {{I|i=menu_obj}}, or {{I|i=item}}
     |}
     <p>Example code to drop a custom item whenever a tree is chopped down:</p>
<syntaxhighlight lang="lua">
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
</syntaxhighlight><br/>
      <h2>data()</h2>
      <p>This hook is called whenever you call the {{F|i=api_get_data()}} or {{F|i=api_set_data()}} methods, as file loading is asynchronous.<br/>Each mod has it's own dedicated JSON file that you can read and write to through the API to avoid direct file access.</p>
      {| class="wikitable"
      ! Parameter !! Datatype !! Description 
      |-
      | ev || {{D|i=string}} ||  the type of data event, either {{I|i=SAVE}} or {{I|i=SAVE}} depending on which method you used
      |-
      | data || {{D|i=string}} or {{D|i=table}} || if a {{I|i=SAVE}} type, will return {{I|i=Success}}, otherwise if a {{I|i=LOAD}} type this parameter will contain your JSON file data as a table
     |}
     <p>Example code to load the mod datafile during {{H|i=init()}} and access the data:</p>
<syntaxhighlight lang="lua">
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
</syntaxhighlight><br/>
      <h2>destroy()</h2>
      <p>This hook is called whenever a tree, flower, generic object, or menu object is destroyed.<br/>While you will be passed the instance ID of the instance destroyed, this instance will no longer exist so you cannot use methods like {{F|i=api_get_data()}} or {{F|i=api_set_data()}}.</p>
      {| class="wikitable"
      ! Parameter !! Datatype !! Description 
      |-
      | id || {{D|i=integer}} ||  the instance id of the inst that just got destroyed
      |-
      | x || {{D|i=integer}} || the x position of the inst that just go destroyed
      |-
      | y || {{D|i=integer}} || the y position of the inst that just go destroyed
      |-
      | oid|| {{D|i=string}} || the oid of the inst that just go destroyed (see [[OID Reference]])
     |}
     <p>Example code to drop a custom item whenever a tree is chopped down:</p>
<syntaxhighlight lang="lua">
function destroy(id, x, y, oid) 

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

end
</syntaxhighlight><br/>
      <h2>draw()</h2>
      <p>This hook is called every in-game draw cycle. This hook allows you to use the various Draw Methods to draw stuff every cycle.<br/>This hook will draw items to the overworld layer - if you want to draw ontop of menus / UI you'll need to use the {{H|i=gui()}} hook instead.</p>
      <p>Example code to draw some text above the player:</p>
<syntaxhighlight lang="lua">
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
</syntaxhighlight><br/>
      <h2>gui()</h2>
      <p>This hook is called every in-game draw cycle and, like {{H|i=draw()}} hook, this hook allows you to use the various Draw Methods to draw stuff every cycle.<br/>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 {{H|i=draw()}} instead.</p>
      <p>Example code to draw a black circle on top of everything:</p>
<syntaxhighlight lang="lua">
function gui()

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

  -- draw a circle
  api_draw_circle(px, py, 100, false, "BLACK")
  
end
</syntaxhighlight><br/>
      <h2>http()</h2>
      <p>This hook is called every time a HTTP response is returned by {{F|i=api_http_request()}}.<br/>This hook returns regardless of whether the HTTP request succeeded or failed.</p>
      {| class="wikitable"
      ! Parameter !! Datatype !! Description 
      |-
      | response_id || {{D|i=string}} ||  the string you set in your {{F|i=api_http_request()}} method to help you identify the callback
      |-
      | status || {{D|i=string}} || returns either "Success" or "Error" depending on the HTTP status returned
      |-
      | response || {{D|i=string}} || response body returned from the HTTP request
     |}
      <p>Example code to handle some random HTTP call to get the APICO website homepage:</p>
<syntaxhighlight lang="lua">
-- 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
</syntaxhighlight><br/>
      <h2>init()</h2>
      <p>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.<br/>If your mod doesn't have an {{H|i=init()}} hook it will not be loaded.<br/>This hook is called before any mod objects might be loaded so you should use {{H|i=ready()}} if you want to get any mod objects that might have been saved.</p>
      <p>Your {{H|i=init()}} hook should return {{I|i=Success}} if things went well, or an error message to be shown in the Modding Console.</p>
      <p>Example code to define a global color when the mod is initialised:</p>
<syntaxhighlight lang="lua">
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
</syntaxhighlight><br/>
      <h2>key()</h2>
      <p>This hook is called whenever a key is pressed. You can use {{F|i=api_get_key_down}} or {{F|i=api_get_key_pressed}} to find out what key/s are being pressed.</p>
     {| class="wikitable"
      ! Parameter !! Datatype !! Description 
      |-
      | key_code || {{D|i=integer}} || the [[Key Codes|keycode]] of the key that was pressed to trigger this event 
     |}
     <p>Example code to run an action when the player presses the spacebar:</p>
<syntaxhighlight lang="lua">
function key(key_code)
  if key_code == 32 then 
    -- spacebar has been pressed!
  end
end
</syntaxhighlight><br/>
      <h2>pdraw()</h2>
      <p>This hook is called every in-game draw cycle. This hook allows you to use the various Draw Methods to draw stuff every cycle.<br/>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).</p>
      <p>Example code to draw some text above the player:</p>
<syntaxhighlight lang="lua">
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
</syntaxhighlight><br/>
      <h2>ready()</h2>
      <p>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.<br/>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.</p>
      <p>Example code to run a function from another mod after all mods have loaded:</p>
<syntaxhighlight lang="lua">
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
</syntaxhighlight><br/>
      <h2>register()</h2>
      <p>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 {{H|i=init()}} or {{H|i=ready()}}.</p>
      <p>Your {{H|i=register()}} hook should return a table with the following values:</p>
      {| class="wikitable"
      ! Parameter !! Datatype !! Description 
      |-
      | name || {{D|i=string}} || the unique name of your mod
      |-
      | hooks || list({{D|i=string}}) || a list of hooks you want your mod to subscribe too, i.e. {{I|i=<nowiki>{"click", "clock"}</nowiki>}}. You do not need to specify "register" or "init" as they are required.
      |-
      | modules || list({{D|i=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.
     |}
     <p>Example code to register "sample_mod" and subscribe to the {{H|i=clock()}} and {{H|i=tick()}} hooks</p>
<syntaxhighlight lang="lua">
function register() 
  return {
    name = "sample_mod",
    hooks = {"clock", "tick"},
    modules = {"define"} -- will load /modules/define.lua (if it exists)
  }
end
</syntaxhighlight><br/>
      <h2>save()</h2>
      <p>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.</p>
      <p>Example code to update the mod datafile when the game saves:</p>
<syntaxhighlight lang="lua">
-- 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
</syntaxhighlight><br/>
      <h2>scroll()</h2>
      <p>This hook is called whenever the mouse wheel is scrolled</p>
      {| class="wikitable"
      ! Parameter !! Datatype !! Description 
      |-
      | direction || {{D|i=string}} || either {{I|i=UP}} or {{I|i=DOWN}}
      |-
      | inverse || {{D|i=boolean}} || whether the player has set inverse scroll in their settings
     |}
      <p>Example code to affect some drawing offset with the scroll:</p>
<syntaxhighlight lang="lua">
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
</syntaxhighlight><br/>
      <h2>tdraw()</h2>
      <p>This hook is called every in-game draw cycle. This hook allows you to use the various Draw Methods to draw stuff every cycle.<br/>This hook is similar to {{H|i=draw()}} except it will draw things underneath the object layer (i.e. for drawing fake tiles).</p>
      <p>Example code to draw a circle that will be below objects/walls:</p>
<syntaxhighlight lang="lua">
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
</syntaxhighlight><br/>
      <h2>tick()</h2>
      <p>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 {{H|i=clock()}}.<br/><b>Please check the logic you are running in this hook along with the FPS meter to ensure you are not starting to reduce performance!</b></p><p><b>Do not leave {{F|i=api_create_log()}} calls in this method!!!</b></p>
      <p>Example code to update a counter every tick:</p>
<syntaxhighlight lang="lua">
global_count = 0

-- after 10 seconds the count would be 100
function tick()
  global_count = global_count + 1
end
</syntaxhighlight><br/>
      <h2>step()</h2>
      <p>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 {{H|i=tick()}} you would see a slight lag as it's not being updated at the same FPS.<br/><b>Please check the logic you are running in this hook along with the FPS meter to ensure you are not starting to reduce performance!</b></p><p><b>Do not leave {{F|i=api_create_log()}} calls in this method!!!</b></p>
      <p>Example code to update a counter every frame:</p>
<syntaxhighlight lang="lua">
global_count = 0

-- after 10 seconds the count would be 600
function step()
  global_count = global_count + 1
end
</syntaxhighlight><br/>
      <h2>worldgen()</h2>
      <p>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 {{F|i=api_set_blueprint()}}, or "replace" existing objects in the world.<br/>For reference, game worlds are 350x350 tiles, with 290x290 being visible on the map and rest being reserved for secret areas.</p>
      {| class="wikitable"
      ! Parameter !! Datatype !! Description 
      |-
      | before_objects || {{D|i=boolean}} || as the hook is called twice, this bool tells you if this is the pre-object call or post-object call
     |}
      <p>Example code to change the player's start position when the world is created:</p>
<syntaxhighlight lang="lua">
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
</syntaxhighlight>
    </div>
  </div><br/>
  
  <div class="aw-api-section mw-customcollapsible-s1">
    <h1>[[File:Barrel_Item.png|32px]]All Methods</h1>
    <p>All methods allow you to get all instances of a given type regardless of where they are in the world (both active and inactive). <b>They should be used extremely sparingly, as they cause all objects to be momentarily activated!<br>Do NOT use these in tick()/clock() hooks</b></p>
    {| class="wikitable"
     ! Method !! Description 
     |-
     | {{F|i=api_all_flowers()}} || returns a list of all flower instance ids in the world
     |-
     | {{F|i=api_all_trees()}} || returns a list of all tree instance ids in the world
     |-
     | {{F|i=api_all_menu_objects()}} || returns a list of all menu object instance ids in the world
     |-
     | {{F|i=api_all_objects()}} || returns a list of all generic object instance ids in the world
    |}
    <div class="mw-collapsible mw-collapsed" id="mw-customcollapsible-s1">
      <h2>api_all_flowers()</h2>
      <p>This method returns the IDs of all flowers in the world, regardless of whether they are onscreen or not.</p>
      {| class="wikitable"
      ! Parameter !! Datatype !! Description 
      |-
      | oid || {{D|i=string}} || filter results to a specific oid (ideally you should always provide a filter) (see [[OID Reference]])
     |}
     <p>This method will return a list of {{D|i=integer}}s for each instance ID, which you can then use with other methods.</p>
     <p>Example code to get all Honeyrose flowers in the world and then DESTROY THEM:</p>
<syntaxhighlight lang="lua">
-- 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
</syntaxhighlight><br/>
      <h2>api_all_trees()</h2>
      <p>This method returns the IDs of all trees in the world, regardless of whether they are onscreen or not.</p>
     <p>This method will return a list of {{D|i=integer}}s for each instance ID, which you can then use with other methods.</p>
     <p>Example code to get all trees in the world and turn 10% of them into Skipper:</p>
<syntaxhighlight lang="lua">
-- 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
</syntaxhighlight><br/>
      <h2>api_all_menu_objects()</h2>
      <p>This method returns the IDs of all menu objects (machines, beehives, npcs etc) in the world, regardless of whether they are working or not.</p>
      {| class="wikitable"
      ! Parameter !! Datatype !! Description 
      |-
      | oid || {{D|i=string}} || filter results to a specific oid (ideally you should always provide a filter) (see [[OID Reference]])
     |}
     <p>This method will return a list of {{D|i=integer}}s for each instance ID, which you can then use with other methods.</p>
     <p>Example code to get all the Skippers in the world, and then duplicate them:</p>
<syntaxhighlight lang="lua">
-- 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
</syntaxhighlight><br/>
      <h2>api_all_objects()</h2>
      <p>This method returns the IDs of all generic objects (rocks, shrubs, benches etc) in the world, regardless of whether they are onscreen or not.</p>
      {| class="wikitable"
      ! Parameter !! Datatype !! Description 
      |-
      | oid || {{D|i=string}} || filter results to a specific oid (ideally you should always provide a filter) (see [[OID Reference]])
     |}
     <p>This method will return a list of {{D|i=integer}}s for each instance ID, which you can then use with other methods.</p>
     <p>Example code to get all rocks in the world and turn them into Honeycore:</p>
<syntaxhighlight lang="lua">
-- 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
</syntaxhighlight>
    </div>
  </div><br/>

  <div class="aw-api-section mw-customcollapsible-s1">
    <h1>[[File:Logs_Item.png|32px]]Create Methods</h1>
    <p>Create methods allow you to create something, either an instance, a particle effect, or a timer.</p>
    {| class="wikitable"
     ! Method !! Description 
     |-
     | {{F|i=api_create_bee_stats()}} || creates a {{D|i=stats}} for a bee for a given species
     |-
     | {{F|i=api_create_counter()}} || creates a custom counter to iterate through values in a loop
     |-
     | {{F|i=api_create_effect()}} || creates a special effect at a given position
     |-
     | {{F|i=api_create_item()}} || creates an item at a given position
     |-
     | {{F|i=api_create_log()}} {{F|i=api_log()}} || creates a log in the Modding Console (opened with {{I|i=CTRL}}+{{I|i=.}})
     |-
     | {{F|i=api_create_obj()}} || creates an object or menu object at a given position
     |-
     | {{F|i=api_create_timer()}} || creates a custom timer to callback after x seconds
    |}
    <div class="mw-collapsible mw-collapsed" id="mw-customcollapsible-s1">
      <h2>api_create_bee_stats()</h2>
      <p>A bee is just a fancy item with a bunch of stats assigned, you've probably seen the {{D|i=stats}} returned in a slot's properties! This method lets you create a bee stat obj by passing a species.<br/>The traits will be picked at random from those available in the bee definition, like naturally spawned bees + mutations do.</p>
      {| class="wikitable"
      ! Parameter !! Datatype !! Description 
      |-
      | species || {{D|i=integer}} || the species of the bee to create stats for
      |-
      | queen || {{D|i=boolean}} || whether to make this a queen bee or not
     |}
     <p>Example code to spawn a bee item for a given species:</p>
<syntaxhighlight lang="lua">
-- create stats
stats = api_create_bee_stats("common", false)

-- create item
api_create_item("bee", 1, 100, 100, stats)
</syntaxhighlight><br/>
      <h2>api_create_counter()</h2>
      <p>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.</p>
      {| class="wikitable"
      ! Parameter !! Datatype !! Description 
      |-
      | key || {{D|i=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 || {{D|i=integer}} || the interval in seconds to increment the counter
      |-
      | start_val || {{D|i=integer}} || the value to start the counter at, and reset too when the end_val is reached
      |-
      | end_val || {{D|i=integer}} || the max number for the counter, after which it'll reset to the start_val
      |-
      | increment || {{D|i=integer}} || the amount to increment by each interval
     |}
     <p>Example code to create a custom counter that goes from 0 - 100 in increments of 25</p>
<syntaxhighlight lang="lua">
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
</syntaxhighlight><br/>
      <h2>api_create_effect()</h2>
      <p>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.<br/>With the exception of {{I|i=BEE_QUEEN}}, {{I|i=BEE_PFX}}, {{I|i=NOTE_1}}, and {{I|i=NOTE_2}}, all particles are just a single pixel size.</p>
      {| class="wikitable"
      ! Parameter !! Datatype !! Description 
      |-
      | px || {{D|i=integer}} || the x position to create the particle at
      |-
      | py || {{D|i=integer}} || the y position to create the particle at
      |-
      | ptype || {{D|i=string}} || the particle type to create, options are: {{I|i=DUST_RIGHT}}, {{I|i=DUST_LEFT}}, {{I|i=DUST_DOWN}}, {{I|i=TREE_LEAVES}}, {{I|i=TREE_GROWTH}}, {{I|i=PAINT_GROWTH}}, {{I|i=GATE_GROWTH}}, {{I|i=BEE_PFX}}, {{I|i=ROCK_GROWTH}}, {{I|i=STEP_RIGHT}}, {{I|i=STEP_LEFT}}, {{I|i=BREATH_RIGHT}}, {{I|i=BREATH_LEFT}}, {{I|i=BEE_TRAIL}}, {{I|i=FLOWER_POLLEN}}, {{I|i=BEE_QUEEN}}, {{I|i=BEE_CONFETTI}}, {{I|i=EXTRACT_DUST}}, {{I|i=RAIN_DROP}}, {{I|i=SNOW_DROP}}, {{I|i=RESIN_DROP}}, {{I|i=SMOKE_PUFF}}, {{I|i=STEP_SNOW}}, {{I|i=CHILL_PUFF}}, {{I|i=MEAD_BUFF}}, {{I|i=NOTE_1}}, or {{I|i=NOTE_2}}
      |-
      | amount || {{D|i=integer}} || the number of particles to create
      |-
      | amount || {{D|i=integer}} || the color key of particles to create, i.e. {{I|i=FONT_BLUE}}
     |}
     <p>Example code to create 50 blue confetti type particles on the player's location:</p>
<syntaxhighlight lang="lua">
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
</syntaxhighlight><br/>
      <h2>api_create_item()</h2>
      <p>This lets you create an already defined item at a specific position. If you want to define a new item you need to use {{F|i=api_define_item()}}</p>
      {| class="wikitable"
      ! Parameter !! Datatype !! Description 
      |-
      | item || {{D|i=string}} || the item oid of the item you want to create (see [[OID Reference]])
      |-
      | count || {{D|i=integer}} || the number of the item to create
      |-
      | x || {{D|i=integer}} || the x position to create the item at
      |-
      | y || {{D|i=integer}} || the y position to create the item at
      |-
      | stats || {{D|i=stats}} || [Optional] a {{D|i=stats}} obj to use, can be one you got from {{F|i=api_create_bee_stats()}} or a custom one
     |}
     <p>This will return either the newly created object item id as a {{D|i=integer}} else it will return {{D|i=nil}} if it failed.</p>
     <p>Example code to create 50 logs near the player:</p>
<syntaxhighlight lang="lua">
-- 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)
</syntaxhighlight><br/>
      <h2>api_create_log()</h2>
      <p>Your new best friend! This logs something to the Modding Console, which you can toggle with {{I|i=CTRL}}+{{I|i=.}}. Each log is shown broken down into the mod name, the group, and then the message.<br/>You can also use a shorthand of "api_log()".</p>
      {| class="wikitable"
      ! Parameter !! Datatype !! Description 
      |-
      | ident || {{D|i=string}} || an identifier for the log to help you identify message
      |-
      | msg || {{D|i=string}} || the message to log
     |}
     <p>Example code to create a log saying hello:</p>
<syntaxhighlight lang="lua">
api_log("test_log", "Hello World!")
</syntaxhighlight><br/>
      <h2>api_create_obj()</h2>
      <p>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 {{F|i=api_define_object()}} or {{F|i=api_define_menu_object()}}.</p>
      {| class="wikitable"
      ! Parameter !! Datatype !! Description 
      |-
      | oid || {{D|i=string}} || the object oid of the object you want to create (see [[OID Reference]])
      |-
      | x || {{D|i=integer}} || the x position to create the object at
      |-
      | y || {{D|i=integer}} || the y position to create the object at
     |}
     <p>For some reason that is completely beyond me this function will always return {{D|i=nil}} and I don't know why, soz :(</p>
     <p>Example code to create a workbench next to the player:</p>
<syntaxhighlight lang="lua">
-- 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)
</syntaxhighlight><br/>
      <h2>api_create_timer()</h2>
      <p>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.</p>
      {| class="wikitable"
      ! Parameter !! Datatype !! Description 
      |-
      | method || {{D|i=string}} || the function you want to call when the timer ends
      |-
      | seconds || {{D|i=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
     |}
<syntaxhighlight lang="lua">
-- 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
</syntaxhighlight><br/>
    </div>
  </div><br/>

  <div class="aw-api-section mw-customcollapsible-s1">
    <h1>[[File:Book1_Item.png|32px]]Define Methods</h1>
    <p>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 [https://github.com/APICO-Modders/APICO-Sample-Mod Sample Mod] project to see examples of the sprites needed.</p>
    {| class="wikitable"
     ! Method !! Description 
     |-
     | {{F|i=api_define_bee()}} || defines a new species of bee for the game
     |-
     | {{F|i=api_define_bee_recipe()}} || defines a custom bee "recipe" for hybrids, along with a mutation script to check criteria
     |-
     | {{F|i=api_define_button()}} || defines a custom button to be used with a menu object
     |-
     | {{F|i=api_define_color()}} || defines a custom color to use in draw calls
     |-
     | {{F|i=api_define_command()}} || defines a custom command to use in the In-Game Console
     |-
     | {{F|i=api_define_flower()}} || defines a new species of flower for the game
     |-
     | {{F|i=api_define_flower_recipe()}} || defines a new species of flower for the game
     |-
     | {{F|i=api_define_gif())}} || defines a custom "gif" sprite to use custom quests
     |-
     | {{F|i=api_define_gui()}} || defines a custom gui (hoverable visual element) to be used with a menu object
     |-
     | {{F|i=api_define_item()}} || defines a new item for the game like Logs or Planks
     |-
     | {{F|i=api_define_item_stats()}} || defines the default "stats" an item will get created with
     |-
     | {{F|i=api_define_liquid()}} || defines a custom liquid to use in barrels, canisters, or your own menu object tanks
     |-
     | {{F|i=api_define_menu_object()}} || defines a new menu object for the game like a Workbench or a Beehive
     |-
     | {{F|i=api_define_notification()}} || defines a new notification type along with a dismiss script for when it's clicked
     |-
     | {{F|i=api_define_npc()}} || defines a custom npc with dialogue and optionally a shop
     |-
     | {{F|i=api_define_object()}} || defines a new object for the game like a Bench or a Statue
     |-
     | {{F|i=api_define_property()}} {{F|i=api_dp}} || defines a new property on a given instance
     |-
     | {{F|i=api_define_quest()}} || defines a new quest for the game, shown in the guide
     |-
     | {{F|i=api_define_recipe()}} || defines a new recipe for the Mod Workbench
     |-
     | {{F|i=api_define_sprite()}} || defines a custom sprite to use in draw calls
     |-
     | {{F|i=api_define_tank()}} || defines a custom liquid storage tank for a menu
     |-
     | {{F|i=api_define_trait()}} || defines a custom trait to apply to all bees going forward
     |-
     | {{F|i=api_define_validation_icon()}} || defines a custom validation icon for "customX" slot validation with {{D|i=layout}}'s
     |-
     | {{F|i=api_define_wall()}} || defines a custom wall
     |-
     | {{F|i=api_define_window()}} || defines a custom window
     |-
     | {{F|i=api_define_workbench()}} || defines the mod and tab labels shown in the Mod Workbench
    |}
    <div class="mw-collapsible mw-collapsed" id="mw-customcollapsible-s1">
      <h2>api_define_bee()</h2>
      <p>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!</p>
      {| class="wikitable"
      ! Parameter !! Datatype !! Description 
      |-
      | bee_def || {{D|i=bee_definition}} || the bee definition to be used to create the new species
      |-
      | bee_sprite_image || {{D|i=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 || {{D|i=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 || {{D|i=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 || {{D|i=color}} || a color to use for the bee, used in the book, predictor, and the discovery popup
      |-
      | bee_mag_image || {{D|i=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 || {{D|i=string}} || headline text to use in the news magazine popup
      |-
      | bee_mag_body || {{D|i=string}} || body text to use in the news magazine popup
     |}
     <p>If this method worked it will return {{I|i=Success}}, otherwise if it fails it will return {{D|i=nil}} and will log an error in the Modding Console with one of the following errors:</p>
     {| class="wikitable"
     ! 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
    |}
     <p>Example code to create a new species of bee:</p>
<syntaxhighlight lang="lua">
-- 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!"
);
</syntaxhighlight><br/>
      <h2>api_define_bee_recipe()</h2>
      <p>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.<br/>In mutation land, {{I|i=common-forest}} is the same as {{I|i=forest-common}} so it doesn't matter which order you set below.</p>
      {| class="wikitable"
      ! Parameter !! Datatype !! Description 
      |-
      | species_a || {{D|i=string}} || one of the two bees this hybrid needs - recipe will be added to both bee definitions
      |-
      | species_b || {{D|i=string}} || the other bee this hybrid needs - recipe will be added to both bee definitions
      |-
      | species_s || {{D|i=string}} || the species that will be formed if a mutation occurs
      |-
      | mutation_script || {{D|i=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
     |}
     <p>If this method worked it will return {{I|i=Success}}, otherwise if it fails it will return {{D|i=nil}} and will log an error in the Modding Console with one of the following errors:</p>
     {| class="wikitable"
     ! 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
    |}
     <p>Example code to create new recipe between Verge and Dream bees to make Ancient bees if the player has enough money:</p>
<syntaxhighlight lang="lua">
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
</syntaxhighlight><br/>
      <h2>api_define_button()</h2>
      <p>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.</p>
      {| class="wikitable"
      ! Parameter !! Datatype !! Description 
      |-
      | menu_id || {{D|i=integer}} || the menu object instance id you want to define attach the button to
      |-
      | button_key || {{D|i=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 || {{D|i=integer}} || the relative x position of the button from the top-left of the menu sprite
      |-
      | button_oy || {{D|i=integer}} || the relative y position of the button from the top-left of the menu sprite
      |-
      | button_text || {{D|i=string}} || text to add to the button, can be blank
      |-
      | button_script || {{D|i=string}} || the name of the function you want to call when the button is pressed - must be defined in your mod
      |-
      | sprite_image || {{D|i=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)
     |}
     <p>If this method worked it will return {{I|i=Success}}, otherwise if it fails it will return {{D|i=nil}} and will log an error in the Modding Console with one of the following errors:</p>
     {| class="wikitable"
     ! 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
    |}
     <p>Example code to create a new button on an existing menu:</p>
<syntaxhighlight lang="lua">
-- 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
</syntaxhighlight><br/>
      <h2>api_define_color()</h2>
      <p>All colors in the game are defined in the colors_ref.json file in the base game, each with their own key.<br/>This method allows you to define a custom RGB color to use alongside these existing color keys.</p>
      {| class="wikitable"
      ! Parameter !! Datatype !! Description 
      |-
      | name || {{D|i=string}} || the name to use for your color, will be the color key you can use in the future to draw with
      |-
      | color || {{D|i=color}} || the rgb color you want to define
     |}
     <p>If this method worked it will return {{I|i=Success}}, otherwise if it fails it will return {{D|i=nil}} and will log an error in the Modding Console with one of the following errors:</p>
     {| class="wikitable"
     ! Error !! Description 
     |-
     | Color Name Already Exists || a color with this key already exists
    |}
     <p>Example code to define a color and use it in the {{H|i=draw()}} hook:</p>
<syntaxhighlight lang="lua">
-- 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
</syntaxhighlight><br/>
      <h2>api_define_command()</h2>
      <p>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 {{F|i=api_set_devmode()}}.<br/>Your command name should include the forward slash, i.e. {{I|i=/teleport}}.</p>
      {| class="wikitable"
      ! Parameter !! Datatype !! Description 
      |-
      | command_name || {{D|i=string}} || the unique name for your command, must be unique across all mods
      |-
      | command_script || {{D|i=string}} || the script to run when the command is entered, will be passed a list of arguments as a parameter
     |}
     <p>If this method worked it will return {{I|i=Success}}, otherwise if it fails it will return {{D|i=nil}} and will log an error in the Modding Console with one of the following errors:</p>
     {| class="wikitable"
     ! Error !! Description 
     |-
     | Command With That Name Already Exists || command name used is already defined
    |}
     <p>Example code to define a command that lets you teleport to a specific x + y position</p>
<syntaxhighlight lang="lua">
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
</syntaxhighlight><br/>
      <h2>api_define_flower()</h2>
      <p>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.<br/><b>As flowers do not have a unique ID per mod you will need to make sure your flower is unique between all mods.</b></p>
      {| class="wikitable"
      ! Parameter !! Datatype !! Description 
      |-
      | flower_def || {{D|i=flower_definition}} || your flower definition table 
      |-
      | flower_sprite_image || {{D|i=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 || {{D|i=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 || {{D|i=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 || {{D|i=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 || {{D|i=color}} || custom RGB color for the flower, used in the smoker, overworld and the book
     |}
     <p>If this method worked it will return {{I|i=Success}}, otherwise if it fails it will return {{D|i=nil}} and will log an error in the Modding Console with one of the following errors:</p>
     {| class="wikitable"
     ! 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
    |}
     <p>Example code to define a custom flower that can be planted on ocean:</p>
<syntaxhighlight lang="lua">
-- 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}
);
</syntaxhighlight><br/>
      <h2>api_define_flower_recipe()</h2>
      <p>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.<br/>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.</p>
      {| class="wikitable"
      ! Parameter !! Datatype !! Description 
      |-
      | species_a || {{D|i=string}} || one of the two flowers this hybrid needs - recipe will be added to both flower definitions
      |-
      | species_b || {{D|i=string}} || the other flower this hybrid needs - recipe will be added to both flower definitions
      |-
      | species_s || {{D|i=string}} || the flower that will be formed if a mutation occurs, it's "chance" value will be used for the mutation chance
     |}
     <p>If this method worked it will return {{I|i=Success}}, otherwise if it fails it will return {{D|i=nil}} and will log an error in the Modding Console with one of the following errors:</p>
     {| class="wikitable"
     ! 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
    |}
     <p>Example code to create new recipe between Honeyrose and Honeybriar to make Combristle:</p>
<syntaxhighlight lang="lua">
-- 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")
</syntaxhighlight><br/>
      <h2>api_define_gif()</h2>
      <p>This method allows you to define a custom "gif" sprite which you can then use in custom quest definitions.<br/>The only difference between this and {{F|i=api_define_sprite()}} is that whatever name you provide will be prepended with "gif_", i.e. {{I|i=gif_my_gif_name}} which will allow the quest rendered to show the GIF correctly.</p>
      {| class="wikitable"
      ! Parameter !! Datatype !! Description 
      |-
      | gif_name || {{D|i=string}} || the name for this gif, will be prepended with "gif_"
      |-
      | gif_image || {{D|i=string}} || the path to the gif sprite you want to add, must be 148px wide, and either 46px, 66px or 86px high
      |-
      | frames || {{D|i=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
     |}
     <p>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 {{D|i=nil}} and will log an error in the Modding Console with one of the following errors:</p>
     {| class="wikitable"
     ! 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
    |}
     <p>Example code define a new gif to then use in a custom quest definition:</p>
<syntaxhighlight lang="lua">

</syntaxhighlight><br/>
      <h2>api_define_gui()</h2>
      <p>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.<br/><b>Your "gui_key" should be unique per menu object define (i.e. don't use "progress" for 2 different menu objects).</b></b></p>
      {| class="wikitable"
      ! Parameter !! Datatype !! Description 
      |-
      | menu_id || {{D|i=integer}} || the menu object instance id you want to define attach the gui to
      |-
      | gui_key || {{D|i=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 || {{D|i=integer}} || the relative x position of the gui from the top-left of the menu sprite
      |-
      | gui_oy || {{D|i=integer}} || the relative y position of the gui from the top-left of the menu sprite
      |-
      | gui_script || {{D|i=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 || {{D|i=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 || {{D|i=string}} || [Optional] the name of the function you want to call when the gui is clicked on - must be defined in your mod
     |}
     <p>If this method worked it will return {{I|i=Success}}, otherwise if it fails it will return {{D|i=nil}} and will log an error in the Modding Console with one of the following errors:</p>
     {| class="wikitable"
     ! 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
    |}
     <p>Example code:</p>
<syntaxhighlight lang="lua">
-- 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
</syntaxhighlight><br/>
      <h2>api_define_item()</h2>
      <p>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.<br/>When you define an item the item oid will be the id you give prepended with your mod name, i.e. {{I|i=sample_mod_my_item}}.</p>
      {| class="wikitable"
      ! Parameter !! Datatype !! Description 
      |-
      | item_def || {{D|i=item_definition}} || an item definition table
      |-
      | sprite_image || {{D|i=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)
     |}
     <p>If this method worked it will return {{I|i=Success}}, otherwise if it fails it will return {{D|i=nil}} and will log an error in the Modding Console with one of the following errors:</p>
     {| class="wikitable"
     ! 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
    |}
     <p>Example code to define a new super cool axe:</p>
<syntaxhighlight lang="lua">
-- 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)
</syntaxhighlight><br/>
      <h2>api_define_item_stats()</h2>
      <p>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.</p>
      {| class="wikitable"
      ! Parameter !! Datatype !! Description 
      |-
      | oid || {{D|i=string}} || the oid of the item to define default stats for (see [[OID Reference]])
      |-
      | stats || {{D|i=table}} || the stats to give to an item when created if it has the given oid
     |}
     <p>This method won't return anything as it's just assigning a value to a key.</p>
     <p>Example code to define a new super cool axe and give it default custom stats to use later:</p>
<syntaxhighlight lang="lua">
-- 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
</syntaxhighlight><br/>
      <h2>api_define_liquid()</h2>
      <p>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.<br/>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)<br/><b>Note: Custom liquids cannot be used in the Bottler.</b></p>
      {| class="wikitable"
      ! Parameter !! Datatype !! Description 
      |-
      | name || {{D|i=string}} || the name of the liquid to use, this will be shown in tooltips and be set as the liquid "type" in stats
      |-
      | color || {{D|i=string}} || a color name to use for the liquid, this can be a default one or your own that you defined with {{F|i=api_define_color()}}
      |-
      | texture_sprite || {{D|i=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 || {{D|i=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)
     |}
     <p>If this method worked it will return {{I|i=Success}}, otherwise if it fails it will return {{D|i=nil}} and will log an error in the Modding Console with one of the following errors:</p>
     {| class="wikitable"
     ! 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
    |}
     <p>Example code to define a "coffee" liquid and spawn a canister containing that liquid:</p>
<syntaxhighlight lang="lua">
-- 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?
</syntaxhighlight><br/>
      <h2>api_define_menu_object()</h2>
      <p>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.<br/>When you define a menu object the object oid will be the id you give prepended with your mod name, i.e. {{I|i=sample_mod_my_menu_object}}.<br/>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 {{D|i=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.</p>
      {| class="wikitable"
      ! Parameter !! Datatype !! Description 
      |-
      | menu_def || {{D|i=menu_definition}} || the menu definition table to use
      |-
      | sprite_image || {{D|i=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 || {{D|i=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 || {{D|i=scripts}} || a scripts definition for all the scripts you want your menu object to run
      |-
      | draw_script || {{D|i=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
     |}
     <p>If this method worked it will return {{I|i=Success}}, otherwise if it fails it will return {{D|i=nil}} and will log an error in the Modding Console with one of the following errors:</p>
     {| class="wikitable"
     ! 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
    |}
     <p>Example code to add a custom "Recycler" machine, that takes items and turns them into random seeds:</p>
<syntaxhighlight lang="lua">
-- 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
</syntaxhighlight><br/>
      <h2>api_define_notification()</h2>
      <p>This let's you define your own notification type to use with {{F|i=api_set_notification()}}. Standard notification types have their own actions when clicked, some simply dismiss while others open books.<br/>Using this method you can set your own action for when the player clicks on your notification!</p>
      {| class="wikitable"
      ! Parameter !! Datatype !! Description 
      |-
      | notification_type || {{D|i=string}} || a name for your notification - will be prepended by your mod ID, i.e. {{I|i=sample_mod_my_notification}}
      |-
      | notification_script || {{D|i=string}} || the script to run when the player clicks this type of notification - needs to be a method in your mod file
     |}
     <p>If this method worked it will return {{I|i=Success}}, otherwise if it fails it will return {{D|i=nil}} and will log an error in the Modding Console with one of the following errors:</p>
     {| class="wikitable"
     ! Error !! Description 
     |-
     | Notification Type Already Defined || notification with this type name has already been used
    |}
     <p>Example code to make a notification type and then set a notification for that type:</p>
<syntaxhighlight lang="lua">
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
</syntaxhighlight><br/>
      <h2>api_define_npc()</h2>
      <p>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!<br/>You will need to handle adding in the NPC to the game yourself, whether in {{H|i=worldgen()}}, {{H|i=ready()}}, or somewhere else.</p>
      {| class="wikitable"
      ! Parameter !! Datatype !! Description 
      |-
      | npc_def || {{D|i=npc_definition}} || the definition obj for your NPC
      |-
      | standing_sprite || {{D|i=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 || {{D|i=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 || {{D|i=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 || {{D|i=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 || {{D|i=string}} || relative path to the sprite you want to use for this NPCs map icon, should be a 64x16 image with 4 frames (normal, normal highlighted, undiscovered, undiscovered highlight)
      |-
      | bust_sprite || {{D|i=string}} || relative path to the sprite you want to use for this item, should be a 18x14 image with 1 frame 
      |-
      | item_sprite || {{D|i=string}} || relative path to the sprite you want to use for this NPCs item (that you get when you hammer an NPC), should be a 64x16 image with 2 frames (normal, normal highlighted)
      |-
      | dialogue_menu_sprite || {{D|i=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 || {{D|i=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)
     |}
     <p>If this method worked it will return {{I|i=Success}}, otherwise if it fails it will return {{D|i=nil}} and will log an error in the Modding Console with one of the following errors:</p>
     {| class="wikitable"
     ! Error !! Description 
     |-
     | Missing Required Key || one of the required keys in the {{D|i=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
    |}
     <p>Example code to define a new NPC:</p>
<syntaxhighlight lang="lua">
--set npc definition
npc_def = {
  id = 69,
  name = "Gobbo",
  pronouns = "They/Them",
  tooltip = "Wassup pal?",
  shop = true,
  walking = true,
  stock = {"log", "log", "log", "log", "log", "log", "log", "log", "log", "log"}, -- max 10
  specials = {"log", "log", "log"}, -- must be 3
  dialogue = {
    "Wot ya mean av I gots anything other than logs to sell??",
    "Wot a stoopid question hoomie"
  },
  greeting = "Alright pal ow ya gettin' on"
}
-- define npc, damn thats a lot of sprites
api_define_npc(npc_def,
  "sprites/npc_standing.png",
  "sprites/npc_standing_h.png",
  "sprites/npc_walking.png",
  "sprites/npc_walking_h.png",
  "sprites/npc_head.png",
  "sprites/npc_bust.png",
  "sprites/npc_item.png",
  "sprites/npc_dialogue_menu.png",
  "sprites/npc_shop_menu.png"
)
</syntaxhighlight><br/>
      <h2>api_define_object()</h2>
      <p>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.<br/>When you define an object the object oid will be the id you give prepended with your mod name, i.e {{I|i=sample_mod_my_object}}.</p>
      {| class="wikitable"
      ! Parameter !! Datatype !! Description 
      |-
      | object_def || {{D|i=obj_definition}} || an obj definition table
      |-
      | sprite_image || {{D|i=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 || {{D|i=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
     |}
     <p>If this method worked it will return {{I|i=Success}}, otherwise if it fails it will return {{D|i=nil}} and will log an error in the Modding Console with one of the following errors:</p>
     {| class="wikitable"
     ! 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
    |}
     <p>Example code to make a chair object:</p>
<syntaxhighlight lang="lua">
-- 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
</syntaxhighlight><br/>
      <h2>api_define_property()</h2>
      <p>This allows you to define a new property onto any instance which you'll then be able to use with {{F|i=api_set_property()}} and {{F|i=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.<br/>Potentially you might end up overriding an existing property so might be worth checking first before setting something generic!<br/>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)</p>
      {| class="wikitable"
      ! Parameter !! Datatype !! Description 
      |-
      | inst_id || {{D|i=integer}} || id of instance to set a property on
      |-
      | prop_name || {{D|i=string}} || key for the property to set
      |-
      | prop_value || Any || value to set the property to
     |}
     <p>If this method worked it will return {{I|i=Success}}, otherwise if it fails it will return {{D|i=nil}} and will log an error in the Modding Console with one of the following errors:</p>
     {| class="wikitable"
     ! Error !! Description 
     |-
     | Instance Doesn't Exist || the instance specified either doesn't exist or has been deactivated
    |}
     <p>Example code:</p>
<syntaxhighlight lang="lua">
-- 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
</syntaxhighlight><br/>
      <h2>api_define_quest()</h2>
      <p>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.</p>
      {| class="wikitable"
      ! Parameter !! Datatype !! Description 
      |-
      | quest_def || {{D|i=quest_definition}} || the quest definition table you want to use
      |-
      | page1 || list({{D|i=quest_line}}) || the lines for the left-hand side quest page
      |-
      | page2 || list({{D|i=quest_definition}}) || the lines for the right-hand side quest page
      |-
      | claim_script || {{D|i=string}} || [Optional] call a script when the quest is completed
     |}
     <p>If this method worked it will return {{I|i=Success}}, otherwise if it fails it will return {{D|i=nil}} and will log an error in the Modding Console with one of the following errors:</p>
     {| class="wikitable"
     ! 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
    |}
     <p>Example code:</p>
<syntaxhighlight lang="lua">
-- 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)
</syntaxhighlight><br/>
      <h2>api_define_recipe()</h2>
      <p>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).<br/>You can use {{F|i=api_define_workbench()}} to define the tab names for your mod.</p>
      {| class="wikitable"
      ! Parameter !! Datatype !! Description 
      |-
      | tab || {{D|i=string}} || the tab in the workbench that this recipe will be shown in, options are {{I|i=t1}}, {{I|i=t2}}, {{I|i=t3}}, {{I|i=t4}}, and {{I|i=t5}}
      |-
      | item || {{D|i=string}} || the item oid that you want this recipe to be for (see [[OID Reference]])
      |-
      | recipe || {{D|i=recipe}} || a recipe definition you want to use
      |-
      | amount || {{D|i=integer}} || [Optional] if specified, when crafting this recipe the player will get this amount instead of 1
     |}
     <p>If this method worked it will return {{I|i=Success}}, otherwise if it fails it will return {{D|i=nil}} and will log an error in the Modding Console with one of the following errors:</p>
     {| class="wikitable"
     ! Error !! Description 
     |-
     | Invalid Recipe Tab Name || tab provided isn't one of the valid options
     |-
     | Invalid Recipe Ingredients || invalid recipe definition, check your setup
    |}
     <p>Example code:</p>
<syntaxhighlight lang="lua">
-- 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)
</syntaxhighlight><br/>
      <h2>api_define_sprite()</h2>
      <p>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.<br/>Whatever name you provide will be prepended with "sp_", i.e. {{I|i=sp_my_mod_sprite_name}}.<br/><b>For all sprites, GameMaker will use the bottom left pixel as the "transparent" pixel!</b><br/><b>All sprite names are global across mods so it's recommended to use your mod_id in the name provided.</b></p>
      {| class="wikitable"
      ! Parameter !! Datatype !! Description 
      |-
      | sprite_name || {{D|i=string}} || the name for this sprite, will be prepended with "sp_"
      |-
      | sprite_image || {{D|i=string}} || the path to the sprite you want to add, can be any size
      |-
      | frames || {{D|i=integer}} || the number of frames for the sprite - your image will be divided by the number of frames given
     |}
     <p>If this method worked it will return the sprite id which you can use later, otherwise if it fails it will return {{D|i=nil}} and will log an error in the Modding Console with one of the following errors:</p>
     {| class="wikitable"
     ! 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
    |}
     <p>Example code define a new sprite to draw with:</p>
<syntaxhighlight lang="lua">
-- 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
</syntaxhighlight><br/>
      <h2>api_define_tank()</h2>
      <p>This method allows you to define a liquid storage tank for a given menu. This tank can then be used with standard methods like {{F|i=api_slot_fill()}}, {{F|i=api_slot_drain()}}, and {{F|i=api_draw_tank()}}</p>
      {| class="wikitable"
      ! Parameter !! Datatype !! Description 
      |-
      | menu_id || {{D|i=integer}} || the menu instance to add the tank too
      |-
      | tank_amount || {{D|i=integer}} || the default amount of liquid in the tank
      |-
      | tank_max || {{D|i=integer}} || the max amount of liquid this tank can have
      |-
      | tank_type || {{D|i=string}} || the type of tank this is, options are {{I|i=water}}, {{I|i=resin}}, {{I|i=honey}} or {{I|i=mead}} 
      |-
      | tx || {{D|i=integer}} || the x position of this tank relative to the menu's top-left corner
      |-
      | ty || {{D|i=integer}} || the y position of this tank relative to the menu's top-left corner
      |-
      | tank_size || {{D|i=string}} || the size of the tank gui (unrelated to tank_max), options are {{I|i=small}}, {{I|i=medium}}, {{I|i=large}} or {{I|i=xlarge}}
      |-
      | tank_script || {{D|i=string}} || [Optional] the name of the function you want to call when the tank is clicked on - must be defined in your mod
     |}
     <p>If this method worked it will return {{I|i=Success}}, otherwise if it fails it will return {{D|i=nil}} and will log an error in the Modding Console with one of the following errors:</p>
     {| class="wikitable"
     ! Error !! Description 
     |-
     | Menu Instance Not Found || specified menu instance doesn't exist or isn't active
    |}
     <p>Example code to setup a menu object that has a water tank and a slot you can drain the water from:</p>
<syntaxhighlight lang="lua">
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
</syntaxhighlight><br/>
      <h2>api_define_trait()</h2>
      <p>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 {{D|i=slot}}'s {{D|i=stats}}.</p>
      {| class="wikitable"
      ! Parameter !! Datatype !! Description 
      |-
      | trait_key || {{D|i=string}} || the name of this trait, will be prepended with your mod id, i.e. {{I|i=sample_mod_magic}}
      |-
      | trait_map || {{D|i=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({{D|i=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
     |}
     <p>If this method worked it will return {{I|i=Success}}, otherwise if it fails it will return {{D|i=nil}} and will log an error in the Modding Console with one of the following errors:</p>
     {| class="wikitable"
     ! 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
    |}
     <p>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:</p>
<syntaxhighlight lang="lua">
-- 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
</syntaxhighlight><br/>
      <h2>api_define_validation_icon()</h2>
      <p>This method allows you to define a custom icon to use with custom validations in {{D|i=layout}}'s for slots.<br/><br/>Custom validations follow the format of "customX:thing" where "thing" is the oid you want to allow in the slot.</p>
      {| class="wikitable"
      ! Parameter !! Datatype !! Description 
      |-
      | validation || {{D|i=string}} || the custom validation, i.e. "customX:axe" - this has to match what you put in your {{D|i=layout}} 
      |-
      | icon_sprite || {{D|i=string}} || the sprite to use for the validation, shown on slot hover. This should be a single 16x16 sprite.
     |}
     <p>If this method worked it will return {{I|i=Success}}, otherwise if it fails it will return {{D|i=nil}} and will log an error in the Modding Console with one of the following errors:</p>
     {| class="wikitable"
     ! 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?
    |}
     <p>Example code to add a custom validation to a machine that only takes axes:</p>
<syntaxhighlight lang="lua">
-- 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
</syntaxhighlight><br/>
      <h2>api_define_wall()</h2>
      <p>This method allows you to define your own custom wall that can be placed in-game and act as a solid.</p>
      {| class="wikitable"
      ! Parameter !! Datatype !! Description 
      |-
      | wall|| {{D|i=wall_definition}} || definition for your new wall
      |-
      | wall_sprite || {{D|i=string}} || the spritesheet for the new wall, needs to contain both the item sprites and wall variants, see the example in the [https://github.com/APICO-Modders/APICO-Sample-Mod/blob/main/sprites/wall/wall_sprite.png Sample Mod]
     |}
     <p>If this method worked it will return {{I|i=Success}}, otherwise if it fails it will return {{D|i=nil}} and will log an error in the Modding Console with one of the following errors:</p>
     {| class="wikitable"
     ! 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
    |}
     <p>Example code to add a shiny custom wall:</p>
<syntaxhighlight lang="lua">
-- 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
</syntaxhighlight><br/>
      <h2>api_define_window()</h2>
      <p>This method allows you to define your own custom window that can be placed on walls.<br/>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.</p>
      {| class="wikitable"
      ! Parameter !! Datatype !! Description 
      |-
      | window || {{D|i=window_definition}} || definition for your new window
      |-
      | window_sprite || {{D|i=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
     |}
     <p>If this method worked it will return {{I|i=Success}}, otherwise if it fails it will return {{D|i=nil}} and will log an error in the Modding Console with one of the following errors:</p>
     {| class="wikitable"
     ! 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
    |}
     <p>Example code to add a shiny custom wall:</p>
<syntaxhighlight lang="lua">
-- setup the trait
function init() 

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

  return "Success"

end
</syntaxhighlight><br/>
      <h2>api_define_workbench()</h2>
      <p>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).<br/>If not specified the Mod Workbench will show your mod_id, and tabs will just be labelled "Tab 1", "Tab 2" etc.<br/><b>The labels you give do not affect the tab parameter in {{F|i=api_define_recipe()}} which will still always use "t1", "t2", etc</b></p>
      {| class="wikitable"
      ! Parameter !! Datatype !! Description 
      |-
      | label || {{D|i=string}} || label to show for your mod in the Mod Workbench
      |-
      | tabs || {{D|i=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.
     |}
     <p>If this method worked it will return {{I|i=Success}}, otherwise god knows how you messed that up!</p>
     <p>Example code to set the tabs for our mod:</p>
<syntaxhighlight lang="lua">
-- 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
</syntaxhighlight>
    </div>
  </div><br/>
  
  <div class="aw-api-section mw-customcollapsible-s1">
    <h1>[[File:Sign_Item.png|32px]]Describe Methods</h1>
    <p>Describe methods allow you to get specific metadata about the game, both from base game and from mods.</p>
    {| class="wikitable"
     ! Method !! Description 
     |-
     | {{F|i=api_describe_bees()}} || returns a list of all bees defined from either the base game or all mods
     |-
     | {{F|i=api_describe_commands()}} || returns a list of all commands defined from either the base game or all mods
     |-
     | {{F|i=api_describe_dictionary()}} || returns the entire dictionary for either the base game or all mods
     |-
     | {{F|i=api_describe_mods()}} || returns a list of all mod_id's loaded
     |-
     | {{F|i=api_describe_oids()}} || returns a list of all oids defined from either the base game or all mods
     |-
     | {{F|i=api_describe_recipes()}} || returns a list of all crafting recipes defined from either the base game or all mods
    |}
    <div class="mw-collapsible mw-collapsed" id="mw-customcollapsible-s1">
      <h2>api_describe_bees()</h2>
      <p>This method returns all the bee definitions for either the base game or for all mods loaded.<b>The bee definitions are also a heckin' BIG table, so I wouldn't try api_log()ing it lol</b></p>
      {| class="wikitable"
      ! Parameter !! Datatype !! Description 
      |-
      | mods || {{D|i=boolean}} || if true will return results for mods instead of the base game
     |}
     <p>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.<br/>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.</p>
     <p>Example code to get some specific oid definitions from dictionaries:</p>
<syntaxhighlight lang="lua">
-- 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)
</syntaxhighlight><br/>
      <h2>api_describe_commands()</h2>
      <p>This method returns all the commands usable in-game for either the base game or for all mods loaded.</p>
      {| class="wikitable"
      ! Parameter !! Datatype !! Description 
      |-
      | mods || {{D|i=boolean}} || if true will return results for mods instead of the base game
     |}
     <p>If the "mods" parameter is false, this method will return a list of {{D|i=string}}s for each command, i.e. "/gimme".<br/>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.</p>
     <p>Example code to get some specific oid definitions from dictionaries:</p>
<syntaxhighlight lang="lua">
-- 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)
</syntaxhighlight><br/>
      <h2>api_describe_dictionary()</h2>
      <p>This method returns the entire dictionary for either the base game or for all mods loaded.<b>The dictionary is a heckin' BIG table, so I wouldn't try api_log()ing it lol</b></p>
      {| class="wikitable"
      ! Parameter !! Datatype !! Description 
      |-
      | mods || {{D|i=boolean}} || if true will return results for mods instead of the base game
     |}
     <p>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.<br/>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.</p>
     <p>Example code to get some specific oid definitions from dictionaries:</p>
<syntaxhighlight lang="lua">
-- 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)
</syntaxhighlight><br/>
      <h2>api_describe_mods()</h2>
      <p>This method returns a list of mod_id's for all the mods currently load.</p>
      {| class="wikitable"
      ! Parameter !! Datatype !! Description 
      |-
      | oid || {{D|i=string}} || filter results to a specific oid (ideally you should always provide a filter) (see [[OID Reference]])
     |}
     <p>This method will return a list of {{D|i=string}}s for each mod loaded.</p>
     <p>Example code to get all mods the user currently has:</p>
<syntaxhighlight lang="lua">
-- 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
</syntaxhighlight><br/>
      <h2>api_describe_oids()</h2>
      <p>This method returns a list of oids defined for either the base game or for all mods loaded (see [[OID Reference]]).</p>
      {| class="wikitable"
      ! Parameter !! Datatype !! Description 
      |-
      | mods || {{D|i=boolean}} || if true will return results for mods instead of the base game
     |}
     <p>If the "mods" parameter is false, this method will return a list of {{D|i=string}}s for each oid in the base game.<br/>If true, this method will return a table with a key for each mod_id loaded, with a list of {{D|i=strings}}s for each of the mods' oids underneath it.</p>
     <p>Example code to get some oids:</p>
<syntaxhighlight lang="lua">
-- 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)
</syntaxhighlight><br/>
      <h2>api_describe_recipes()</h2>
      <p>This method returns all the crafting recipes in either the base game or for all mods loaded.</p>
      {| class="wikitable"
      ! Parameter !! Datatype !! Description 
      |-
      | mods || {{D|i=boolean}} || if true will return results for mods instead of the base game
     |}
     <p>If the "mods" parameter is false, this method will return a table for each recipe category (see {{F|i=api_define_recipe()}}), with a list of {{D|i=recipe}} under each one.<br/>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).</p>
     <p>Example code to get some specific oid definitions from dictionaries:</p>
<syntaxhighlight lang="lua">
-- 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)
</syntaxhighlight>
    </div>
  </div><br/>

  <div class="aw-api-section mw-customcollapsible-s1">
    <h1>[[File:Pencil_Item.png|32px]]Draw Methods</h1>
    <p>Draw methods let you draw sprites or primitives. These methods will only work in the draw script of a menu object (defined in {{F|i=api_define_menu_object()}}), in the {{H|i=draw()}} hook or in the {{H|i=gui()}} hook<br/>It's worth noting that due to the small scale resolution of APICO any primitives you draw will be aligned with the pixel grid.</p>
    {| class="wikitable"
     ! Method !! Description 
     |-
     | {{F|i=api_draw_button()}} || helper to draw a button defined with {{F|i=api_define_button()}} automatically
     |-
     | {{F|i=api_draw_circle()}} || draws a circle (solid or outlined) at a specific position
     |-
     | {{F|i=api_draw_line()}} || draws a line at a specific position
     |-
     | {{F|i=api_draw_rectangle()}} || draws a rectangle (solid or outlined) at a specific position
     |-
     | {{F|i=api_draw_slots()}} || draws all the slots for a given menu
     |-
     | {{F|i=api_draw_sprite()}} || draws a given sprite at a specific position
     |-
     | {{F|i=api_draw_sprite_part()}} || draws part of a given sprite at a specific position
     |-
     | {{F|i=api_draw_sprite_ext()}} || draws a sprite at a given position and allows for transformations (rotate, scale, color blend)
     |-
     | {{F|i=api_draw_text()}} || draws text at a specific position
     |-
     | {{F|i=api_draw_tank()}} || helper to draw a tank defined with {{F|i=api_define_tank()}} automatically
    |}
    <div class="mw-collapsible mw-collapsed" id="mw-customcollapsible-s1">
      <h2>api_draw_button()</h2>
      <p>Utility method to quickly draw a button you've defined with {{F|i=api_define_button()}}. You could draw the button manually but this does a lot of boilerplate for you.</p>
      {| class="wikitable"
      ! Parameter !! Datatype !! Description 
      |-
      | button_id || {{D|i=integer}} || the button id to draw 
      |-
      | show_text || {{D|i=boolean}} || if the button has text you can choose to draw it here
     |}
     <p>Example code to define and draw a button for a menu:</p>
<syntaxhighlight lang="lua">
-- 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
</syntaxhighlight><br/>
      <h2>api_draw_circle()</h2>
      <p>This lets you draw a circle (filled or outline) at a give position.</p>
      {| class="wikitable"
      ! Parameter !! Datatype !! Description 
      |-
      | cx || {{D|i=integer}} || the x position to draw at (this will be at the centre of the circle)
      |-
      | cy || {{D|i=integer}} || the y position to draw at (this will be at the centre of the circle)
      |-
      | rad || {{D|i=integer}} || the radius of the circle
      |-
      | outline || {{D|i=boolean}} || whether to draw an outline instead of a filled circle
      |-
      | col || {{D|i=string}} || [Optional] the color key to use for this circle color, either one you defined with {{F|i=api_define_color()}} or a name from the {{I|i=colors_ref.json}} game file, defaults to white if not specified
      |-
      | alpha || {{D|i=integer}} || [Optional] the alpha level to draw with (number between 0-1)
     |}
     <p>Example code to draw some concentric coloured circles:</p>
<syntaxhighlight lang="lua">
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)
</syntaxhighlight><br/>
      <h2>api_draw_line()</h2>
      <p>This lets you draw a basic line between two points.</p>
      {| class="wikitable"
      ! Parameter !! Datatype !! Description 
      |-
      | x1 || {{D|i=integer}} || the x position to start the line at
      |-
      | y1 || {{D|i=integer}} || the y position to start the line at
      |-
      | x2 || {{D|i=integer}} || the x position to end the line at
      |-
      | y2 || {{D|i=integer}} || the y position to end the line at
      |-
      | col || {{D|i=string}} || [Optional] the color key to use for this circle color, either one you defined with {{F|i=api_define_color()}} or a name from the {{I|i=colors_ref.json}} game file, defaults to white if not specified
      |-
      | alpha || {{D|i=integer}} || [Optional] the alpha level to draw with (number between 0-1)
     |}
     <p>Example code to draw a green line between two points:</p>
<syntaxhighlight lang="lua">
api_draw_line(0, 0, 100, 100, "FONT_GREEN")
</syntaxhighlight><br/>
      <h2>api_draw_rectangle()</h2>
      <p>This lets you draw a basic rectangle shape, either outlined or filled.</p>
      {| class="wikitable"
      ! Parameter !! Datatype !! Description 
      |-
      | x1 || {{D|i=integer}} || the left x position of the rectangle
      |-
      | y1 || {{D|i=integer}} || the top y position of the rectangle
      |-
      | x2 || {{D|i=integer}} || the right x position of the rectangle
      |-
      | y2 || {{D|i=integer}} || the bottom y position of the rectangle
      |-
      | col || {{D|i=string}} || the color key to use for this circle color, either one you defined with {{F|i=api_define_color()}} or a name from the {{I|i=colors_ref.json}} game file, defaults to white if set as {{D|i=nil}}
      |-
      | outline || {{D|i=boolean}} || whether to draw an outline instead of a filled rectangle
      |-
      | alpha || {{D|i=integer}} || [Optional] the alpha level to draw with (number between 0-1)
     |}
     <p>Example code to draw a 100x100px blue rectangular outline:</p>
<syntaxhighlight lang="lua">
api_draw_rectangle(0, 0, 100, 100, "FONT_BLUE", true)
</syntaxhighlight><br/>
      <h2>api_draw_slots()</h2>
      <p>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. <br/><br/>By using this method you can then redraw the slots on top of whatever you have drawn in your menu_draw script.</p>
      {| class="wikitable"
      ! Parameter !! Datatype !! Description 
      |-
      | menu_id || {{D|i=integer}} || the menu instance to draw the slots for (NOT the menu object instance)
     |}
     <p>Example code to draw a 100x100px blue rectangle in a menu draw cycle then redraw the slots on top:</p>
<syntaxhighlight lang="lua">
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
</syntaxhighlight><br/>
      <h2>api_draw_sprite()</h2>
      <p>This let's you draw a sprite that you either created through {{F|i=api_define_sprite()}} or retrieved through {{F|i=api_get_sprite()}}.<br/>You should get your sprite indexes outside of the draw script to help performance.</p>
      {| class="wikitable"
      ! Parameter !! Datatype !! Description 
      |-
      | sprite_ref || {{D|i=integer}} || the sprite id to draw with
      |-
      | frame || {{D|i=integer}} || the sprite frame to draw
      |-
      | sx || {{D|i=integer}} || the x position to draw at 
      |-
      | sy || {{D|i=integer}} || the y position to draw at
     |}
     <p>Example code to draw a sprite you defined earlier:</p>
<syntaxhighlight lang="lua">
-- 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
</syntaxhighlight><br/>
      <h2>api_draw_sprite_part()</h2>
      <p>This is the same as {{F|i=api_draw_sprite()}} except you can draw a part of the sprite instead of the whole sprite.</p>
      {| class="wikitable"
      ! Parameter !! Datatype !! Description 
      |-
      | sprite_ref || {{D|i=integer}} || the sprite id to draw with
      |-
      | frame || {{D|i=integer}} || the sprite frame to draw
      |-
      | left || {{D|i=integer}} || the x position on the sprite image to draw the part from
      |-
      | top || {{D|i=integer}} || the y position on the sprite image to draw the part from
      |-
      | width || {{D|i=integer}} || the width of the part
      |-
      | height || {{D|i=integer}} || the height of the part
      |-
      | sx || {{D|i=integer}} || the x position to draw at 
      |-
      | sy || {{D|i=integer}} || the y position to draw at
     |}
     <p>Example code to draw a small part of a sprite:</p>
<syntaxhighlight lang="lua">
  -- 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
</syntaxhighlight><br/>
      <h2>api_draw_sprite_ext()</h2>
      <p>This is the same as {{F|i=api_draw_sprite()}} except you can apply scale transformations, rotations and color blending.</p>
      {| class="wikitable"
      ! Parameter !! Datatype !! Description 
      |-
      | sprite_ref || {{D|i=integer}} || the sprite id to draw with
      |-
      | frame || {{D|i=integer}} || the sprite frame to draw
      |-
      | sx || {{D|i=integer}} || the x position to draw at 
      |-
      | sy || {{D|i=integer}} || the y position to draw at
      |-
      | x_scale || {{D|i=integer}} || the x scale to apply
      |-
      | y_scale || {{D|i=integer}} || the y scale to apply
      |-
      | rot || {{D|i=integer}} || the rotation angle to draw at
      |-
      | col || {{D|i=string}} || the color blend to apply, use {{D|i=nil}} to apply no color blending
      |-
      | alp || {{D|i=decimal}} || the alpha level to draw with, a number between 0-1
     |}
     <p>Example code to draw our axe again but this time 3x the size:</p>
<syntaxhighlight lang="lua">
-- 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
</syntaxhighlight><br/>
      <h2>api_draw_text()</h2>
      <p>This allows you to draw any amount of text, either on 1 line or wrapped based off a width</p>
      {| class="wikitable"
      ! Parameter !! Datatype !! Description 
      |-
      | tx || {{D|i=integer}} || the x position to draw at 
      |-
      | ty || {{D|i=integer}} || the y position to draw at
      |-
      | text || {{D|i=integer}} || the text to draw
      |-
      | card || {{D|i=boolean}} || whether to show a card background behind the text (like tooltips)
      |-
      | col || {{D|i=string}} || [Optional] the color key to use for this circle color, either one you defined with {{F|i=api_define_color()}} or a name from the {{I|i=colors_ref.json}} game file, defaults to white if not specified
      |-
      | tw || {{D|i=integer}} || [Optional] a width to apply to the text, causing extra text to wrap onto the next line
     |}
     <p>Example code to draw a blue text tooltip ontop of the player:</p>
<syntaxhighlight lang="lua">
-- 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)
</syntaxhighlight><br/>
      <h2>api_draw_tank()</h2>
      <p>Utility method to quickly draw a tank you've defined with {{F|i=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.</p>
      {| class="wikitable"
      ! Parameter !! Datatype !! Description 
      |-
      | tank_id || {{D|i=integer}} || the tank gui id to draw
     |}
     <p>Example code to define and draw a tank for a menu:</p>
<syntaxhighlight lang="lua">
-- 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
</syntaxhighlight>
    </div>
  </div><br/>

  <div class="aw-api-section mw-customcollapsible-s1">
    <h1>[[File:Stone_Hammer_Item.png|32px]]Get Methods</h1>
    <p>Get methods allow you to retrieve information or instances from the game. All get methods start with {{I|i=api_get_*}}.</p>
    {| class="wikitable"
     ! Method !! Description 
     |-
     | {{F|i=api_get_boundary()}} || returns a {{D|i=boundary}} for a given instance
     |-
     | {{F|i=api_get_camera_position()}} {{F|i=api_get_cam}} || returns a {{D|i=coordinate}} of the current camera position
     |-
     | {{F|i=api_get_data()}} || returns the mods own JSON datafile
     |-
     | {{F|i=api_get_definition()}} || returns the dictionary definition for a given oid
     |-
     | {{F|i=api_get_equipped()}} || returns the currently equipped item (mouse or hotbar), if any
     |-
     | {{F|i=api_get_filename()}} || returns the file the player is currently playing in
     |-
     | {{F|i=api_get_floor()}} || returns the floor tile oid of the flooring at a given position, if any
     |-
     | {{F|i=api_get_flowers()}} || returns a list of {{D|i=instance}}s for all the active flowers onscreen
     |-
     | {{F|i=api_get_game_size()}} || returns the current size of the game window, taking game scale into account
     |-
     | {{F|i=api_get_ground()}} || returns the ground oid of the ground at a given position
     |-
     | {{F|i=api_get_highlighted()}} || returns a currently highlighted instance, if any
     |-
     | {{F|i=api_get_inst()}} || returns an {{D|i=instance}} specified by id
     |-
     | {{F|i=api_get_inst_in_rectangle()}} || returns a list of {{D|i=instance}} in a given rectangle boundary
     |-
     | {{F|i=api_get_inst_in_circle()}} || returns a a list of {{D|i=instance}} in a given circle boundary
     |-
     | {{F|i=api_get_key_down()}} || returns if a key is currently being held down
     |-
     | {{F|i=api_get_key_pressed()}} || returns if a key is currently being pressed
     |-
     | {{F|i=api_get_language()}} || returns the current player's selected language, i.e. "en"
     |-
     | {{F|i=api_get_menu_objects()}} || returns a list of {{D|i=instance}}s for all active menu objects, both onscreen and "working" offscreen
     |-
     | {{F|i=api_get_menus_obj()}} || returns the menu object inst for a given menu inst
     |-
     | {{F|i=api_get_mouse_inst()}} || returns the mouse inst id for the global mouse instance
     |-
     | {{F|i=api_get_mouse_position()}} || returns a {{D|i=coordinate}} of the current mouse position
     |-
     | {{F|i=api_get_mouse_tile_position()}} || returns a {{D|i=coordinate}} of the current mouse tile
     |-
     | {{F|i=api_get_objects()}} || returns a list of {{D|i=instance}}s for all active objects onscreen
     |-
     | {{F|i=api_get_player_instance()}} || returns the player instance id
     |-
     | {{F|i=api_get_player_position()}} || returns a {{D|i=coordinate}} of the player's current position
     |-
     | {{F|i=api_get_player_tile_position()}} || returns a {{D|i=coordinate}} of the player's current tile 
     |-
     | {{F|i=api_get_property()}} {{F|i=api_gp}} || returns a property value for a given instance
     |-
     | {{F|i=api_get_slot()}} || returns a {{D|i=slot}} for a specific index from a menu object
     |-
     | {{F|i=api_get_slot_inst()}} || returns a {{D|i=slot}} for a speicifc slot inst id
     |-
     | {{F|i=api_get_slots()}} || returns a list of {{D|i=slot}}s for a menu object
     |-
     | {{F|i=api_get_sprite()}} || returns a sprite reference for a given oid
     |-
     | {{F|i=api_get_time()}} || returns a {{D|i=time}} of the current game time
     |-
     | {{F|i=api_get_trees()}} || returns a list of {{D|i=instance}}s for all the active trees onscreen
     |-
     | {{F|i=api_get_weather()}} || return a {{D|i=weather}} of the current game weather
    |}
    <div class="mw-collapsible mw-collapsed" id="mw-customcollapsible-s1">
      <h2>api_get_boundary()</h2>
      <p>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.</p>
      {| class="wikitable"
      ! Parameter !! Datatype !! Description 
      |-
      | inst_id || {{D|i=integer}} || the instance you want to get the boundary for 
     |}
     <p>Returns either a {{D|i=boundary}} or {{D|i=nil}} with one of the following errors logged in the Modding Console:</p>
     {| class="wikitable"
     ! Error !! Description 
     |-
     | Invalid Instance ID || instance id provided is not valid 
     |-
     | Instance Not Active || instance provided is not active
    |}
     <p>Example code to get the bounding box of the player:</p>
<syntaxhighlight lang="lua">
player_inst = api_get_player_instance()
bounding_box = api_get_boundary(player_inst)
</syntaxhighlight><br/>
      <h2>api_get_camera_position()</h2>
      <p>This method lets you get the camera position. The entire world is made up of objects with a {{D|i=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.<br/>If you want to draw something within the view you'll need to take into account the camera position.</p>
      <p>This method will return a {{D|i=coordinate}} for the camera position.</p>
     <p>Example code to draw a red circle on top of the player:</p>
<syntaxhighlight lang="lua">
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)
</syntaxhighlight><br/>
      <h2>api_get_data()</h2>
      <p>This method lets you retrieve your mods' {{I|i=data.json}} file. As file loading needs to be asynchronous, this will callback to the {{H|i=data()}} hook, so you will need to handle the processing of your data file to do whatever you want to do there.</p>
     <p>Example code to get a key from your datafile:</p>
<syntaxhighlight lang="lua">
-- 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
</syntaxhighlight><br/>
      <h2>api_get_definition()</h2>
      <p>This method lets you get the definition for a given oid from the dictionary based on a given oid.<br/>See your "dictionary.json" file for the sorts of values on these dictionary tables.</p>
      {| class="wikitable"
      ! Parameter !! Datatype !! Description 
      |-
      | oid || {{D|i=integer}} || the oid to retrieve a dictionary definition for
     |}
     <p>This function will return either a {{D|i=table}} or {{D|i=nil}} if no definition was found.</p>
     <p>Example code to get the tooltip from the standard wooden axe:</p>
<syntaxhighlight lang="lua">
axe_def = api_get_definition("axe1")
tooltip = axe_def["tooltip"]
api_create_log("axe_tooltip", tooltip)
</syntaxhighlight><br/>
      <h2>api_get_equipped()</h2>
      <p>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.</p>
      <p>This method will return a {{D|i=string}}, with either an oid or empty if there's nothing equipped.</p>
     <p>Example code to do something if the player clicks with an axe:</p>
<syntaxhighlight lang="lua">
function click()
  -- check whats equipped
  equipped_item = api_get_equipped()
  if equipped_item == "axe1" then
    -- do something with the axe
  end
end
</syntaxhighlight><br/>
      <h2>api_get_filename()</h2>
      <p>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.</p>
      <p>This method will return a {{D|i=integer}}, with either {{I|i=1}}, {{I|i=2}} or {{I|i=3}}.</p>
     <p>Example code to do get the current file:</p>
<syntaxhighlight lang="lua">
function ready()
  -- check what file we are in
  file = api_get_filename()
end
</syntaxhighlight><br/>
      <h2>api_get_floor()</h2>
      <p>This method gets you the current flooring at a given position.</p>
      {| class="wikitable"
      ! Parameter !! Datatype !! Description 
      |-
      | tx || {{D|i=integer}} || the x position to check
      |-
      | ty || {{D|i=integer}} || the y position to check
     |}
     <p>This method will return a {{D|i=string}} with the following values:</p>
     {| class="wikitable"
     ! 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
    |}
     <p>Example code to check automatically place pier tiles under the player as they walk if it's empty:</p>
<syntaxhighlight lang="lua">
-- 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
</syntaxhighlight><br/>
      <h2>api_get_flowers()</h2>
      <p>This method gets a list of all the flowers currently onscreen.</p>
      {| class="wikitable"
      ! Parameter !! Datatype !! Description 
      |-
      | radius || {{D|i=integer}} || [Optional] if specified this method will get all objects within this radius from the player, rather than get all onscreen
     |}
      <p>This method will return a list of {{D|i=instance}}s, empty if there are no flowers onscreen.</p>
     <p>Example code to check how many Honeyrose flowers are around:</p>
<syntaxhighlight lang="lua">
flowers = api_get_flowers()
total = #flowers
count = 0
for i=1,total, do
  if flowers[i]["oid"] == "flower1" then 
    count = count + 1
  end
end
</syntaxhighlight><br/>
      <h2>api_get_game_size()</h2>
      <p>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 {{H|i=gui()}} hook.</p>
     <p>This method will return an {{D|i=table}} with a key for {{I|i=width}} and {{I|i=height}}, both are an {{D|i=integer}}.</p>
     <p>Example code to draw a black overlay to the game:</p>
<syntaxhighlight lang="lua">
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
</syntaxhighlight><br/>
      <h2>api_get_ground()</h2>
      <p>This method gets the ground oid at the given position. This is the actual land/water oid for the biome at that position.</p>
      {| class="wikitable"
      ! Parameter !! Datatype !! Description 
      |-
      | tx || {{D|i=integer}} || the x position to check
      |-
      | ty || {{D|i=integer}} || the y position to check
     |}
     <p>This method will return a {{D|i=string}} with the following values:</p>
     {| class="wikitable"
     ! 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)
    |}
     <p>Example code to turn the ground under the player to water as they walk:</p>
<syntaxhighlight lang="lua">
-- 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
</syntaxhighlight><br/>
      <h2>api_get_highlighted()</h2>
      <p>At any given time something is probably being highlighted by the player - this allows you to find out what!<br/>It's worth noting that {{I|i=item}}s are the floating items on the ground - not items in your menus/inventory. For that you want to use {{I|i=slot}}s.</p>
      {| class="wikitable"
      ! Parameter !! Datatype !! Description 
      |-
      | inst_type || {{D|i=string}} || the type of instance you want to check is highlighted, options are {{I|i=item}}, {{I|i=obj}}, {{I|i=menu_obj}}, {{I|i=menu}}, {{I|i=slot}}, {{I|i=ui}}, {{I|i=wall}}, {{I|i=carpet}}, and {{I|i=ground}}
     |}
     <p>This method will return an {{D|i=integer}} of the instance highlighted if any was found, otherwise it will return {{D|i=nil}}</p>
     <p>Example code to check if we are highlighting a sawbench, and add logs to it if we are:</p>
<syntaxhighlight lang="lua">
-- 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
</syntaxhighlight><br/>
      <h2>api_get_inst()</h2>
      <p>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.</p>
      {| class="wikitable"
      ! Parameter !! Datatype !! Description 
      |-
      | inst_id || {{D|i=integer}} || an instance id to get the properties for
     |}
     <p>This method will return a {{D|i=instance}} if a match is found, otherwise it will return {{D|i=nil}}</p>
     <p>Example code to get the properties of whatever is being highlighted:</p>
<syntaxhighlight lang="lua">
-- 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
</syntaxhighlight><br/>
      <h2>api_get_inst_in_rectangle()</h2>
      <p>This method lets you get a list of {{D|i=instance}}s in a given rectangle boundary.</p>
      {| class="wikitable"
      ! Parameter !! Datatype !! Description 
      |-
      | inst_type || {{D|i=string}} || the type of instance you want to check is highlighted, options are {{I|i=item}}, {{I|i=obj}}, {{I|i=tree}}, {{I|i=flower}} and {{I|i=menu_obj}}
      |-
      | x1 || {{D|i=integer}} || left x position of the rectangle box
      |-
      | y1 || {{D|i=integer}} || top y position of the rectangle box
      |-
      | x2 || {{D|i=integer}} || right x position of the rectangle box
      |-
      | y2 || {{D|i=integer}} || bottom y position of the rectangle box
     |}
     <p>This method will return a list of {{D|i=instance}}s, empty if none are found or if inst_type was invalid</p>
     <p>Example code to get all flowers in the 3x3 tile area around the player:</p>
<syntaxhighlight lang="lua">
-- 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)
</syntaxhighlight><br/>
      <h2>api_get_inst_in_circle()</h2>
      <p>This method lets you get a list of {{D|i=instance}}s in a given circle boundary.</p>
      {| class="wikitable"
      ! Parameter !! Datatype !! Description 
      |-
      | inst_type || {{D|i=string}} || the type of instance you want to check is highlighted, options are {{I|i=item}}, {{I|i=obj}}, {{I|i=tree}}, {{I|i=flower}} and {{I|i=menu_obj}}
      |-
      | x1 || {{D|i=integer}} || x center position of the circle
      |-
      | y1 || {{D|i=integer}} || y center position of the circle
      |-
      | rad || {{D|i=integer}} || radius of the circle
     |}
     <p>This method will return a list of {{D|i=instance}}s, empty if none are found or if inst_type was invalid</p>
     <p>Example code to get all trees in a circle from the mouse when clicked:</p>
<syntaxhighlight lang="lua">
function click()
  mouse = api_get_mouse_position()
  trees = api_get_inst_in_circle("tree", mouse["x"], mouse["y"], 64)
end
</syntaxhighlight><br/>
      <h2>api_get_key_down()</h2>
      <p>This method checks if a given key is being held down by the player.</p>
      {| class="wikitable"
      ! Parameter !! Datatype !! Description 
      |-
      | key_label || {{D|i=string}} || either a key character like "A" or one of the following special labels: {{I|i=LEFT}}, {{I|i=RIGHT}}, {{I|i=UP}}, {{I|i=DOWN}}, {{I|i=ENTER}}, {{I|i=ESC}}, {{I|i=SPACE}}, {{I|i=SHFT}}, {{I|i=CTRL}}, {{I|i=ALT}}, {{I|i=TAB}}
     |}
     <p>This method returns a {{D|i=boolean}} for whether the key is down or not.</p>
     <p>Example code to check if the "Shift" + "A" key is being held down:</p>
<syntaxhighlight lang="lua">
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
</syntaxhighlight><br/>
      <h2>api_get_key_pressed()</h2>
      <p>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.</p>
      {| class="wikitable"
      ! Parameter !! Datatype !! Description 
      |-
      | key_label || {{D|i=string}} || either a key character like "A" or one of the following special labels: {{I|i=LEFT}}, {{I|i=RIGHT}}, {{I|i=UP}}, {{I|i=DOWN}}, {{I|i=ENTER}}, {{I|i=ESC}}, {{I|i=SPACE}}, {{I|i=SHFT}}, {{I|i=CTRL}}, {{I|i=ALT}}, {{I|i=TAB}}
     |}
     <p>This method returns a {{D|i=boolean}} for whether the key was pressed or not.</p>
     <p>Example code to check if the "F" key was pressed:</p>
<syntaxhighlight lang="lua">
key_pressed = api_get_key_pressed("F")
if key_pressed == 1 then
  api_create_log("key_pressed", "F's in chat")
end
</syntaxhighlight><br/>
      <h2>api_get_language()</h2>
      <p>This method returns the current player's language selection as a 2-digit language code, i.e. "en".</p>
     <p>This method returns the current language code, which can be one of the following: {{I|i=en}}, {{I|i=fr}}, {{I|i=it}}, {{I|i=de}}, {{I|i=es}}, {{I|i=br}}, or {{I|i=jp}}.</p>
     <p>Example code to see if the current language is German:</p>
<syntaxhighlight lang="lua">
current_lan = api_get_language()
if current_lan == "de" then
  -- hallo!
end
</syntaxhighlight><br/>
      <h2>api_get_menu_objects()</h2>
      <p>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.</p>
      {| class="wikitable"
      ! Parameter !! Datatype !! Description 
      |-
      | radius || {{D|i=integer}} || [Optional] if specified this method will get all objects within this radius from the player, rather than get all onscreen
      |-
      | oid || {{D|i=string}} || [Optional] if specified this method will only return objs with a matching oid (see [[OID Reference]])
      |-
      | coordinate || {{D|i=coordinate}} || [Optional] if using a radius, this allows you specify the center point to use. If not given, will default to the player
     |}
      <p>This method will return a list of {{D|i=instance}}s, empty if there are no menu objects onscreen or working.</p>
     <p>Example code to find any basic apiaries nearby:</p>
<syntaxhighlight lang="lua">
-- 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
</syntaxhighlight><br/>
      <h2>api_get_menus_obj()</h2>
      <p>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.</p>
      {| class="wikitable"
      ! Parameter !! Datatype !! Description 
      |-
      | menu_id || {{D|i=integer}} || the menu instance to get the menu object inst for
     |}
      <p>This method will return either the menu object instance ad as a {{D|i=integer}}, otherwise it will return {{D|i=nil}} if not valid.</p>
     <p>Example code to set an object as immortal when it's menu define is called:</p>
<syntaxhighlight lang="lua">
function menu_define(menu_id)
  obj_id = api_get_menus_obj(menu_id)
  api_set_immortal(obj_id, true)
end
</syntaxhighlight><br/>
      <h2>api_get_mouse_inst()</h2>
      <p>This method gets the global mouse instance id, so that you can get or set its properties.<br/>For all purposes you can consider the mouse inst as just a slot, as it has most of the same properties.</p>
      <p>This method will return the mouse instance as an {{D|i=instance}}.</p>
     <p>Example code to get the mouse inst and then set the held item to something else:</p>
<syntaxhighlight lang="lua">
mouse = api_get_mouse_inst()
api_sp(mouse["id"], "item", "my_fancy_axe")
</syntaxhighlight><br/>
      <h2>api_get_mouse_position()</h2>
      <p>This method gets the current mouse position.</p>
      <p>This method will return a {{D|i=coordinate}} of the current mouse position.</p>
     <p>Example code to teleport the player to the mouse position when you click:</p>
<syntaxhighlight lang="lua">
function click()
  mouse = api_get_mouse_position()
  api_set_player_position(mouse["x"], mouse["y"])
end
</syntaxhighlight><br/>
      <h2>api_get_mouse_tile_position()</h2>
      <p>This method gets the position of the tile currently underneath the mouse</p>
      <p>This method will return a {{D|i=coordinate}} of the tile under the current mouse position.</p>
     <p>Example code to create a crate on the grid under the mouse when you click:</p>
<syntaxhighlight lang="lua">
function click()
  mouse_tile = api_get_mouse_tile_position()
  api_create_obj("crate1", mouse_tile["x"], mouse_tile["y"])
end
</syntaxhighlight><br/>
      <h2>api_get_objects()</h2>
      <p>This method gets a list of all objects currently onscreen.</p>
      {| class="wikitable"
      ! Parameter !! Datatype !! Description 
      |-
      | radius || {{D|i=integer}} || [Optional] if specified this method will get all objects within this radius from the player, rather than get all onscreen
      |-
      | oid || {{D|i=string}} || [Optional] if specified this method will only return objs with a matching oid (see [[OID Reference]])
      |-
      | coordinate || {{D|i=coordinate}} || [Optional] if using a radius, this allows you specify the center point to use. If not given, will default to the player
     |}
      <p>This method will return a list of {{D|i=instance}}s, empty if there are no objects onscreen.</p>
     <p>Example code to find the first bed nearby, if any, and teleport the player there:</p>
<syntaxhighlight lang="lua">
-- 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
</syntaxhighlight><br/>
      <h2>api_get_player_instance()</h2>
      <p>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.<br/><b>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!</b><br/>Here's some default properties that might be useful to retrieve with {{F|i=api_get_property()}}:</p>
      {| class="wikitable"
      ! Property !! Datatype !! Description 
      |-
      | name || {{D|i=string}} || the player's name
      |-
      | money || {{D|i=integer}} || the amount of rubees the player has
      |-
      | honeycore || {{D|i=integer}} || the amount of honeycore the player has
      |-
      | dir || {{D|i=string}} || the direction the player is facing, either {{I|i=left}} or {{I|i=right}}
      |-
      | sitting || {{D|i=boolean}} || whether the player is sitting on a bench
      |-
      | sleeping || {{D|i=boolean}} || whether the player is sleeping
      |-
      | sailing || {{D|i=boolean}} || whether the player is in a boat
      |-
      | hotbar || {{D|i=integer}} || the index of the slot the player has active in their hotbar, from 0-9
      |-
      | current_tile || {{D|i=string}} || the current ground oid beneath the player (see {{F|api_get_ground()}} for oid names)
     |}
      <p>This method will return a {{D|i=integer}} of the player instance id.</p>
     <p>Example code to get all the slots of the player inventory:</p>
<syntaxhighlight lang="lua">
player = api_get_player_instance()
slots = api_get_slots(player)
</syntaxhighlight><br/>
      <h2>api_get_player_position()</h2>
      <p>This method gets the player position, relative to 0,0 in the top left of the world.</p>
      <p>This method will return a {{D|i=coordinate}} of the current player position</p>
     <p>Example code to put a workbench near the current player position:</p>
<syntaxhighlight lang="lua">
player = api_get_player_position()
api_create_obj("workbench", player["x"] + 16, player["y"] - 32)
</syntaxhighlight><br/>
      <h2>api_get_player_tile_position()</h2>
      <p>This method gets the position of the tile the player is currently on, relative to 0,0 in the top left of the world.</p>
      <p>This method will return a {{D|i=coordinate}} of the tile under the current player position</p>
     <p>Example code to put a workbench on the tile under the player position:</p>
<syntaxhighlight lang="lua">
player = api_get_player_tile_position()
api_create_obj("workbench", player["x"], player["y"])
</syntaxhighlight><br/>
      <h2>api_get_property()</h2>
      <p>This method will get a given property from an instance. You can also use the shorthand "api_gp()" for this method.<br/>See [[Instance Properties]] for a full list of all built-in properties for all types of instances.</p>
      {| class="wikitable"
      ! Parameter !! Datatype !! Description 
      |-
      | inst_id || {{D|i=integer}} || instance id to get a property for
      |-
      | prop_name || {{D|i=string}} || name of the property to try and get
     |}
     <p>This method could return any datatype, depending on the property that you ask for. If it fails for some reason it will return {{D|i=nil}} and log one of the following errors to the Modding Console:</p>
     {| class="wikitable"
     ! 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
    |}
     <p>Example code to find out how much money the player has, and give them $100 if they don't have any:</p>
<syntaxhighlight lang="lua">
player = api_get_player_instance()
money = api_gp(player, "money")
if money == 0 then
  api_give_money(100)
end
</syntaxhighlight><br/>
      <h2>api_get_slot()</h2>
      <p>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.</p>
      {| class="wikitable"
      ! Parameter !! Datatype !! Description 
      |-
      | menu_id || {{D|i=integer}} || menu instance to get a slot from
      |-
      | slot_index || {{D|i=integer}} || index of the slot to get, starting at 1
     |}
     <p>This method will return a {{D|i=slot_instance}} if found, otherwise it will return {{D|i=nil}}</p>
     <p>Example code to get the first player slot:</p>
<syntaxhighlight lang="lua">
player = api_get_player_instance()
first_slot = api_get_slot(player, 1)
api_log("player_first_slot", first_slot["item"])
</syntaxhighlight><br/>
      <h2>api_get_slot_inst()</h2>
      <p>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.<br/>This is useful for using it with {{F|i=api_get_highlighted}} to save you getting the menu details first.</p>
      {| class="wikitable"
      ! Parameter !! Datatype !! Description 
      |-
      | slot_id || {{D|i=integer}} || slot instance to get properties for
     |}
     <p>This method will return a {{D|i=slot_instance}} if found, otherwise it will return {{D|i=nil}}</p>
     <p>Example code to check if the slot we are highlighting contains an axe:</p>
<syntaxhighlight lang="lua">
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
</syntaxhighlight><br/>
      <h2>api_get_slots()</h2>
      <p>This method is similar to the previous one, except it gets all of the slots for a given menu.</p>
      {| class="wikitable"
      ! Parameter !! Datatype !! Description 
      |-
      | menu_id || {{D|i=integer}} || menu instance to get a slot from
     |}
     <p>This method will return a list of {{D|i=slot_instance}} if a valid menu object, otherwise it will return {{D|i=nil}}</p>
     <p>Example code to get all of the player slots and fill them with logs, then set the first slot to be a bee:</p>
<syntaxhighlight lang="lua">
-- 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))
</syntaxhighlight><br/>
      <h2>api_get_sprite()</h2>
      <p>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.<br/>You need to prepend the oid with "sp_", for example {{I|i=sp_axe1}}.<br/><b>You can get bee sprites with by using the following format: {{I|i=sp_bee_common}}</b></p>
      {| class="wikitable"
      ! Parameter !! Datatype !! Description 
      |-
      | oid || {{D|i=string}} || sprite to get the reference for (see [[OID Reference]])
     |}
     <p>This method will return a {{D|i=integer}} for the sprite id if found otherwise it will return {{D|i=nil}}</p>
     <p>Example code to get the common bee sprite and draw with it:</p>
<syntaxhighlight lang="lua">
-- 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
</syntaxhighlight><br/>
      <h2>api_get_time()</h2>
      <p>This method will get the current game time, current day, as well as some other useful information.</p>
      <p>This method will return a {{D|i=time}}.</p>
     <p>Example code to get the current day:</p>
<syntaxhighlight lang="lua">
time = api_get_time()
day = time["day"]
if day == 7 then 
  api_log("time", "it's day 7!")
end
</syntaxhighlight><br/>
      <h2>api_get_trees()</h2>
      <p>This method will get all the trees currently onscreen.</p>
      {| class="wikitable"
      ! Parameter !! Datatype !! Description 
      |-
      | radius || {{D|i=integer}} || [Optional] if specified this method will get all objects within this radius from the player, rather than get all onscreen
     |}
      <p>This method will return a list of {{D|i=instance}}s, empty if there are no trees onscreen (Hivemother forbid).</p>
     <p>Example code to see how many trees are onscreen:</p>
<syntaxhighlight lang="lua">
trees = api_get_trees()
total = #trees
</syntaxhighlight><br/>
      <h2>api_get_weather()</h2>
      <p>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.</p>
      <p>This method will return a {{D|i=weather}}</p>
     <p>Example code to get see if it's raining or snowing:</p>
<syntaxhighlight lang="lua">
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
</syntaxhighlight>
    </div>
  </div><br/>

  <div class="aw-api-section mw-customcollapsible-s1">
    <h1>[[File:Mainlander_Money_Item.png|32px]]Give Methods</h1>
    <p>Give methods allow you to give things directly to the player, be it items or money.</p>
    {| class="wikitable"
     ! Method !! Description 
     |-
     | {{F|i=api_give_honeycore()}} || gives an amount of Honeycore to the player
     |-
     | {{F|i=api_give_item()}} || gives an amount of a specific item to the player
     |-
     | {{F|i=api_give_money()}} || gives an amount of Rubees to the player
    |}
    <div class="mw-collapsible mw-collapsed" id="mw-customcollapsible-s1">
      <h2>api_give_honeycore()</h2>
      <p>Gives a certain amount of Honeycore to the player.</p>
     {| class="wikitable"
      ! Parameter !! Datatype !! Description 
      |-
      | amount || {{D|i=integer}} || the amount to give
     |}
<syntaxhighlight lang="lua">
-- give 10 honeycore
api_give_honeycore(10)
</syntaxhighlight><br/>
      <h2>api_give_item()</h2>
      <p>Gives a certain amount of a specific item to the player.</p>
     {| class="wikitable"
      ! Parameter !! Datatype !! Description 
      |-
      | item_oid || {{D|i=string}} || the item oid to give
      |-
      | amount || {{D|i=integer}} || the amount to give
     |}
<syntaxhighlight lang="lua">
-- give 9999 logs
api_give_item("log", 9999)
</syntaxhighlight><br/>
      <h2>api_give_money()</h2>
      <p>Gives a certain amount of Rubees to the player.</p>
     {| class="wikitable"
      ! Parameter !! Datatype !! Description 
      |-
      | amount || {{D|i=integer}} || the amount to give
     |}
<syntaxhighlight lang="lua">
-- give 420 money
api_give_money(420)
</syntaxhighlight>
    </div>
  </div><br/>

  <div class="aw-api-section mw-customcollapsible-s1">
    <h1>[[File:Skipper.png|32px]]Misc Methods</h1>
    <p>These are misc. methods that don't fit in with one general theme and act as helpers.</p>
    {| class="wikitable"
     ! Method !! Description 
     |-
     | {{F|i=api_add_slot_to_menu()}} || tries to add the contents of a given slot to a given menu
     |-
     | {{F|i=api_blacklist_input()}} || blacklists a specific object oid from input meaning normal key presses are ignored while its menu is highlighted
     |-
     | {{F|i=api_check_discovery()}} || checks if a player has discovered (picked up) a given item
     |-
     | {{F|i=api_choose()}} || picks randomly from a list of items and returns the result
     |-
     | {{F|i=api_destroy_inst()}} || destroys an instance permanently
     |-
     | {{F|i=api_http_request()}} || sends a HTTP request to a specific endpoint
     |-
     | {{F|i=api_inst_exists()}} || checks if an inst exists
     |-
     | {{F|i=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)
     |-
     | {{F|i=api_play_sound()}} || plays a given game sound
     |-
     | {{F|i=api_random()}} || returns a random number between 0-X, where X is given 
     |-
     | {{F|i=api_random_range()}} || returns a random number between a range or X-Y, where X and Y are given
     |-
     | {{F|i=api_refresh_tooltip()}} || refreshes the tooltip cache to update with new values (if any)
     |-
     | {{F|i=api_remove_gui()}} || removes a menu gui instance made with {{F|i=api_define_gui()}}
     |-
     | {{F|i=api_toggle_menu()}} || toggles a menu instance to be open or closed
     |-
     | {{F|i=api_unlock_quest()}} || unlocks a specified quest based on it's given quest id
    |}
    <div class="mw-collapsible mw-collapsed" id="mw-customcollapsible-s1">
      <h2>api_add_slot_to_menu()</h2>
      <p>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.<br/><br/>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)</p>
      {| class="wikitable"
       ! Parameter !! Datatype !! Description 
       |-
       | slot_id || {{D|i=integer}} || the slot id of the slot you want to move the contents for 
       |-
       | menu_id || {{D|i=integer}} || the menu id of the menu inst you want to try and move the slot contents to
      |}
      <p>Example code to move the contents of the player's first slot into another menu:</p>
<syntaxhighlight lang="lua">
player = api_get_player_instance()
player_slots = api_get_slots(player)

api_add_slot_to_menu(player_slots[1]["id"], MY_OTHER_MENU_ID)
</syntaxhighlight><br/>
      <h2>api_blacklist_input()</h2>
      <p>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.<br/><b>The "Escape" key (or whatever is mapped to menu close) is the only exception not blacklisted.</b></p>
      {| class="wikitable"
       ! Parameter !! Datatype !! Description 
       |-
       | oid || {{D|i=string}} || the object oid you want to blacklist from input, should be a menu_object oid (see [[OID Reference]])
      |}
      <p>Example code to blacklist input on a custom defined menu object:</p>
<syntaxhighlight lang="lua">
api_blacklist_input("custom_sign")
</syntaxhighlight><br/>
      <h2>api_check_discovery()</h2>
      <p>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.</p>
      {| class="wikitable"
       ! Parameter !! Datatype !! Description 
       |-
       | oid || {{D|i=string}} || the item oid you want to check discovery for (see [[OID Reference]])
      |}
      <p>This method will return a {{D|i=boolean}} based on whether the item is discovered or not.</p>
      <p>Example code to check the discovery of a few items:</p>
<syntaxhighlight lang="lua">
unlocked_dream_bee = api_check_discovery("bee:dream")

unlocked_honeycore_axe = api_check_discovery("axe3")

unlocked_bee_book = api_check_discovery("book2")
</syntaxhighlight><br/>
      <h2>api_choose()</h2>
      <p>This method picks randomly from a list of items you give it and returns the result.</p>
      {| class="wikitable"
       ! Parameter !! Datatype !! Description 
       |-
       | items || {{D|i=list}} || list of items you want to pick from
      |}
      <p>Example code to pick from 3 items:</p>
<syntaxhighlight lang="lua">
-- pick a random item from a pool
item_to_give = api_choose({"axe1", "log", "planks1"})
</syntaxhighlight><br/>
      <h2>api_destroy_inst()</h2>
      <p>This method will destroy a given instance, assuming it exists.</p>
      {| class="wikitable"
       ! Parameter !! Datatype !! Description 
       |-
       | inst_id || {{D|i=integer}} || the id of the instance you want to destroy
      |}
      <p>This method either returns {{I|i=Success}} if the request was sent, otherwise if it fails it will return {{D|i=nil}} and will log an error in the Modding console with one of the following errors:</p>
      {| class="wikitable"
       ! Error !! Description
       |-
       | Invalid Instance ID || instance given does not exists
      |}
      <p>Example code to delete all trees onscreen as you walk:</p>
<syntaxhighlight lang="lua">
function tick()
  trees = api_get_trees()
  len = #trees
  for i=1,len do
    api_destroy_inst(trees[i]["id"])
  end
end
</syntaxhighlight><br/>
      <h2>api_http_request()</h2>
      <p>This method will send a HTTP request to a given endpoint.<br/><br/>You will need to implement the {{H|i=http()}} hook to handle the response as this is an asynchronous call.</p>
      {| class="wikitable"
       ! Parameter !! Datatype !! Description 
       |-
       | url || {{D|i=string}} || the full URL to send the HTTP request to
       |-
       | method_type || {{D|i=string}} || the HTTP method type, i.e. GET or POST
       |-
       | headers || {{D|i=table}} || a map of headers to apply to your request
       |-
       | body || {{D|i=string}} || a body to send with the request (can just be an empty string)
      |}
      <p>This method either returns {{I|i=Success}}, otherwise if it fails it will return {{D|i=nil}} and will log an error in the Modding console with one of the following errors:</p>
      {| class="wikitable"
       ! Error !! Description
       |-
       | Failed To Send Request || generic catch-all, check your parameters
      |}
      <p>Example code to handle some random HTTP call to get the APICO website homepage:</p>
<syntaxhighlight lang="lua">
-- 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
</syntaxhighlight><br/>
      <h2>api_inst_exists()</h2>
      <p>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.</p>
      {| class="wikitable"
       ! Parameter !! Datatype !! Description 
       |-
       | inst_id || {{D|i=integer}} || the id of the instance you want to check exists
      |}
      <p>This method returns a {{D|i=boolean}} based on if the instance was found or not.</p>
      <p>Example code to check a saved instance id exists still:</p>
<syntaxhighlight lang="lua">
inst = MY_SAVED_INST
if (api_inst_exists(inst)) then
  -- do something cool
end
</syntaxhighlight><br/>
      <h2>api_library_add_book()</h2>
      <p>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.<br/><br/><b>Note: This will NOT define a book for you, you must handle that yourself. See the [https://github.com/APICO-Modders/APICO-Sample-Mod Sample Mod] for an example book implementation.</b></p>
      {| class="wikitable"
       ! Parameter !! Datatype !! Description 
       |-
       | book_name || {{D|i=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 || {{D|i=string}} || script to be run when the book is clicked, must be in your mod code somewhere
       |-
       | book_sprite || {{D|i=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)
      |}
      <p>This method either returns {{I|i=Success}}, otherwise if it fails it will return {{D|i=nil}} and will log an error in the Modding console with one of the following errors:</p>
      {| class="wikitable"
       ! 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)
      |}
      <p>Example code to add a book button that calls a custom script:</p>
<syntaxhighlight lang="lua">
-- 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
</syntaxhighlight><br/>
      <h2>api_play_sound()</h2>
      <p>This method will play a given sound from the base game sounds.</p>
      {| class="wikitable"
       ! Parameter !! Datatype !! Description 
       |-
       | name || {{D|i=string}} || the sound name to play, current options are {{I|i=break}}, {{I|i=click}}, {{I|i=confetti}}, {{I|i=error}}, {{I|i=jingle}}, {{I|i=open}}, {{I|i=plop}}, {{I|i=pop}}, or {{I|i=rollover}}
      |}
      <p>This method either returns {{I|i=Success}}, otherwise if it fails it will return {{D|i=nil}} and will log an error in the Modding console with one of the following errors:</p>
      {| class="wikitable"
       ! Error !! Description
       |-
       | Invalid Instance ID || instance given does not exist
      |}
      <p>Example code to delete all trees onscreen as you walk:</p>
<syntaxhighlight lang="lua">
function tick()
  trees = api_get_trees()
  len = #trees
  for i=1,len do
    api_destroy_inst(trees[i]["id"])
  end
end
</syntaxhighlight><br/>
      <h2>api_random()</h2>
      <p>This returns a random number between 0 and the number you give it</p>
      {| class="wikitable"
       ! Parameter !! Datatype !! Description 
       |-
       | max || {{D|i=integer}} || the max number to be returned
      |}
      <p>Example code to get a number between 0 and 9:</p>
<syntaxhighlight lang="lua">
-- get a number between 0-9
random_number = api_random(9)
</syntaxhighlight><br/>
      <h2>api_random_range()</h2>
      <p>This returns a random number between a given range of numbers.</p>
      {| class="wikitable"
       ! Parameter !! Datatype !! Description 
       |-
       | start_num || {{D|i=integer}} || number for range to start at
       |-
       | end_num || {{D|i=integer}} || number for range to end at
      |}
      <p>Example code to get a number between 5 and 10:</p>
<syntaxhighlight lang="lua">
-- get a random number between 5 and 10
random_number = api_random_range(5, 10)
</syntaxhighlight><br/>
      <h2>api_refresh_tooltip()</h2>
      <p>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.<br/>Calling this method will reset the cache and make a new tooltip.</p>
      <p>Example code to refresh the tooltip after a click:</p>
<syntaxhighlight lang="lua">
function click()

  api_refresh_tooltip()

end
</syntaxhighlight><br/>
      <h2>api_remove_gui()</h2>
      <p>This destroys a GUI instance created with {{F|i=api_define_gui()}}. This is seperate to {{F|i=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.</p>
      {| class="wikitable"
       ! Parameter !! Datatype !! Description 
       |-
       | menu_id || {{D|i=integer}} || the menu inst ID that you defined the GUI on in the first place
       |-
       | gui_key || {{D|i=string}} || the gui key you used when defining the GUI
      |}
      <p>This method either returns {{I|i=Success}}, otherwise if it fails it will return {{D|i=nil}} and will log an error in the Modding console with one of the following errors:</p>
      {| class="wikitable"
       ! 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
      |}
      <p>Example code to remove an existing custom GUI:</p>
<syntaxhighlight lang="lua">
api_remove_gui(MY_MENU_ID, "custom_button_thing")
</syntaxhighlight><br/>
      <h2>api_toggle_menu()</h2>
      <p>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!</p>
      {| class="wikitable"
       ! Parameter !! Datatype !! Description 
       |-
       | menu_id || {{D|i=integer}} || the menu instance to open or close
       |-
       | toggle || {{D|i=string}} || how you want to toggle the menu, either {{I|i=open}} or {{I|i=close}}
      |}
      <p>Example code to open a menu when highlighting the object and pressing "X":</p>
<syntaxhighlight lang="lua">
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
</syntaxhighlight><br/>
      <h2>api_unlock_quest()</h2>
      <p>This lets you force unlock a quest you have defined (or a vanilla one!)<br/><b>Note: This will always fail in the {{H|i=init()}} hook for custom quests! You need to use it in the {{H|i=ready()}} hook or later hooks, as the custom quest is only given progress values once the init is finished for all mods.</b></p>
      {| class="wikitable"
       ! Parameter !! Datatype !! Description 
       |-
       | quest_id || {{D|i=string}} || the quest id used when defining your quest 
      |}
      <p>This method either returns {{I|i=Success}}, otherwise if the quest id wasn't found it will return {{D|i=nil}}.</p>
      <p>Example code to unlock a defined quest:</p>
<syntaxhighlight lang="lua">
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
</syntaxhighlight>
  </div><br/>

  <div class="aw-api-section mw-customcollapsible-s1">
    <h1>[[File:Workbench_Item.png|32px]]Mod Methods</h1>
    <p>Mod methods let you call other mods that may or not be loaded. You should check a mod exists first in the {{H|i=ready()}} hook before attempting to interact with it.</p>
    {| class="wikitable"
     ! Method !! Description 
     |-
     | {{F|i=api_mod_exists}} || checks if a given mod exists / is loaded
     |-
     | {{F|i=api_mod_call}} || calls a function from another mod and returns the result
    |}
    <div class="mw-collapsible mw-collapsed" id="mw-customcollapsible-s1">
      <h2>api_mod_exists()</h2>
      <p>This checks is a given mod exists and is registered and initialised correctly.</p>
      {| class="wikitable"
       ! Parameter !! Datatype !! Description 
       |-
       | mod_name || {{D|i=string}} || the unique mod name for the mod
      |}
      <p>This method returns a {{D|i=boolean}} based on whether the mod exists or not.</p>
      <p>Example code to check if another mod exists:</p>
<syntaxhighlight lang="lua">
-- 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
</syntaxhighlight><br/>
      <h2>api_mod_call()</h2>
      <p>This lets you call a function from another mod assuming that mod exists</p>
      {| class="wikitable"
       ! Parameter !! Datatype !! Description 
       |-
       | mod_name || {{D|i=string}} || the unique mod name for the mod
       |-
       | method_name || {{D|i=string}} || the method to call in the other mod's file
       |-
       | args || {{D|i=list}} || [Optional] a list of args to pass in
      |}
      <p>This method either returns whatever the other mods method returns, otherwise if it fails it will return {{D|i=nil}} and will log an error in the Modding console with one of the following errors:</p>
      {| class="wikitable"
       ! Error !! Description
       |-
       | Failed To Invoke Method || if the function call fails this will detail the issue it came across
      |}
      <p>Example code to call a function from another mod:</p>
<syntaxhighlight lang="lua">
-- 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
</syntaxhighlight>
    </div>
  </div><br/>

  <div class="aw-api-section mw-customcollapsible-s1">
    <h1>[[File:Stone_Axe_Item.png|32px]]Set Methods</h1>
    <p>Set methods let you set properties or values, like setting the player position or changing the time of day.</p>
    {| class="wikitable"
     ! Method !! Description 
     |-
     | {{F|i=api_set_blueprint()}} || overrides the worldgen blueprints with your own custom blueprint
     |-
     | {{F|i=api_set_data()}} || sets the mods own JSON datafile 
     |-
     | {{F|i=api_set_devmode()}} || toggles devmode in the game, turning on FPS meter + allowing inline commands
     |-
     | {{F|i=api_set_floor()}} || sets the floor tile at a given position
     |-
     | {{F|i=api_set_ground()}} || sets the ground at a given position
     |-
     | {{F|i=api_set_immortal()}} || sets a menu object to be "immortal" meaning it'll stay active regardless of it it's no longer working
     |-
     | {{F|i=api_set_menu_position()}} || sets the position of a menu instance, updating any gui/buttons for you
     |-
     | {{F|i=api_set_notification()}} || sets a notification to show to the player
     |-
     | {{F|i=api_set_player_position()}} || sets the player's position
     |-
     | {{F|i=api_set_position()}} || sets the position for a given instance id
     |-
     | {{F|i=api_set_property()}} {{F|i=api_sp}} || sets a property on a given instance id
     |-
     | {{F|i=api_set_spawn()}} || sets the player spawn position which is used if the player gets stuck
     |-
     | {{F|i=api_set_time()}} || sets the game time
     |-
     | {{F|i=api_set_tooltip()}} || sets the tooltip for a given oid's dictionary definition
     |-
     | {{F|i=api_set_weather()}} || sets the game weather
    |}
    <div class="mw-collapsible mw-collapsed" id="mw-customcollapsible-s1">
      <h2>api_set_blueprint()</h2>
      <p>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 {{H|i=worldgen()}} hook.<br/>For reference, game worlds are 350x350 tiles, with 290x290 being visible on the map and rest being reserved for secret areas.<br/><b>This must be called in the {{H|i=init()}} hook to work.</b></p>
      {| class="wikitable"
       ! Parameter !! Datatype !! Description 
       |-
       | blueprints || list({{D|i=blueprint}}) || the blueprints you want to use, each blueprint being a "blob" of land you define
       |-
       | blank || list({{D|i=boolean}}) || if true this will mean that no objects are created during the worldgen, giving you an entirely blank world with only grass/water
      |}
      <p>Example code to change the worldgen to just be one big tundra island:</p>
<syntaxhighlight lang="lua">
blueprint = {}
blueprint[1] = {
  width = 200,
  height = 200,
  x = 50,
  y = 50,
  type = "snow",
  dye = 15
}
api_set_blueprint(blueprint, false)
</syntaxhighlight><br/>
      <h2>api_set_data()</h2>
      <p>This method allows you to set the contents of your mods {{I|i=data.json}} file that you can retrieve through {{F|i=api_get_data()}}. This lets your store data across sessions - you can use the {{H|i=save()}} hook to check when the player or game has saved.<br/>As file load/save is asynchronous you will need to use the {{H|i=data()}} hook to handle the response to check if it worked.</p>
      {| class="wikitable"
       ! Parameter !! Datatype !! Description 
       |-
       | json_data || {{D|i=table}} || a table of data that will be turned into JSON
      |}
      <p>This method will either return {{I|i=Success}} if everything worked, otherwise if it fails it will return {{D|i=nil}} and will log an error in the Modding console with one of the following errors:</p>
      {| class="wikitable"
       ! Error !! Description
       |-
       | Invalid JSON String || the table you provided couldn't be parsed into valid JSON
      |}
      <p>Example code to save some data to the {{I|i=data.json}} file:</p>
<syntaxhighlight lang="lua">
-- 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
</syntaxhighlight><br/>
      <h2>api_set_devmode()</h2>
      <p>Your other best friend along with {{F|i=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 {{I|i=/}} and let's you run commands like {{I|i=/gimme log 5}} or {{I|i=/weather on}}.<br/>It will also show the FPS meter so you can check performance.</p>
      {| class="wikitable"
       ! Parameter !! Datatype !! Description 
       |-
       | dev_mode || {{D|i=boolean}} || whether to turn dev mode on or off.
      |}
      <p>Example code to turn on devmode when the mod initialises:</p>
<syntaxhighlight lang="lua">
function init()
  api_set_devmode(true)
end
</syntaxhighlight><br/>
      <h2>api_set_floor()</h2>
      <p>This method sets the floor tile at a given position.</p>
      {| class="wikitable"
       ! Parameter !! Datatype !! Description 
       |-
       | floor_oid || {{D|i=string}} || the floor oid to set, see below for details
       |-
       | tx || {{D|i=integer}} || the x position to set the tile, will be rounded to the grid
       |-
       | ty || {{D|i=integer}} || the y position to set the tile, will be rounded to the grid
      |}
      <p>This following floor oids are available to use:</p>
      {| class="wikitable"
      ! 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
     |}
      <p>If this method fails it will log an error in the Modding console with one of the following errors:</p>
      {| class="wikitable"
       ! Error !! Description
       |-
       | Invalid Floor ID || you didn't use one of the floor oids listed above
      |}
      <p>Example code to set the floor underneath the player to tiles (auto-tiler, nice!):</p>
<syntaxhighlight lang="lua">
-- 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
</syntaxhighlight><br/>
      <h2>api_set_ground()</h2>
      <p>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.</p>
      {| class="wikitable"
       ! Parameter !! Datatype !! Description 
       |-
       | ground_oid || {{D|i=string}} || the ground oid you want to set
       |-
       | tx || {{D|i=integer}} || the x position to set the tile, will be rounded to the grid
       |-
       | ty || {{D|i=integer}} || the y position to set the tile, will be rounded to the grid
      |}
      <p>This following ground oids are available to use:</p>
      {| class="wikitable"
      ! 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)
     |}
      <p>If this method fails it will log an error in the Modding console with one of the following errors:</p>
      {| class="wikitable"
       ! Error !! Description
       |-
       | Invalid Tile ID || you didn't use one of the ground oids listed above
      |}
      <p>Example code to set the ground beneath the player to swamp grass:</p>
<syntaxhighlight lang="lua">
-- 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
</syntaxhighlight><br/>
      <h2>api_set_immortal()</h2>
      <p>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.<br/><b>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.</b></p>
      {| class="wikitable"
       ! Parameter !! Datatype !! Description 
       |-
       | menu_obj_id || {{D|i=integer}} || the id of the menu object instance you want to immortalise
       |-
       | bool || {{D|i=boolean}} || whether to set the property to true or false
      |}
      <p>This method will either return {{I|i=Success}} if everything worked, otherwise if it fails it will return {{D|i=nil}} and will log an error in the Modding console with one of the following errors:</p>
      {| class="wikitable"
       ! 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
      |}
      <p>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:</p>
<syntaxhighlight lang="lua">
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
</syntaxhighlight><br/>
      <h2>api_set_menu_position()</h2>
      <p>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 {{D|menu_definition}}'s "center" property.<br/>Combined with {{F|api_toggle_menu()}} this would allow you to open a menu object from anywhere and show the menu anywhere.</p>
      {| class="wikitable"
       ! Parameter !! Datatype !! Description 
       |-
       | menu_id || {{D|i=integer}} || the menu you want to move (note: not the menu object id)
       |-
       | mx || {{D|i=integer}} || the x position you want to move the menu to
       |-
       | my || {{D|i=integer}} || the y position you want to move the menu to
      |}
      <p>This method will either return {{I|i=Success}} if everything worked, otherwise if it fails it will return {{D|i=nil}} and will log an error in the Modding console with one of the following errors:</p>
      {| class="wikitable"
       ! Error !! Description
       |-
       | Menu Instance Doesn't Exist || given menu instance id
      |}
      <p>Example code to open and move a previously created menu objects menu:</p>
<syntaxhighlight lang="lua">
-- 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"])
</syntaxhighlight><br/>
      <h2>api_set_notification()</h2>
      <p>This method lets you set your own notification, either with a standard notification type of your own custom notification type.<br/>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 {{F|i=api_define_notification()}}</p>
      {| class="wikitable"
       ! Parameter !! Datatype !! Description 
       |-
       | notification_type || {{D|i=string}} || a notification type, either your own or one of the standard types: {{I|i=workbench}}, {{I|i=quest}}, {{I|i=bees}}, {{I|i=microscope}}, {{I|i=flowers}}, {{I|i=weather}}, {{I|i=altar}}, {{I|i=buff}}, {{I|i=mag}}, {{I|i=notice}}
       |-
       | item_oid || {{D|i=string}} || the item oid to show in the notification icon (see [[OID Reference]])
       |-
       | title || {{D|i=string}} || the title to show in the notification
       |-
       | msg || {{D|i=string}} || the message to show in the notification
      |}
      <p>Example code to piggyback the "notice" type notification to show our own message:</p>
<syntaxhighlight lang="lua">
api_set_notification("notice", "axe3", "You are cool", "You are so damn cool")
</syntaxhighlight><br/>
      <h2>api_set_player_position()</h2>
      <p>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.</p>
      {| class="wikitable"
       ! Parameter !! Datatype !! Description 
       |-
       | px || {{D|i=integer}} || the x position you want to set
       |-
       | py || {{D|i=integer}} || the y position you want to set
      |}
      <p>Example code to teleport the player the mouse position when clicking:</p>
<syntaxhighlight lang="lua">
function click()
  mouse = api_get_mouse_tile_position
  api_set_player_position(mouse["x"], mouse["y"])
end
</syntaxhighlight><br/>
      <h2>api_set_position()</h2>
      <p>This method lets you set the position of any given instance.</p>
      {| class="wikitable"
       ! Parameter !! Datatype !! Description 
       |-
       | inst_id || {{D|i=integer}} || the instance you want to move
       |-
       | px || {{D|i=integer}} || the x position you want to set
       |-
       | py || {{D|i=integer}} || the y position you want to set
      |}
      <p>This method will either return {{I|i=Success}} if everything worked, otherwise if it fails it will return {{D|i=nil}} and will log an error in the Modding console with one of the following errors:</p>
      {| class="wikitable"
       ! Error !! Description
       |-
       | Instance Doesn't Exist || instance id given doesn't exist, or isn't active
      |}
      <p>Example code to move whatever is highlighted to a random position on the map:</p>
<syntaxhighlight lang="lua">
-- 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)
</syntaxhighlight><br/>
      <h2>api_set_property()</h2>
      <p>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.<br/><b>When setting custom properties on menu objects you should add the prop_name to the related menu's {{I|i=menu._fields}} list key if you want to keep it persistent when the player saves (see {{F|i=api_define_menu_object()}} for an example)</b><br/>See [[Instance Properties]] for a full list of all built-in properties for all types of instances.</p>
      {| class="wikitable"
       ! Parameter !! Datatype !! Description 
       |-
       | inst_id || {{D|i=integer}} || the instance you want to set a property for
       |-
       | prop_name || {{D|i=string}} || the name of the property you want to set
       |-
       | prop_value || Any || the value for the property
      |}
      <p>This method will either return {{I|i=Success}} if everything worked, otherwise if it fails it will return {{D|i=nil}} and will log an error in the Modding console with one of the following errors:</p>
      {| class="wikitable"
       ! 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?
      |}
      <p>Example code to cycle through the highlighted objects sprite frames:</p>
<syntaxhighlight lang="lua">
function tick() 
  highlighted = api_get_highlighted("obj")
  if highlighted ~= nil then
    api_sp(highlighted, "image_index", api_gp(highlighted, "image_index") + 1)
  end
end
</syntaxhighlight><br/>
      <h2>api_set_spawn()</h2>
      <p>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.</p>
      {| class="wikitable"
       ! Parameter !! Datatype !! Description 
       |-
       | px || {{D|i=integer}} || the x position you want to set
       |-
       | py || {{D|i=integer}} || the y position you want to set
      |}
      <p>Example code to set the spawn position:</p>
<syntaxhighlight lang="lua">
api_set_spawn(100, 100)
</syntaxhighlight><br/>
      <h2>api_set_time()</h2>
      <p>This method lets you update the in-game time, either to a set time or a raw time in ms</p>
      {| class="wikitable"
       ! Parameter !! Datatype !! Description 
       |-
       | time || {{D|i=string}} || a preset time point in the day to use, options are {{I|i=dawn_start}}, {{I|i=dawn_mid}}, {{I|i=day_start}}, {{I|i=dusk_start}}, {{I|i=dusk_mid}}, {{I|i=night_start}}, or {{I|i=night_end}}
       |-
       | raw_ms || {{D|i=integer}} || [Optional] instead of a preset you can set a raw time in ms - see {{D|i=time}} for more info
      |}
      <p>This method will either return {{I|i=Success}} if everything worked, otherwise if it fails it will return {{D|i=nil}} and will log an error in the Modding console with one of the following errors:</p>
      {| class="wikitable"
       ! Error !! Description
       |-
       | Invalid Time Value || time value set wasn't from the list of options above
      |}
      <p>Example code to the time to 8am:</p>
<syntaxhighlight lang="lua">
-- one game hour is 60000ms (1 minute)
time = 60000 * 8
api_set_time("", time)
</syntaxhighlight><br/>
      <h2>api_set_tooltip()</h2>
      <p>This method lets change the dictionary tooltip for a given oid's definition. You can use this to make dynamic tooltips for different objects.</p>
      {| class="wikitable"
       ! Parameter !! Datatype !! Description 
       |-
       | oid || {{D|i=string}} || the oid of the definition you want to update, i.e. {{I|i=axe1}}
       |-
       | tooltip || {{D|i=string}} || the tooltip string you want to use instead
      |}
      <p>This method will either return {{I|i=Success}} if everything worked, otherwise if it fails it will return {{D|i=nil}} and will log an error in the Modding console with one of the following errors:</p>
      {| class="wikitable"
       ! Error !! Description
       |-
       | Definition For OID Doesn't Exist || given oid is not defined in the dictionary
      |}
      <p>Example code to change the tooltip for the spade:</p>
<syntaxhighlight lang="lua">
api_set_tooltip("spade1", "Diggy diggy hole")
</syntaxhighlight><br/>
      <h2>api_set_weather()</h2>
      <p>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.<br/>The type of weather is based on the biome the player is currently in, weather as a property is either on or off.</p>
      {| class="wikitable"
       ! Parameter !! Datatype !! Description 
       |-
       | start_time || {{D|i=integer}} || the time in ms for the weather to start - see {{D|i=time}} for more info
       |-
       | end_time || {{D|i=integer}} || the time in ms for the weather to end - see {{D|i=time}} for more info
      |}
      <p>Example code to make it rain between 7am and 10am:</p>
<syntaxhighlight lang="lua">
-- one game hour is 60000ms (1 minute)
start_time = 60000 * 7
end_time = 60000 * 10
api_set_weather(start_time, end_time)
</syntaxhighlight>
    </div>
  </div><br/>

  <div class="aw-api-section mw-customcollapsible-s1">
    <h1>[[File:Frame1_Item.png|32px]]Slot Methods</h1>
    <p>Slot methods let you easily interact with slots, which is useful for any sort of custom menu object logic.</p>
    {| class="wikitable"
     ! Method !! Description 
     |-
     | {{F|i=api_slot_clear()}} || clears a slot and makes it empty
     |-
     | {{F|i=api_slot_decr()}} || decreases a slot amount, if reduced to 0 the slot will be cleared
     |-
     | {{F|i=api_slot_drain()}} || starts a drain action with a given slot, draining the menu's tank into this slot
     |-
     | {{F|i=api_slot_fill()}} || starts a fill action with a given slot, filling the menu's tank from this slot
     |-
     | {{F|i=api_slot_incr()}} || increases a slot amount, capped at 99
     |-
     | {{F|i=api_slot_item_id()}} || gets a special item data id for a given slot, mainly used by Ell in his weird mods
     |-
     | {{F|i=api_slot_match()}} || finds a slot/slots that match certain criteria based on the items they have (or dont have)
     |-
     | {{F|i=api_slot_match_range()}} || same as above but specifies a range of slots that the match will check instead of all menu slots
     |-
     | {{F|i=api_slot_set()}} || sets a slot to have a specific item in it
     |-
     | {{F|i=api_slot_set_inactive()}} || sets a slot to be inactive (no hover or click interactions)
     |-
     | {{F|i=api_slot_set_modded()}} || sets a slot to be modded (hover interactions but no click interactions)
     |-
     | {{F|i=api_slot_redraw()}} || redraws a slot and it's item
     |-
     | {{F|i=api_slot_validate()}} || validates a given item/stats combination for a given slot
    |}
    <div class="mw-collapsible mw-collapsed" id="mw-customcollapsible-s1">
      <h2>api_slot_clear()</h2>
      <p>This method will clear a given slot, making it empty.</p>
      {| class="wikitable"
       ! Parameter !! Datatype !! Description 
       |-
       | slot_id || {{D|i=integer}} || the slot id of the slot instance you want to clear
      |}
      <p>If this method worked it will return {{I|i=Success}}, otherwise if it fails it will return {{D|i=nil}} and will log an error in the Modding Console with one of the following errors:</p>
      {| class="wikitable"
      ! Error !! Description 
      |-
      | Failed To Clear Slot || generic error catch, shouldn't really see this.
     |}
     <p>Example code to clear the first slot of the menu object that's been clicked on:</p>
<syntaxhighlight lang="lua">
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
</syntaxhighlight><br/>
      <h2>api_slot_decr()</h2>
      <p>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.</p>
      {| class="wikitable"
       ! Parameter !! Datatype !! Description 
       |-
       | slot_id || {{D|i=integer}} || the slot id of the slot instance you want to clear
       |-
       | amount || {{D|i=integer}} || [Optional] amount to decrease by, defaults to 1
      |}
      <p>If this method worked it will return {{I|i=Success}}, otherwise if it fails it will return {{D|i=nil}} and will log an error in the Modding Console with one of the following errors:</p>
      {| class="wikitable"
      ! Error !! Description 
      |-
      | Failed To Decrease Slot || generic error catch, shouldn't really see this.
     |}
     <p>Example code to reduce the amount of the first player slot:</p>
<syntaxhighlight lang="lua">
-- 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)
</syntaxhighlight><br/>
      <h2>api_slot_drain()</h2>
      <p>This method will drain a menu's tank into the given slot, assuming the slot has something it can drain into (canister1 or canister2).<br/>This method will only work with a slot that is part of a menu you defined a tank on with {{F|i=api_define_tank}}.</p>
      {| class="wikitable"
       ! Parameter !! Datatype !! Description 
       |-
       | menu_id || {{D|i=integer}} || the menu id for the slot you want to drain into, this menu must have a tank defined
       |-
       | slot_index || {{D|i=integer}} || the slot index in the menu you want to drain to, starting at 1
      |}
      <p>If this method worked it will return {{I|i=Success}}, otherwise if it fails it will return {{D|i=nil}} and will log an error in the Modding Console with one of the following errors:</p>
      {| class="wikitable"
      ! Error !! Description 
      |-
      | Menu Instance Doesn't Exist || given menu instance doesn't exist.
     |}
     <p>Example code to drain water from a tank into a slot when the slot has a canister put in it:</p>
<syntaxhighlight lang="lua">
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
</syntaxhighlight><br/>
      <h2>api_slot_fill()</h2>
      <p>This method will fill a menu's tank into the given slot, assuming the slot has something it can fill from (canister1 or canister2).<br/>This method will only work with a slot that is part of a menu you defined a tank on with {{F|i=api_define_tank}}.</p>
      {| class="wikitable"
       ! Parameter !! Datatype !! Description 
       |-
       | menu_id || {{D|i=integer}} || the menu id for the slot you want to fill into, this menu must have a tank defined
       |-
       | slot_index || {{D|i=integer}} || the slot index in the menu you want to fill from, starting at 1
      |}
      <p>If this method worked it will return {{I|i=Success}}, otherwise if it fails it will return {{D|i=nil}} and will log an error in the Modding Console with one of the following errors:</p>
      {| class="wikitable"
      ! Error !! Description 
      |-
      | Menu Instance Doesn't Exist || given menu instance doesn't exist.
     |}
     <p>Example code to drain water from a tank into a slot when the slot has a canister put in it:</p>
<syntaxhighlight lang="lua">
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
</syntaxhighlight><br/>
      <h2>api_slot_incr()</h2>
      <p>This method will increase a slot count by the amount given, or 1 if no amount specified. It will cap out automatically at 99.</p>
      {| class="wikitable"
       ! Parameter !! Datatype !! Description 
       |-
       | slot_id || {{D|i=integer}} || the slot id of the slot instance you want to clear
       |-
       | amount || {{D|i=integer}} || [Optional] amount to increase by, defaults to 1
      |}
      <p>If this method worked it will return {{I|i=Success}}, otherwise if it fails it will return {{D|i=nil}} and will log an error in the Modding Console with one of the following errors:</p>
      {| class="wikitable"
      ! Error !! Description 
      |-
      | Failed To Increase Slot || generic error catch, shouldn't really see this.
     |}
     <p>Example code to increase the amount of the second player slot:</p>
<syntaxhighlight lang="lua">
-- 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)
</syntaxhighlight><br/>
      <h2>api_slot_item_id()</h2>
      <p><b>If you want to get the type of bee in a slot and have the slot instance already just look at the slot's {{D|i=stats}} property! This method is intended for situations where you have only have slot ID, and not the slot instance from say {{F|i=api_get_slot()}}.</b><br/>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.<br/><br/>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.</p>
      {| class="wikitable"
       ! Parameter !! Datatype !! Description 
       |-
       | menu_id || {{D|i=integer}} || the menu inst that the slot belongs to 
       |-
       | slot_index || {{D|i=integer}} || the index of the slot you want to get, starting at 1
      |}
      <p>If this method worked it will return a {{D|i=string}} with the data id or OID, empty if no item is present in this slot.</p>
     <p>Example code to get the item id for the first slot in the players menu:</p>
<syntaxhighlight lang="lua">
-- 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
</syntaxhighlight><br/>
      <h2>api_slot_match()</h2>
      <p>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.</p>
      {| class="wikitable"
       ! Parameter !! Datatype !! Description 
       |-
       | menu_id || {{D|i=integer}} || the menu instance you want to find matches on
       |-
       | match || list({{D|i=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 || {{D|i=boolean}} || [Optional] if true, this method will return the first slot only rather than a list of matches
      |}
      <p>If you specify "first" to be true, this method will either return a {{D|i=slot_instance}} or {{D|i=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 {{D|i=slot_instance}}, just empty if no matches were found.</p>
      <p>Example code to get various slot matches from the player inventory:</p>
<syntaxhighlight lang="lua">
-- 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, {""})
</syntaxhighlight><br/>
      <h2>api_slot_match_range()</h2>
      <p>This is the same as {{F|i=api_slot_match()}} except you can specify the range of slot indexes to match from rather than all the slots.</p>
      {| class="wikitable"
       ! Parameter !! Datatype !! Description 
       |-
       | menu_id || {{D|i=integer}} || the menu instance you want to find matches on
       |-
       | match || list({{D|i=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({{D|i=integer}}) || a list of slot indexes to check. Indices start at 1 like LUA lists do
       |-
       | first_only || {{D|i=boolean}} || [Optional] if true, this method will return the first slot only rather than a list of matches
      |}
      <p>If you specify "first" to be true, this method will either return a {{D|i=slot_instance}} or {{D|i=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 {{D|i=slot_instance}}, just empty if no matches were found.</p>
      <p>Example code to get various slot matches from the player inventory:</p>
<syntaxhighlight lang="lua">
-- 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})
</syntaxhighlight><br/>
      <h2>api_slot_set()</h2>
      <p>This method lets you set the contents of a slot manually, overriding anything in that slot.</p>
      {| class="wikitable"
       ! Parameter !! Datatype !! Description 
       |-
       | slot_id || {{D|i=integer}} || the slot id of the slot instance you want to set
       |-
       | item_oid || {{D|i=string}} || the item oid you want to set in the slot (see [[OID Reference]])
       |-
       | amount || {{D|i=integer}} || the amount of the item you want to set. If setting a singular item this will be ignored
       |-
       | stats || {{D|i=stats}} || [Optional] a {{D|i=stats}} obj to use, can be one you got from {{F|i=api_create_bee_stats()}} or a custom one
      |}
      <p>If this method worked it will return {{I|i=Success}}, otherwise if it fails it will return {{D|i=nil}} and will log an error in the Modding Console with one of the following errors:</p>
      {| class="wikitable"
      ! Error !! Description 
      |-
      | Failed To Set Slot || Failed to set slot, potentially a bad item oid
     |}
     <p>Example code set all the slots in the player inventory to logs (you are welcome):</p>
<syntaxhighlight lang="lua">
-- 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
</syntaxhighlight><br/>
      <h2>api_slot_set_inactive()</h2>
      <p>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.<br/>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.</p>
      {| class="wikitable"
       ! Parameter !! Datatype !! Description 
       |-
       | slot_id || {{D|i=integer}} || the slot id of the slot instance you want to set
       |-
       | inactive || {{D|i=boolean}} || whether to set the slot as inactive or not
      |}
      <p>If this method worked it will return {{I|i=Success}}, otherwise if it fails it will return {{D|i=nil}} and will log an error in the Modding Console with one of the following errors:</p>
      {| class="wikitable"
      ! Error !! Description 
      |-
      | Slot Instance Doesn't Exist || Failed to set slot property as slot doesn't exist
     |}
     <p>Example code set all the slots in the player inventory to inactive (you are welcome):</p>
<syntaxhighlight lang="lua">
-- 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
</syntaxhighlight><br/>
      <h2>api_slot_set_modded()</h2>
      <p>This method lets you set a slot to be 'modded'. Modded slots CAN be highlighted/hovered but they can't be clicked on.<br/>This allows you to handle your own click logic for the slot.</p>
      {| class="wikitable"
       ! Parameter !! Datatype !! Description 
       |-
       | slot_id || {{D|i=integer}} || the slot id of the slot instance you want to set
       |-
       | modded || {{D|i=boolean}} || whether to set the slot as modded or not
      |}
      <p>If this method worked it will return {{I|i=Success}}, otherwise if it fails it will return {{D|i=nil}} and will log an error in the Modding Console with one of the following errors:</p>
      {| class="wikitable"
      ! Error !! Description 
      |-
      | Slot Instance Doesn't Exist || Failed to set slot property as slot doesn't exist
     |}
     <p>Example code set all the slots the first slot in the player inventory as modded:</p>
<syntaxhighlight lang="lua">
-- get player slots
slots = api_get_slots(api_get_player_instance())
api_slot_set_modded(slots[1]["id"], true)
</syntaxhighlight><br/>
      <h2>api_slot_redraw()</h2>
      <p>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.<br/><br/><b>If wanting to redraw all the slots for a menu you should use {{F|i=api_draw_slots}} for performance reasons!</b></p>
      {| class="wikitable"
       ! Parameter !! Datatype !! Description 
       |-
       | slot_id || {{D|i=integer}} || the slot id of the slot instance you want to redraw
      |}
     <p>Example code to draw a sprite and then redraw a slot in a custom menu_draw script:</p>
<syntaxhighlight lang="lua">
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
</syntaxhighlight><br/>
      <h2>api_slot_validate()</h2>
      <p>You may have noticed that if you just use {{F|i=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).<br/><br/>This does not actually move the item into the slot, just a read-only check.</p>
      {| class="wikitable"
       ! Parameter !! Datatype !! Description 
       |-
       | slot_id || {{D|i=integer}} || the slot id of the slot instance you want to validate agaisnt
       |-
       | item || {{D|i=string}} || the item oid you want to put in the slot, i.e. "axe4" (see [[OID Reference]])
       |-
       | stats || {{D|i=table}} || the stats for the item you want to put in the slot, can be an empty table if no stats needed
      |}
     <p>This method will return a {{D|i=boolean}}, true if the item/stats combination you passed can go in the slot.</p>
     <p>Example code to see if we can add a Bee into a Sawbench (spoilers, you can't)</p>
<syntaxhighlight lang="lua">
-- 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
</syntaxhighlight>
    </div>
  </div><br/>

  <div class="aw-api-section mw-customcollapsible-s1">
    <h1>[[File:Mainlander_Money_Item.png|32px]]Take Methods</h1>
    <p>Take methods allow you to take currency from the player.</p>
    {| class="wikitable"
     ! Method !! Description 
     |-
     | {{F|i=api_take_honeycore()}} || takes an amount of Honeycore from the player
     |-
     | {{F|i=api_take_money()}} || takes an amount of a money from the player
    |}
    <div class="mw-collapsible mw-collapsed" id="mw-customcollapsible-s1">
      <h2>api_take_honeycore()</h2>
      <p>Takes a certain amount of Honeycore from the player.</p>
     {| class="wikitable"
      ! Parameter !! Datatype !! Description 
      |-
      | amount || {{D|i=integer}} || the amount to take
     |}
<syntaxhighlight lang="lua">
-- take 10 honeycore
api_take_honeycore(10)
</syntaxhighlight><br/>
      <h2>api_take_money()</h2>
      <p>Takes a certain amount of Rubees from the player.</p>
     {| class="wikitable"
      ! Parameter !! Datatype !! Description 
      |-
      | amount || {{D|i=integer}} || the amount to take
     |}
<syntaxhighlight lang="lua">
-- take 69 money
api_take_money(69)
</syntaxhighlight>
    </div>
  </div><br/>

  <div class="aw-api-section mw-customcollapsible-s1">
    <h1>[[File:Paintbrush_Item.png|32px]]Use Methods</h1>
    <p>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.</p>
    {| class="wikitable"
     ! Method !! Description 
     |-
     | {{F|i=api_use_item()}} || uses up a certain amount of an item from the players inventory and open menus
     |-
     | {{F|i=api_use_total}} || returns the total amount of an item currently in the players inventory and open menus
    |}
    <div class="mw-collapsible mw-collapsed" id="mw-customcollapsible-s1">
      <h2>api_use_item()</h2>
      <p>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.<br/>You should use {{F|i=api_use_total()}} to check what the player has first!</p>
      {| class="wikitable"
       ! Parameter !! Datatype !! Description 
       |-
       | item_oid || {{D|i=string}} || the item to use up (see [[OID Reference]])
       |-
       | amount || {{D|i=integer}} || the amount to use up
      |}
      <p>Example code to use up 1 log every second:</p>
<syntaxhighlight lang="lua">
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
</syntaxhighlight><br/>
      <h2>api_use_total()</h2>
      <p>This method returns the total amount of an item currently in the players inventory and open menus.</p>
      {| class="wikitable"
       ! Parameter !! Datatype !! Description 
       |-
       | item_oid || {{D|i=string}} || the item to use up (see [[OID Reference]])
      |}
      <p>This method returns an {{D|i=integer}} for the amount of the given item available.</p>
      <p>Example code to check for an amount of planks and give the player more planks if under a certain amount:</p>
<syntaxhighlight lang="lua">
-- 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
</syntaxhighlight>
    </div>
  </div>

</div>