Add new api methods

Author: ThatGravyBoat

create_methods.lua

@@ -61,4 +61,11 @@ function api_create_timer(method, seconds, arg1, arg2, arg3)  end
 ---@param x number the x position to create the lightweight at
 ---@param y number the y position to create the lightweight at
 ---@return number returns instance id of lightweight
-function api_create_lightweight(type, sprite_ref, frame, x, y)  end
+function api_create_lightweight(type, sprite_ref, frame, x, y)  end
+
+---
+---@since 2.1.0
+---@param species string the species of butterfly to spawn
+---@param weather string he type of weather for this butterfly - once the game weather no-longer matches what you pass in, the butterfly will despawn. Values allowed are snow, rain or an empty string
+---@param inst_id number the instance to spawn the butterfly on, can be a flower, tree, generic obj, menu obj, or a wall
+function api_create_butterfly(species, weather, inst_id)  end

datatypes/butt_definition.lua

@@ -0,0 +1,17 @@
+---@class butt_definition
+---@field id string lowercase unique name for your butterfly
+---@field title string name of your butterfly for tooltips + books
+---@field latin string the latin name for your butterfly, shown in the book
+---@field hint string the hint to show in the book when this species hasn't been discovered yet
+---@field desc string the description to show in the book when this species has been discovered
+---@field biome string the biome this butterfly spawns in, valid options are Forest, Swamp, Snow, Hallow, and Devland
+---@field lifespan number a lifespan value to use for the butterfly, chrysalis lifespan is always half the butterfly species
+---@field behaviour string a behaviour trait this species will spawn with, valid options are Diurnal, Nocturnal, Crepuscular, Cathemeral
+---@field climate string a climate trait this species will spawn with, valid options are Temperate, Tropic, Polar, Any
+---@field rainlover boolean whether this species likes rain
+---@field snowlover boolean whether this species likes snow
+---@field flora string the OID of the specific flora item that this butterfly's caterpiller will eat as food
+---@field flowers string[] a list of two flower OIDs that will represent the flower "likes" a butterfly has
+---@field chance number the chance this butterfly will spawn naturally if the conditions are met
+---@field named boolean whether this butterfly is a "named" species - named species will not get "Butterfly" appended to their species nam
+

datatypes/dialogue.lua

@@ -0,0 +1,4 @@
+---@class dialogue
+---@field P string the prompt the player will see for this dialogue section
+---@field D string[] a list of dialogue strings that will represent "screens" of dialogue the player can click through
+---@field A string[] a list of dialogue actions to match each of the dialogue "screens" - you need to match the number of strings in D.

datatypes/dialoguetree.lua

@@ -0,0 +1,3 @@
+---@class dialoguetree
+---@field A dialogue the first dialogue option an NPC has
+---@field * dialogue as long as you have an "A" you can add as many new sections as you like

datatypes/menu_definition2.lua

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

datatypes/npc_definition2.lua

@@ -0,0 +1,11 @@
+---@class npc_definition2
+---@field id number id to use for the npc, must be unique across all mods
+---@field name string the name of this NPC, shown in tooltips and their dialogue
+---@field pronouns string the pronouns for this NPC, shown in their dialogue
+---@field tooltip string the tooltip message for this NPC, usually just a greeting message
+---@field specials string[] a list of at least 3 item oids that this NPC will have in it's special item pool
+---@field stock string[] a list of up to 10 item oids that this NPC will have as it's shop stock
+---@field greeting string the default greeting message shown in the dialogue menu when it opens
+---@field dialogue dialoguetree[] a special table that represents an NPCs dialogue tree
+---@field walking boolean @[Optional] whether this NPC will walk around or stay still
+---@field shop boolean @[Optional] whether this NPC will have a shop or just be dialogue only

datatypes/sbee_definition.lua

@@ -0,0 +1,15 @@
+---@class sbee_definition
+---@field id string lowercase unique name for your bee
+---@field title string name of your bee for tooltips + books
+---@field latin string the latin name for your bee, shown in the book
+---@field hint string the hint to show in the book when this species hasn't been discovered yet
+---@field desc string the description to show in the book when this species has been discovered
+---@field biome string the biome this bee spawns in, valid options are Forest, Swamp, Snow, Hallow, and Devland
+---@field behaviour string a behaviour trait this species will spawn with, valid options are Diurnal, Nocturnal, Crepuscular, Cathemeral
+---@field climate string a climate trait this species will spawn with, valid options are Temperate, Tropic, Polar, Any
+---@field rainlover boolean whether this species likes rain
+---@field snowlover boolean whether this species likes snow
+---@field produce string the OID of the item this bee will leave as a gift when in habitats
+---@field specials string[] a list of up to two item OIDs that the solitary bee will need along with flora to appear
+---@field chance number the chance this bee will spawn naturally if the conditions are met
+

