DEV: Creating Models
This guide will explain the fundamentals of creating a Saturn-compatible model, as well as adding color code and/or CometSPARK support.
NOTE: This guide assumes you have prior knowledge of Blender and Fast64 - if you're new to that sort of thing, I highly recommend watching a YouTube tutorial and familiarizing yourself with the process.
- Basic Setup
-
Color Code Support
- Extra CometSPARK Lights
- Default GameShark Code
- CC Editor Labels
-
Adding Expressions
- Custom Blink Cycles (new)
- Customizable Textures
- Protecting Models
To export models for usage in Saturn, you will need to configure Fast64 to export to C. You can do so by navigating to SM64 -> SM64 File Settings -> Export type and set to C.
You do not need to specify a ROM, Decomp folder, or any other file path.
In SM64 Geolayout Exporter, enable Custom Export Path and set the Directory to your model's folder (e.g. <path_to_build_folder>/dynos/packs/CustomMario). Set Folder Name to mario and Geolayout Name to mario_geo.
Once finished, select your armature and press Export Armature Geolayout. Relaunch Saturn and the model should appear in the Model Packs list.
As of 2022-08-14, Saturn now uses a model.json file to store basic model information. This includes the model's name, author, description, version, and info for model-specific color codes and/or CometSPARK lights.
This isn't necessary to use models, but it is required for the below sections.
Each model.json file must be placed in the model's root folder (dynos/packs/<ModelFolder>/model.json).
Saturn models can also support color codes. Saturn identifies a color-codable part based on it's shade color value. Each part follows Mario's vanilla colors, except the gloves, which are solid green. This was done to avoid texture lighting issues.
To add color-codable limbs, simply edit a Fast3D material's Light color to use one of the following hex codes:
Hat - #FF0000, shade #7F0000
Overalls - #0000FF, shade #00007F
Gloves - #00FF00 (green), shade #007F00
Shoes - #721C0E, shade #390E07
Skin - #FEC179, shade #7F603C
Hair - #730600, shade #390300
NOTE: On newer versions of Fast64, you may need to disable "Automatic Ambient Color" and specify a light's shade hex (see above). This is likely a bug with Fast64 that causes it to sometimes export inaccurate shading colors.
Color code support can be enabled/disabled by changing cc_support in the model.json file.
Saturn also has support for CometSPARK GameShark codes, allowing 6 more color-codable Lights to be used in a model.
Shirt - #FFFF00, shade #7F7F00
Shoulders - #00FFFF, shade #007F7F
Arms - #00FF7F, shade #007F40
Pelvis - #FF00FF, shade #7F007F
Thigh - #FF007F, shade #7F0040
Calf - #7F00FF, shade #40007F
CometSPARK support can be enabled by setting spark_support to true in the model.json file.
If your model has color code support, is recommended you add a default GameShark (.gs) code. Unlike standard GS files, default GameShark codes will appear at the top of the model's color code list, and are not editable or removeable.
Simply place a GS file (.gs) in the model folder and rename it to default.gs.
Models can be configured to automatically adjust the Color Code Editor. This allows model authors to change label names or hide colors entirely. Ideally, you'd only want to show values your model uses.
In the above screenshot, the model.json file contains the snippet:
"colors": {
"hat": "Robe",
"overalls": "Mask",
"gloves": "Belt Buckle",
"skin": "Soles",
"hair": "Belt",
"shirt": "Spear Tip",
"shoulders": "Spear Handle",
"arms": "Spear Hilt",
"pelvis": "",
"thighs": "",
"calves": ""
}
Each entry can be defined with a corresponding label name. Entries with "" are hidden from the editor, whereas segments left out (i.e. "shoes" in the above example) are skipped.
Saturn models support up to 8 texture "expressions" for users to customize. These can be eyes, sideburns, eyebrows, sunglasses - you name it, and they can be changed at runtime.
In Blender, create a new Fast64 material for each expression you want to add. This next step is arguably the most important - The texture's file name (not the material name) must contain the keyword saturn_<expression>, where <expression> is the name of your expression. This can be saturn_cape_asdanhfdfd or saturn_eye_blahblah, as long as it contains that keyword.
Next, create a folder inside your model's folder called expressions/. Inside that folder, create one folder for every expression, named after the keyword you specified above. For example, dynos/packs/<ModelFolder>/cape/. You can place as many PNG files as you want in these folders, and Saturn will swap them out accordingly.
For eye textures, we make one small exception:
As Mario's blinking state consists of 3 looping textures, Saturn makes use of Mario's unused "left" eye state for custom eye expressions.
In Blender, enter Pose Mode and highlight the 000-switch.001 bone (see below image).
Select Switch Option 3 (the left eye state) and assign a Material Override. We overwrite Mario's neutral expression with the eye material we defined earlier.
You can now set material overrides for each switch option (e.g. Switch Option 3 is left, we overwrite Mario's neutral expression with our new custom saturn_eye_blahblah material we defined earlier).
After exporting, select CUSTOM... in the Saturn eyes dropdown. If your eyes get swapped, you've set this up successfully!
As a side note, if an eyes/ folder is not present in expressions/, Saturn will use the dynos/eyes/ folder instead - This is helpful if you don't want model-specific eye textures!
As of 2023-07-06, Saturn now also supports custom blink animations! This allows animators to select any 3 eye textures to use in the model's blink cycle. Of course, for model authors, this requires one extra setup step:
Similar to how custom expressions work, each of the model's eye materials (most should have 3 - Open, Half and Closed), each texture file must contain one of the following keywords:
saturn_1eye <-- Eye Open
saturn_2eye <-- Eye Half
saturn_3eye <-- Eye Closed
And finally, add the following entry to your model.json file:
"custom_blink_cycle": true
Your model should then have the following feature in Saturn:
Optionally, if you have an expression that's just "on" and "off", you can choose to have it displayed as a convenient little checkbox instead of a dropdown.
Getting these set up is easy - just rename your 2 textures to default.png and none.png.
If you wish to reverse these (checkbox disabled by default), you can use the filenames 0-none.png and default.png so none appears first alphabetically.
By default, textures will be embedded in the model.inc.c file. Note that this does not remove or "bypass" copyright restrictions, it just reduces file sizes and makes textures harder to edit.
However, you can also choose to export textures as easy-to-edit PNG files.
To export textures alongside a Saturn model, navigate to Fast64 -> F3D Global Settings and enable Save Textures.
In each Fast3D material, make sure the Format is NOT set to Color Index. These will break in DynOS! I suggest using RGBA 16-bit instead.
And finally, before exporting, verify that Save texture.inc.c separately is disabled as it is incompatible with DynOS.
Exported models should now contain editable PNG textures. Note that after each model/texture edit, the mario_geo.bin file must be deleted (and Saturn relaunched) to reset the cached modeldata.
The mario_geo.bin file may be distributed without needing to include mario/ folder. This file contains pre-cached model data, which restricts it from editing. In a way, this allows model authors to "protect" their models from being modified directly.
NOTE: If you have copyrighted/vanilla textures in your model, it WILL STILL BE included in the mario_geo.bin file. Be careful on distributing them publicly! (gg Nintendo)