This page provides info on all of the functions, etc. exposed by the WiddlePets API. This page assumes a baseline understanding of Lua.

---

_G.wpets

The mod's global table of functions and values to be accessed by other mods. All API function calls need to be preceded by this.

Functions

get_version()

Returns the the primary version number (first two digits) of the mod as a decimal number (currently 1.2).

Example:

print("mod version is: " .. _G.wpets.get_version())

add_pet(petInfo)

Adds a pet to the mod's menu. Returns its integer ID.

• petInfo : table
  • a table of properties. All fields are optional unless stated otherwise.

Field	Type	Description	Example
name	string	The pet's name to display in the menu. Required field.	name = "Bob-Omb Buddy"
credit	string	The model creator + contributors.	credit = "wibblus"
description	string	The short description shown in the menu.	description = "A cool lil pet."
modelID	ModelExtendedId	The pet's model ID, from smlua_model_util_get_id(). Required field.	modelID = E_MODEL_WPET
flying	boolean	Whether the pet should fly or walk to move around.	flying = true
scale	number	The visual scale of the pet model from its base scale.	scale = 1.0
yOffset	integer	A positive or negative unit amount to vertically offset the pet model by.	yOffset = 0
animPointer	Pointer_ObjectAnimPointer	Legacy field. Sets the built-in object animation to use if no animations are set for this pet.	animPointer = gObjectAnimations.koopa_seg6_anims_06011364

Example:

local E_MODEL_HEADPHONE_GOOMBA = smlua_model_util_get_id('hp_goomba_geo')

local ID_HPG = _G.wpets.add_pet({
    name = "Headphone Goomba", credit = "wibblus, Nintendo",
    description = "His tunes are the best in the Mushroom Kingdom.",
    modelID = E_MODEL_HEADPHONE_GOOMBA,
    scale = 0.74, yOffset = 0
})

edit_pet(i, petInfo)

Edit the properties of an existing pet.

• i : integer
  • the pet ID to affect
• petInfo : table
  • a table of properties. Same as add_pet(), but all fields are optional.

Example:

_G.wpets.edit_pet(ID_HPG, {scale = 2.0})

add_pet_alt(i, modelID)

Adds an alternate model choice to an existing pet. Returns the index of the added alt model. Alt models can be swapped between by re-selecting a pet in the menu.

• i : integer
  • the pet ID to affect
• modelID : ModelExtendedId|integer
  • the pet alt model ID, from smlua_model_util_get_id()

Example:

_G.wpets.add_pet_alt(ID_HPG, E_MODEL_HEADPHONELESS_GOOMBA)

set_pet_anims(i, anims)

Sets up animations for the specified pet. You can either specify one of the default pet animations, or a custom one added using smlua_anim_util_register_animation().

• i : integer
  • the pet ID to affect
