Skip to content

Home

Jump to bottom
Willow edited this page Jul 5, 2024 · 13 revisions

Welcome to the WiddlePets API guide! This mod uses an API system to allow anyone to create their own pets and add them to the game using a separate, add-on mod. This guide will walk through the process of setting up your own custom pet using the API. Ensure that you have Blender (3.6 recommended) and fast64 installed.

(This guide is still being worked on!)

The WPets Template

This template contains four base rigs that can be edited and exported as valid pets. It can be downloaded here from the repo.

There is base rig for: flying (wing), two-legged (2leg), four-legged (4leg), and single-bone (head) pets. Choose the base rig that suits your pet the most (not all bones on the base's armature need to be used.) Each base is sorted into its own collection in the Outliner, so you can hide the ones you aren't using. Once you've chosen a base rig to use, the process is similar to creating a custom character over Mario.

Rigging your Pet Model (section WIP)

Well, the first step is to actually get the model you're going to use! Once that's in your .blend file, we can now skin the pet model to the rig! (If you have experience with rigging models in Blender, feel free to skip over this section.)

  • Line up the mesh with your chosen base rig. Move it to the same position and facing the same direction.
  • Select the base rig's armature and enter Pose Mode. Adjust the bones to align with your own model's joints, wherever needed. Once finished, select 'Apply As Rest Pose' on the sidebar, under 'SM64 Tools'.
  • Once aligned, enter Object Mode and select your mesh, then the base mesh, and go to Object -> Join (Ctrl J).
  • Enter Edit Mode, and now you can select and delete the base rig's mesh.
  • Navigate to the Vertex Data tab. For each bone that you need to skin to your mesh, select its Vertex Group, then select the respective part of your mesh, then click 'Assign'.

The template file contains all the default animations used by each base rig type, so you can easily preview how your pet will look in-game. Simply select the armature in Object Mode, and choose an animation to preview in the Action Editor (be sure to switch the animation back to REST POSE when exporting.)

Exporting your Pet

If all looks good, it's time to export! But before we do, it'd be a good idea to create the mod folder for your custom pet, if you haven't already. I recommend placing a copy of the [PET] Template Mod in your mods folder to start.

Now in Blender, use the 'SM64 Geolayout Exporter' tab on the sidebar to export. Set the Directory to the actors folder in your mod, set the Folder Name to anything you'd like, and the Geolayout Name to [your_pet_name]_geo (be sure that the chosen geo name does NOT conflict with any existing ones used by the game. If you're uncertain, add 'pet' somewhere in the name.)

The Template Mod

And now to put it all in game! Open the main.lua file in your mod using a code editor (VSCode recommended). This script contains all the code needed to add a pet into the game. Going section-by-section:

local E_MODEL_WPET = smlua_model_util_get_id('wpet_geo')

This line loads our pet model. Change the arg to match your Geolayout name, and rename the E_MODEL variable to something more fitting (E_MODEL_[YOUR_PET_NAME]).

local ID_WPET = _G.wpets.add_pet({
    name = "A Pet", credit = "You!",
    description = "A custom pet.",
    modelID = E_MODEL_WPET,
    scale = 1.0, yOffset = 0, flying = false
})

This section adds the pet to the list in the WiddlePets menu, and sets up various properties for the pet.

  • name, credit, and description are self-explanatory.
  • modelID takes in the variable we created previously.
  • scale can be changed to easily tweak the size of the model in-game.
  • yOffset can be changed to render the model a bit higher or lower, good if they're clipping in the ground or hovering by default.
  • flying can be set to true to have your pet fly, instead of walk.

Once again, rename the ID variable to something more fitting.

_G.wpets.set_pet_anims_2leg(ID_WPET)

