Instance Properties

From APICO Wiki
Jump to navigation Jump to search

Every single instance in the game falls under a specific category of instance class. The main ones you will interact with are the Player, Mouse, Items, Objects, Trees, Flowers, Menu Objects, Menus, and Slots!

Each instance has a set of built-in properties that you can get/set with api_get_property() and api_set_property(). This page aims to list all the properties you may find useful alongside the standard ones listed on the Generic Instance datatype.

Modding

Instance Properties

Player (ob_player)

The Player is a special instance of which there is only ever one. This is the Player instance that the player moves around, and it stores a lot of key information.

Property Key Datatype Description
x integer current player x position
y integer current player y position
spawn_x integer current player spawn x position (player will spawn here after drowning / going to devland / finishing the game)
spawn_y integer current player y position (player will spawn here after drowning / going to devland / finishing the game)
open boolean whether the player's inventory is open or closed
hotbar integer current "equipped" slot index in the hotbar, starting from 0
dir string current direction the player is facing, either "left" or "right"
walking boolean whether the player is currently walking / moving
wading boolean whether the player is currently wading in shallow water
sitting boolean whether the player is sitting on a bench
sleeping boolean whether the player is sleeping (on a bench or a bed)
soaking boolean whether the player is standing in shallow water
sailing boolean whether the player is sailing on a boat (moving or not)
sliding boolean whether the player is sliding on ice
drowning boolean whether the player is "drowning" (stuck in deep water)
name string the player's chosen name
money integer the amount of Rubees the player has
honeycore integer the amount of Honeycore the player has
current_tile string the current tile OID under the player, i.e. "grass1" or "water2" etc
buff string the current buff applied to the player, if any. This value will be the spice OID, i.e. "spice1". Setting this value directly will not trigger the buff notification.
buff_time integer the amount of time left before the buff applied expires, if any
boat integer the instance ID of the boat object if the player is sailing in a boat
palette table the color palette for the player, which is a set of indices keys for hair, skin, overalls, undershirt, and hair. Changing these indices will not change the player colors.
stats table the stats stored for the player (the ones shown in nan's bookcase!)
unlocked_books table a boolean for each book to say whether its unlocked or not (making it show in the bottom bar)
door_opened boolean whether the player has opened the Hivemother Door, basically if the player has got every bee and "finished" the game (spoilers!)


Mouse (ob_mouse)

The Mouse is a special instance that follows the mouse position and handles interaction. For all intents and purposes the Mouse is just a fancy Slot, and has a lot of the same properties as slots.

Property Key Datatype Description
x integer current mouse x position
y integer current mouse y position
tx integer current mouse tile x position
ty integer current mouse tile y position
item integer the OID of the "item" if an item is picked up. If one is set this OID is used to draw the item preview you see next to the mouse
count integer the number of the item picked up, if any
current_health decimal the current health of the item picked up, if any
total_health decimal the total health of the item picked up, if any
stats table the stats table of the item picked up, if any (i.e. bee properties, frame stats etc)


Items (ob_item)

Items are instances of items you find on the floor, or that are dropped when you pick stuff up. Items are destroyed once they are picked up by the Player. Items have pretty much the same properties as Slot instances - these properties get moved to the slot when picked up.

Property Key Datatype Description
x integer current item x position
y integer current item y position
item integer the OID of the item. If one is set this OID is used to draw the item you see
count integer the number of the item, if any
current_health decimal the current health of the item, if any
total_health decimal the total health of the item, if any
stats table the stats table of the item, if any (i.e. bee properties, frame stats etc)



Objects (ob_generic)

Objects are any generic object that doesn't have a menu, i.e. shrubs, rocks, boats, benches etc. Trees and Flowers are not part of this instance class because they have other special properties, listed below.

Property Key Datatype Description
x integer current object x position
y integer current object y position
sprite_index integer sprite index to use when drawing this object
oid string the OID of the object
current_health decimal the current health of the object, if any
total_health decimal the total health of the object, if any
biome string current biome the object is in, values are "forest", "swamp", "snow", and "hallow"
paint integer index of any paint used on this object, if any
script_draw string mod draw script if this is a custom modded object (if this is a standard object, changing this value does nothing)


Trees (ob_tree)

Trees are like objects, but separated out for efficiency in the game. They pretty much have the same properties as objects.

Property Key Datatype Description
x integer current tree x position
y integer current tree y position
sprite_index integer sprite index to use when drawing this tree
oid string the OID of the tree (always "tree" lol)
current_health decimal the current health of the tree
total_health decimal the total health of the tree
biome string current biome the tree is in, values are "forest", "swamp", "snow", and "hallow". Trees in the "hallow" biome cannot be cut down without Grandpa's Axe
paint integer index of any paint used on this tree, if any. This can't be set on trees without modding
variant string the variant index for the tree. All trees have 8 variants, picked randomly when the tree is created



Flowers (ob_flower)

Flowers are also like objects, but again separated out for efficiency in the game. They pretty much have the same properties as objects.

Property Key Datatype Description
x integer current flower x position
y integer current flower y position
sprite_index integer sprite index to use when drawing this flower
oid string the OID of the flower
biome string current biome the flower is in, values are "forest", "swamp", "snow", and "hallow"
paint integer index of any paint used on this flower, if any. This can't be set on flower without modding
variant string the variant index for the flower. All flowers have 6 variants, picked randomly when the flower is created
flowering boolean whether this flower is "flowering" which causes the bobbing movement when bees visit that specific flower
potted boolean whether this is a potted flower. When you put a flower in a pot it actually creates a flower behind the pot that is destroyed when the flower is either removed from the pot or the pot is picked up
pot integer the pot instance the flower is current "in", if any


Menu Objects (ob_menu_object)

Menu Objects are objects that have a menu that opens when clicked, i.e. sawbench, workbench, beehives etc. The Menu Object has an attached Menu instance - it's important to remember these are two seperate things!

Menu Objects have a bunch of extra properties on top of the usual Object ones.

Property Key Datatype Description
x integer current menu object x position
y integer current menu object y position
sprite_index integer sprite index to use when drawing this menu object
oid string the OID of the menu object
menu integer the Menu instance for this menu object
open boolean whether the menu for this menu object is open
npc boolean whether this is an NPC menu object
beehive boolean whether the is a beehive menu object (natural or man-made)
working boolean whether this menu object is working (i.e. sawmill with clockwork wind running or beehive with active queen). Working menu objects do not get deactivated until they finish working.
immortal boolean whether this menu object is immortal, meaning it never deactivates when offscreen regardless of working status
invisible boolean whether this menu object is invisible, i.e. not drawn in the draw cycle. The menu of this menu object will still be drawn if open
center boolean whether this menu object's menu should open dead center of the screen when clicked
in_view boolean whether this menu object in in the current player view
hp decimal the current health of the menu object, all menu objects have 2 HP that regenerates to prevent hammer accidents
biome string current biome the menu object is in, values are "forest", "swamp", "snow", and "hallow"
paint integer index of any paint used on this menu object, if any
draw_script string mod draw script if this is a custom modded object (if this is a standard object, changing this value does nothing)



Menus (ob_menu)

Menus are the actual open menu you see when clicking on a Menu Object. This is where a lot of the OID specific logic is stored, and as such it'd be a mammoth task to try listing every single set of properties for every different menu OID, however beehives/apiaries have their special properties below!

Instead these are all the generic properties that all Menus share.

Property Key Datatype Description
x integer current menu x position
y integer current menu y position
rx integer relative menu x position to the camera (i.e. x - camera.x)
ry integer relative menu y position to the camera (i.e. y - camera.y)
obj_x integer current menu's menu object x position (when it was placed)
obj_y integer current menu's menu object y position (when it was placed)
drag boolean whether the menu is being dragged or not
obj integer the Object instance ID of this menu's menu object
oid string the OID for this menu
target boolean whether this menu is the current "target" or not, changing this can mess with the auto-targeting stuff
open boolean whether the menu is open or not
_fields list a list of properties that are stored when the game is saved
working boolean whether the menu is currently "working" or not. Working menu objects do not get deactivated until they finish working.
sprite_ref integer unlike other classes, menus have a cached sprite reference for the menu sprite which is used instead of the GMS sprite_index built-in
beehive boolean whether this is a beehive menu (beehive, man-made apiaries etc)
modded boolean whether this is a modded menu
script_mdraw string the draw cycle script to call for modded menus
script_tick string the tick script to call for modded menus
script_define string the define script to call for modded menus
script_change string the change script to call for modded menus
error string if the menu has an error it will be rendered underneath the menu, you can use this to set your own errors on modded menus


Beehive/Apiary Menus (ob_menu)

Like all other menus, beehives and apiaries share all the properties mentioned above. However for beehives and apiaries specifically there are some extra properties that may be useful for you to check.

Most of these properties are set every tick so you can't really update them but you can read them to do other things with!

Property Key Datatype Description
l_start integer current lifespan amount / progress
l_end integer total lifespan amount (set based on queen's lifespan trait). When l_start reaches l_end the queen dies and offspring are formed
p_start integer current productivity meter amount
p_end integer total productivity amount (set based on queen's productivity trait) when p_start reaches p_end we make produce (honeycomb or frames) and reset p_start
flowers list(integer) list of all flowers nearby (flower inst ids)
flowers_unique list(string) unique list of all flower oids nearby (i.e. "flower4", "flower6")
status_sleeping boolean whether the bees are asleep
status_wet boolean whether there is weather that the bees don't like
status_happy boolean whether the bees are happy with their climate
status_calm boolean whether the bees are grumpy but calmed down

Slots (ob_slot)

Slots are the actual slots within a Menu instance. Each slot stores data of the item it contains, and has similar properties to the Mouse and Item classes, except with a few extra special properties

Property Key Datatype Description
ox integer relative x position from the parent menu origin position (top left)
oy integer relative y position from the parent menu origin position (top left)
rx integer relative x position to the camera (i.e. x - camera.x)
ry integer relative y position to the camera (i.e. y - camera.y)
menu integer the parent menu instance that this slot belongs to
item integer the OID of the item in the slot, if any
count integer the number of the item in the slot, if any
current_health decimal the current health of the item in the slot, if any
total_health decimal the total health of the item in the slot, if any
stats table the stats table of the item in the slot, if any (i.e. bee properties, frame stats etc)
index integer the index of the slot based on the menu's Dictionary definition layout, starting at 0
type string the "type" of slot based on the menu's Dictionary definition layout, stuff like "Input", "Output" etc
hex boolean whether this is a "hex" shaped slot, like the one found in beehives/apiaries. Used to show different highlight sprites
changed boolean whether the slot has been changed (shows a flash for a second then turns this boolean back to false)
confetti boolean whether to show confetti in this slot (used in new bees being discovered, shows confetti particles then turns this boolean back to false)
shop boolean whether this is a "shop" slot or not, allowing you to "buy" the item in this slot
sprite_ref integer the sprite reference of the item in the slot - this is cached for performance when the slot is changed, but could be changed if needed to show a "different" sprite in the slot. This is reset when the slot is clicked/changed
inactive boolean "inactive" slots are not visible and cannot be highlighted/selected
modded boolean "modded" slots are visible and can be highlighted but do nothing when clicked (allowing for custom mod click actions)

Buttons (ob_button)

Buttons are pretty basic but have a few properties on them that could be useful to you when handling button presses or changing actions of certain buttons.

Property Key Datatype Description
text string text that this button will show when rendered by the default API button draw method. could also use this for your own checks
index integer not used by default, but you could use this to apply different actions (i.e. if button.index == 1 etc)
menu integer menu instance this button belongs to
highlighted boolean whether the button is highlighted or not
allowed boolean doesn't have an inherent effect when set but you could use this to handle verification (like anvils/workbenches do)