• `anims' : table
  • a table of animation names.

Field	Default Options
idle	2leg_idle, 4leg_idle, wing_idle, head_idle
follow	2leg_follow, 4leg_follow, wing_follow, head_follow
petted	2leg_petted, 4leg_petted, wing_petted, head_petted
dance	2leg_dance, 4leg_dance, wing_dance, head_dance

Example:

_G.wpets.set_pet_anims(ID_HPG, {
    idle = 'hp_goob_idle',
    follow = 'hp_goob_follow',
    petted = 'hp_goob_petted',
    dance = 'hp_goob_dance'
})

set_pet_anims_2leg(i)

Shorthand for setting all animation fields to their 2leg defaults.

set_pet_anims_4leg(i)

Shorthand for setting all animation fields to their 4leg defaults.

set_pet_anims_wing(i)

Shorthand for setting all animation fields to their wing defaults.

set_pet_anims_head(i)

Shorthand for setting all animation fields to their head defaults.

set_pet_sounds(i, sounds)

Sets up sound effects for a specified pet. Entries can be either: a filename string, an integer sound ID, or a table of multiple entries.

• i : integer
  • the pet ID to affect
• sounds : table
  • a table of sound entries.

Example:

_G.wpets.set_pet_sounds(ID_HPG, {
    spawn = {'goob_spawn.ogg', 'goob_happy.ogg'},
    happy = 'goob_happy.ogg',
    step = SOUND_OBJ_GOOMBA_WALK
})

get_pet_field(i, field)

Returns the value of any specified property from an existing pet.

• i : integer
  • the pet ID to reference
• field : string
  • the field name (refer to add_pet())

Example:

local x = _G.wpets.get_pet_field(ID_HPG, 'modelID')

get_index_from_name(name)

Returns the ID of the pet with the specified name.

• name : string
  • the name to search for, not case sensitive.

Example:

local ID = _G.wpets.get_index_from_name("headphone goomba")

spawn_pet(playerIndex, petIndex, altIndex)

(Re)spawns the specified player's pet.

• playerIndex : integer
  • the local index of the player who's pet should be spawned (m.playerIndex).
• petIndex : integer
  • the ID of the pet to spawn. Leave as nil to respawn the player's already active pet (if any)
• altIndex : integer
  • the alt model index to spawn the pet with. Uses the default model if index is out of range or left as nil.

Example:

_G.wpets.spawn_pet(m.playerIndex, ID_HPG, nil)

despawn_pet(playerIndex)

Despawns the specified player's pet.

• playerIndex : integer
  • the local index of the player who's pet should be despawned (m.playerIndex).

Example:

_G.wpets.despawn_pet(m.playerIndex)

get_active_pet_id(playerIndex)

Returns two integer values: the specified player's pet ID, and alt model index. Returns nil if the player does not have an active pet.

• playerIndex : integer
  • the local index of the player to query.

Example:

local petId, altId = _G.wpets.get_active_pet_id(m.playerIndex)

if petId == ID_HPG then
    -- this user loves gooba
end

get_obj_pet_id(obj)

Returns two integer values: the specified WPet object's pet ID, and alt model index. If the given object is not a pet object, returns nil.

• obj : Object
  • the object to query. usually obtained from m.heldObj, or wpets.get_pet_obj().

Example:

local petId, altId = _G.wpets.get_obj_pet_id(m.heldObj)

if petId == ID_HPG then
    -- holding gooba
end

get_pet_obj()

Returns a reference to the local player's pet object. Also see the [bhvWPet] section for info on the custom fields, etc. used by the pet objects.

Example:

local obj = _G.wpets.get_pet_obj()
obj.oVelY = 10.0 --wheee

hook_allow_menu(func)

Hooks the specified function to be called when the WiddlePets menu is about to open. Return false to stop the menu from opening.

Example:

local function on_wpets_menu_open()
    if m.numStars < 10 then
        return false
    end
end
_G.wpets.hook_allow_menu(on_wpets_menu_open)

---

process_pet_samples()

Deprecated function for v1.2 onward. Calls an empty function to not break older [PET] mods.

WPet Behavior

bhvWPet

WiddlePets uses a custom behavior for all pet objects. The WPet behavior ID can be accessed through _G.bhvWPet, or by using get_id_from_behavior_name('bhvWPet').

---

The oAction field can have one of these possible values for WPet objects:

ID	Action	Description
0	IDLE	The pet is standing/hovering near you. Uses the idle animation.
1	FOLLOW	The pet is moving towards the owner player. Uses the follow animation.
2	PETTED	The pet has just been petted by a player. Uses the petted animation.
3	DANCE	The pet is dancing while the owner player performs a special action (i.e. getting a star). Uses the dance animation
4	BOUNCE	The pet has no AI and bounces off of walls. Returns to IDLE after landing. Used when a pet is thrown or kicked.
5	TELEPORT	The pet is invisible/intangible and waiting to teleport. Will teleport and return to IDLE once there is ground to spawn on near the owner player.
6	DESPAWN	The pet object is about to be unloaded.