Instance Properties
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 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 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 |
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) |
Lightweights (ob_lightweight_x)
Lightweights are a special instance made using api_create_lightweight() that allow you to efficiently draw lots of sprites without losing performance. From GameMaker's perspective these are very simple instances and as such just have the standard built-ins you would expect.
| Property Key | Datatype | Description |
|---|---|---|
| sprite_index | integer | the sprite index set for this lightweight that will be drawn |
| image_index | integer | the "frame" of the sprite strip to draw |
| x | integer | the x position of the lightweight |
| y | integer | the y position of the lightweight |
| image_speed | integer | defaults to 0 (no speed), but if set this will increment the image_index every step by the amount given, so you can cycle between frames automatically |