This section sets up the default two-legged animations for your pet. Change the 2leg part of the function name to whichever base you used (either wing, 2leg, 4leg, or `head'), and change the specified ID to match your own from the previous section.

_G.wpets.set_pet_sounds(ID_WPET, {
    spawn = 'pet_sound.ogg',
    happy = 'pet_sound.ogg',
    vanish = nil,
    step = SOUND_OBJ_BOBOMB_WALK
})

This section sets up sound effects for your pet. Each field can either be set to: an audio filename in your mod's sound folder (use .ogg), or a vanilla sound ID. Set a field to nil to play no sound. Change the specified ID to again match your own.

Additional Features

Blinking Animation

WiddlePets has support for blinking animations on pet models. If you'd like to set this up on your custom pet, select your pet's armature and navigate to the 'Anim State Switch' bone in the Outliner. This, again, works similar to setting up eye states on a custom Mario model. Change the 'Material' and 'Specified Material to Override' in the bone settings to your own materials. Ensure that the 'Parameter' of the Switch function is set to 2 (unlike the image, will fix soon)

If your pet isn't going to use this feature, feel free to delete the 'Anim State Switch' bone altogether.

Recolor Parts

You can also set any material on your pet to match the color of a 'player part'. The setup for this is the exact same process as setting up recolor parts on a custom character model, so I'd recommend checking out the guide on the Character Template repo (done after exporting the Geolayout).

Custom Pet Animations (WIP)

You can create custom animations in Blender for your chosen pet armature, and set them up for use in-game. I won't go over the details of animating in Blender, but to start, you can select one of the existing animations in the template using the Action Editor, make a copy of it, and begin editing. Some important notes:

  • It's recommended to have only the first layer of bones visible while animating. The current visible layers can be tweaked in the Armature tab on the right.
  • SM64 animations will only export rotation values, and root translation values. Due to this, all bones should only have their Rotation keyframed, other than the Root bone, which should only have its Translation keyframed.
  • All the default pet animations are the same lengths: idle is 48 frames, follow is 24 frames, petted is 70 frames, and dance is 40 frames. These are not hard restrictions, but can be a good guide when timing animations.

Once an animation is done, export it anywhere you'd like using the SM64 Animation Exporter tab in fast64. The exported file contains the animation data; open it in a code editor.

Now open your [PET] mod file (main.lua) add the code below to any new line, where: startFrame is the first frame of your animation (typically 0), loopStart is the frame that a loop of the animation begins at (typically 0), and loopEnd is the last frame of your animation.

smlua_anim_util_register_animation( 'YOUR_ANIM_NAME', 0, 4, startFrame, loopStart, loopEnd,
    {},
    {}
)

Now for the last two arguments; your exported animation file contains two lists of hexadecimal numbers. Copy everything inside of the curly braces of the first list (labelled [anim_name]_values), and paste it inside the first set of empty curly braces in the above ^ code. Now do the same for the next exported list (labelled [anim_name]_indices), copy it and paste into the second set of empty curly braces. The code should look something like this:

smlua_anim_util_register_animation( 'YOUR_ANIM_NAME', 0, 4, 0, 0, 48,
    {
    0x0000, 0x0000, 0x0000, 0x0000, 0x0000, 0x0000, 0x0000, 0x0000, 0x0000, 
    0x0000, 0x0000, 0x0000, 0x0000, 0x0000, 0x0000, 0x0000, 0x0000, 0x0000,
    },
    {
    0x0000, 0x0000, 0x0000, 0x0000, 0x0000, 0x0000, 0x0000, 0x0000, 0x0000, 
    0x0000, 0x0000, 0x0000, 0x0000, 0x0000, 0x0000, 0x0000, 0x0000, 0x0000,
    }
)

And now, you can plug 'YOUR_ANIM_NAME' into a _G.wpets.set_pet_anims() function call to use this animation on your pet.

Several other features are available for mods using the WiddlePets API; full info on everything available can be found in the Full API Docs page. If you'd like to see more example custom pets outside of the template mod, read through the z-builtin_pets.lua script. It uses custom animations, mixed sound types, alt models, etc.

Clone this wiki locally