define_methods.lua

@@ -84,6 +84,7 @@ function api_define_gui(menu_id, gui_key, gui_ox, gui_oy, gui_hover, sprite_imag
 function api_define_item(item_def, sprite_image)  end
 
 ---
+---@deprecated use api_define_menu_object2 instead
 ---@param menu_def menu_definition the menu definition table to use
 ---@param sprite_image string relative path of the sprite you want to use for the menu object, should be a 64x16 image with 4 frames (normal, normal highlighted, undiscovered, undiscovered highlight)
 ---@param menu_image string relative path of the sprite you want to use for the menu itself, can be any size but needs to have 4 frames (normal, highlighted, dragging, help overlay)
@@ -99,6 +100,7 @@ function api_define_menu_object(menu_def, sprite_image, menu_image, scripts, dra
 function api_define_notification(notification_type, notification_script)  end
 
 ---
+---@deprecated use api_define_npc2 instead
 ---@param npc_def npc_definition the definition obj for your NPC
 ---@param standing_sprite string relative path to the sprite you want to use for the NPC standing animation, should be a 36x18 image with 2 frames (standing, standing_bob)
 ---@param standing_h_sprite string relative path to the sprite you want to use for the NPC when standing and highlighted, should be a 36x18 image with 2 frames (standing, standing_bob)
@@ -214,4 +216,61 @@ function api_define_window(window, window_sprite) end
 ---@param color string a color name to use for the liquid, this can be a default one or your own that you defined with api_define_color()
 ---@param texture_sprite string the path to a single 37x34px image used as the liquid "texture". This will be drawn at 50% alpha on top of any tanks with your liquid in it, to help identify your liquid without color
 ---@param preview_sprite string the path to a single 12x12px image used as the liquid preview when hovering over machines with a tank containing your liquid - this should be a solid filled in image (i.e. your color + your texture combined)
-function api_define_liquid(name, color, texture_sprite, preview_sprite) end
+function api_define_liquid(name, color, texture_sprite, preview_sprite) end
+
+---
+---@since 2.1.0
+---@param sbee_def sbee_definition the solitary bee definition to be used to create the new species
+---@param bee_sprite_image string relative path of the sprite you want to use for the bee item, should be a 72x18 image with 4 frames (normal, normal highlighted, undiscovered, undiscovered highlight)
+---@param bee_shiny_image string relative path of the sprite you want to use for the shiny variant, should be a 380x18 image with 20 frames for a shine animation
+---@param bee_hd_image string relative path of the sprite you want to use for the "HD" bee image in the book, should be a 96x48 image with 2 frames (normal, undiscovered)
+---@param bee_color color a color to use for the bee, used in the book, predictor, and the discovery popup
+---@param bee_letter_image string relative path of the sprite you want to use for the bee's letter item, should be a 32x16 image with 2 frames (normal, highlighted)
+---@param bee_letter_text string text to show in the letter for this species
+---@return string|nil If this method worked it will return Success, otherwise if it fails it will return nil and will log an error in the Modding Console.
+function api_define_solitary(sbee_def, bee_sprite_image, bee_shiny_image, bee_hd_image, bee_color, bee_letter_image, bee_letter_text) end
+
+---
+---@since 2.1.0
+---@param butt_def butt_definition the solitary bee definition to be used to create the new species
+---@param butt_sprite_image string relative path of the sprite you want to use for the bee item, should be a 72x18 image with 4 frames (normal, normal highlighted, undiscovered, undiscovered highlight)
+---@param butt_golden_image string relative path of the sprite you want to use for the golden variant, should be a 72x18 image with 4 frames (normal, normal highlighted, undiscovered, undiscovered highlight)
+---@param butt_cat_image string relative path of the sprite you want to use for the caterpiller, should be a 18x18 image with 1 frame (normal)
+---@param butt_hd_image string relative path of the sprite you want to use for the "HD" butterfly image in the book, should be a 96x48 image with 2 frames (normal, undiscovered)
+---@param butt_color color a color to use for the butterfly, used in the book
+---@return string|nil If this method worked it will return Success, otherwise if it fails it will return nil and will log an error in the Modding Console.
+function api_define_butterfly(butt_def, butt_sprite_image, butt_golden_image, butt_cat_image, butt_hd_image, butt_color) end
+
+---
+---@since 2.1.0
+---@param item_def item_definition an item definition for your incense using standard definition keys (this is also where "effect" is used in the item_definition)
+---@param sprite_image string relative path to the sprite you want to use for this item, should be a 64x16 image with 4 frames (normal, normal highlighted, undiscovered, undiscovered highlight)
+---@param alchemy_check string a method name defined in your mod code that will be used to check if the combination the player has in their alchemy bench will create your incense. This method will be passed the current incense oid that will be combined currently, along an alchemy_count table
+---@return string|nil If this method worked it will return Success, otherwise if it fails it will return nil and will log an error in the Modding Console.
+function api_define_incense(item_def, sprite_image, alchemy_check) end
+
+---
+---@since 2.1.0
+---@param npc_def npc_definition2 the definition obj for your NPC
+---@param standing_sprite string relative path to the sprite you want to use for the NPC standing animation, should be a 36x18 image with 2 frames (standing, standing_bob)
+---@param standing_h_sprite string relative path to the sprite you want to use for the NPC when standing and highlighted, should be a 36x18 image with 2 frames (standing, standing_bob)
+---@param walking_sprite string relative path to the sprite you want to use for the NPC walk animation, should be a 72x18 image with 4 frames (stand, step_1, stand, step_2)
+---@param walking_h_sprite string relative path to the sprite you want to use for the NPC when walking and highlighted, should be a 72x18 image with 4 frames (stand, step_1, stand, step_2)
+---@param head_sprite string relative path to the sprite you want to use for this NPCs map icon, should be a 18x14 image with 1 frame
+---@param bust_script string relative path to the sprite you want to use for this item, should be a 64x36 image with 2 frames (normal, bought "happy" face)
+---@param item_sprite string relative path to the sprite you want to use for this NPCs item (that you get when you hammer an NPC), should be a 32x16 image with 2 frames (normal, normal highlighted)
+---@param dialogue_bg_sprite string relative path to the sprite you want to use for this NPCs dialogue menu, should be a 48x38 image with 1 frame
+---@param shop_bg_image string relative path of the sprite you want to use for the NPCs shop menu bust background, should be a 39x39 image with 1 frame
+---@param dialogue_check string the name of a script in your mod code that will be called to decide which dialogue options to show
+---@return string|nil If this method worked it will return Success, otherwise if it fails it will return nil and will log an error in the Modding Console.
+function api_define_npc2(npc_def, standing_sprite, standing_h_sprite, walking_sprite, walking_h_sprite, head_sprite, bust_script, item_sprite, dialogue_bg_sprite, shop_bg_image, dialogue_check) end
+
+---
+---@since 2.1.0
+---@param menu_def menu_definition2 the menu definition table to use
+---@param sprite_image string relative path of the sprite you want to use for the menu object, should be a 64x16 image with 4 frames (normal, normal highlighted, undiscovered, undiscovered highlight)
+---@param menu_image string relative path of the sprite you want to use for the menu itself, can be any size but needs to have 2 frames (normal, help overlay)
+---@param scripts scripts a scripts definition for all the scripts you want your menu object to run
+---@param draw_script string? @[Optional]  if specified this allows you to override the default object draw (overworld object) with your own draw script - this must be a method in your mod, and won't be called if you set the obj_definition "invisible" property to true
+---@return string|nil If this method worked it will return Success, otherwise if it fails it will return nil and will log an error in the Modding Console.
+function api_define_menu_object2(menu_def, sprite_image, menu_image, scripts, draw_script)  end

describe_methods.lua

@@ -32,4 +32,10 @@ function api_describe_oids(mods) end
 ---@since 1.3.1
 ---@param mods boolean if true will return results for mods instead of the base game
 ---@return table
-function api_describe_recipes(mods) end
+function api_describe_recipes(mods) end
+
+---
+---@since 2.1.0
+---@param mods boolean if true will return results for mods instead of the base game
+---@return table
+function api_describe_butterflies(mods) end

get_methods.lua

@@ -178,4 +178,16 @@ function api_get_weather()  end
 ---
 ---@since 1.3.1
 ---@return string returns a 2 letter language code, current options: [en, fr, it, de, es, br, jp]
-function api_get_language() end
+function api_get_language() end
+
+---
+---@since 2.1.0
+---@param inst_id number instance id
+---@return string returns a ZOID
+function api_get_zoid_from_inst(inst_id) end
+
+---
+---@since 2.1.0
+---@param zoid string ZOID
+---@return number returns the inst_id of ZOID
+function api_get_inst_from_zoid(zoid) end