Custom Character Tutorial

Introduction
-tarsa129
 * Help for specific issues that you may experience should be asked in the Double Crew server.
 * It is highly recommended that you read all relevant readme files and documentations, look to see what vanilla does, AND read outputs from programs before asking (potentially annoying) questions. This guide will assume that you have read all the relevant material, unless it is especially noteworthy, because I do not wish to copy words that are perfectly written elsewhere.

Video Tutorial: PmC87QrKiZM

Breaking open the .iso:
You need to break open the .iso in order to access / modify the character files. See the page on breaking open an .iso for detailed information.

Breaking open MRAM.arc:
Most of the edits will take place in MRAM.arc. See Extracting and Packing ARC Files for information on how to extract and pack files for MRAM.arc.

Folders in MRAM.arc (that are relevant to characters):
 * driver:
 * Each character has their own folder for their driver.bmd and facial animations.
 * There are also “common” folders for common animations among similar characters.
 * The character model is driver.bmd. The .btp files are facial animations.
 * kart
 * Each character has their own folder for their kart + the parade kart
 * Contains models for the body, left and right wheels, and under-body parts.
 * item
 * Contains models for all items, including special items
 * setting
 * Contains setting files for each kart
 * shadow
 * Contains shadow models / animations for all karts
 * CURRENTLY CANNOT BE EDITED
 * MRAM.arc/race2d.arc|race2d.arc
 * Contains various images like:
 * Character select screen image
 * Character minimap icon
 * Icons for the kart / special items
 * Can be opened in the same way as MRAM.arc

A Note about File Size:
There are two ways in which a character model that is too large can crash the game: Both can causes game crashes, and should be avoided. As a general rule, your custom character should be around or below the vanilla character's size.
 * The file itself is too large ( > 90 kb)
 * MRAM.arc is too large
 * Large MRAM.arc files can cause crashes on either game startup or course loading
 * While there is a way to get around MRAM.arc size restrictions, it causes loading times to skyrocket, and is thus not recommended to play with.

= Editing Characters =

Getting the Vanilla Model
Basing your character off the vanilla model (rig and material/texture setup-wise) makes it easier to get the character working as intended in-game. Using an edited or custom skeleton can cause issues with the bone animations, which are tedious to edit.

SuperBMD
Using SuperBMD on a vanilla driver.bmd file, a character's model, rig, and material and texture data can be obtained. See the SuperBMD tutorial for information. This set is important for all users regardless of Blender/3dsMax, because the .json files will be used when converting back to .bmd later.

Blemd
If you are using Blender, the .dae output of SuperBMD might not work for you. In this case, you can use blemd to import the vanilla model into the game.

Getting a Non-Vanilla Model
Pre-made Models Your new model can be from a variety of sources, but getting it is up to you. If you want to use pre-made models, you can look at Models Resource or you could get one from the files of another game.

Character Edits Character edits - taking a character model and changing it slightly to create a variant of the character - is also a popular choice.

Making a model If you wish to make your own model, look at some of the tips described in the next section.

CAD Software / Pre-Conversion Instructions
Tools Needed: 3dsMax/Blender, Image editing software

Meshes
Making a character model is a highly subjective practice, so it is impossible to give instructions. However, tips can be given.
 * Try to keep the model to under roughly 700 faces, in order to keep file size down. If you got a model from another source and it is too high poly, you must optimize / decimate the model.
 * Using the vanilla mesh for the arms and legs can help the animations look better, and it saves time for you.
 * Unless you can or are willing to edit bone animations, you should try to sculpt your model around the vanilla model. (Hint: you don't want to edit bone animations). Getting the vanilla rig is described above.
 * Normals should be unified / smoothed if you want your character to look smooth.
 * Before rigging, there should be (at most) one mesh for the body and one mesh for the eyes/face. Have a separate face model (whose name is alphabetically after the name of the body) may be essential for having materials applied correctly.

Bones/Rigging
To get the vanilla bones to use in rigging:
 * 1) Import the character into your software via the steps above. If using blemd, rename the "driver_armature" skeleton to "skeleton_root".
 * 2) Delete the meshes that come with the import.
 * 3) Import the mesh that you want to use.

Rigging Tips:
 * There should be no vertices attached to charactername_all, or any of the hand/feet pose bones. However, they should still be in the skeleton.
 * Not all other bones have to have vertices weighted for them.
 * When in doubt, refer back to vanilla (especially if you are not going to edit any bone animations)
 * It is okay to have both face and body in one mesh, as long as they have different materials.
 * A face-only mesh should only have the face bone attached (in 3dsmax skin modifier)
 * Partial weights are discouraged unless necessary. This is because they increase .bmd size.
 * If you must have partial weights for a vertex, try to keep it at 50% weighted to one bone, 50% to another. Any other weightings may cause the game to crash at the opening menu screen.
 * (If using 3dsmax) Add all the bones to the skin modifier except skeleton root.
 * If using blender, make sure to delete all _end bones (if there are any) and to export without any _end bones added. These bones will mess up animations.
 * In 3dsmax, when you export, you should not get any popup about incorrect bone binding matrices.

Materials:
The body and the face should have different materials (if the vanilla model has two different materials), but they can be part of the same mesh. The material names (don’t worry about textures or meshes mesh names) of the body/face on your model should match those of the vanilla model as stated in the .json files. If not, the game might crash. Usually the body name is: characterfoldername_all_tx And the eye name is: characterfoldername_eye_tx But you should check for the specific character that you are replacing.

While knowledge of how the material settings affect how a character will look, it is (mostly) beyond the scope of custom characters. The only changes that one should be doing to material .json files for custom characters (in the vast majority of cases) is editing texture names and cull mode.

Textures:
The texture names, for your convenience later, should also match the vanilla names, but changing them will not cause a game crash. If you do change the texture names, you must edit the material and texture .json files to match. As this can be annoying, it is recommended to stick with the vanilla names.

The texheader .json file: The texheader files is used to specify all the images in the .bmd. It is compmosed of an array of texheaders, which each define a texture. This allows characters to have facial expressions. Many texheader settings can be changed in J3dView, but it is easier to change them in the .json file so that you do not have to reedit them after each conversion. is a basic list of texheader settings. Here is a list of relevant texheader settings for characters:
 * Format: None of your textures should be in the RGB5A3 format. This will take up too much filespace and cause the game to crash. Use CMPR or a grayscale format instead.
 * WrapS / WrapT - basically WrapU / WrapV
 * Define how UVs should act when a meshes UV's put them outside of the texture.
 * S is for U, and T is for V
 * "Clamp" will put the UVS at the closest edge of the texture, "Repeat" will cause the texture to be repeated over all UV space, and "Mirror" will cause the texture to be mirrored over all UV space.

If you are using Mipmaps for a texture, you need to set: All textures (except for the highlight texture) for vanilla characters in this game have mipmaps.
 * MipMap: 1 (instead of 0)
 * MinFilter: “LinearMipmapLinear” (instead of Linear)
 * MaxLOD: # of mipmaps (instead of 0)

For Faces:
 * Make sure that you have vanilla number of facial textures (usually 6). If you do not plan on editing the .btps, it would be wise to try to match the expressions.
 * If you have less than the vanilla number of facial textures, you will have to edit the texheader.json file. Basically, just copy the texture data for a texture that you do have one texture over the textures you do not have. Doing so will not increase the file size, but will save you time in editing the .btp files.
 * If one edits the .btps, it is possible to change the number of facial textures needed, but this can be tedious.
 * In the cadding software itself, you only need to load the first eye texture (the one with a 0 in its name)

 Shading:  In order to get the vanilla shading, you must use the vanilla material .json file in conversion (explained later). This material uses the highlight texture, which is an output of the .bmd -> .dae process. If your normals are good, your shading still might be off. The best you can do is adjust normals and pray.

The LOD Model
In each driver folder, there is a driver.bmd and a driver_200.bmd file. The driver_200.bmd file is a low-poly version of the driver.bmd file. They usually have around 200 faces and have one 64 x 64 texture. This file is used for other character models in 3/4 player split screen mode when any other kart is a distance away from the "main" player for that screen. To make a LOD model:
 * 1) Optimize the texture and the model to be roughly what it is in vanilla - 200 faces and a 64x64 texture that has the body and the eyes. Optimization can be done via Blender's Decimate modifier, 3dsMax's ProOptimize modifier, or done manually.
 * 2) The rigging, material, and texture instructions are the same as for the main model - make sure that the material names match.

Using SuperBMD / Conversion Instructions
Here is an in-depth article on how to use SuperBMD. Some of the more basic points are reiterated here. Once you are done with your model, export as a .dae or .fbx using SuperBMD. Exporting as a .obj will not save the rigging data. When converting to .bmd, the driver_materials.json and tex_headers.json files must also be specified in the SuperBMD conversion so that the model's shading matches that of the vanilla character models in-game.

To use SuperBMD: This process can also be done using the command line, but that can be more tedious, and offers no benefit over a .bat file.
 * 1) Create a new .bat file, and put the following text in it:   --mat --texheader
 * 2) Replace the words in  to the correct file names.
 * 3) Run the .bat file, and a .bmd file with the name as the outputfilepath (if specified, inputfilepath.bmd if not) will be created.

For example, a typical .bat file for this purpose might look like

C:\Users\username\Documents\mkdd\course-related-programs\superbmd\superbmdfiles\Superbmd.exe file.fbx driver.bmd --mat driver_materials.json --texheader driver_tex_headers.json

J3dView:
See Viewing Animations in J3dView for more information.

After the new driver.bmd file is created, you may want to check on its textures and materials if you did not do that before conversion. Open J3dView and open your new .bmd file. If the textures look strange, try editing the texture settings in J3View (especially the Wrap S/T settings), and then when you are happy, apply the changes to the texheader .json file. If you ever have to re-convert from .dae / .fbx, you will not have to change the .bmd in J3dView again.

J3dView is also great for seeing how character select screen animations will look like before putting them in-game.

Additionally, character facial animations can be viewed. Viewing them in this method is a lot easier than viewing them in-game, because testing in-game will require actually triggering them in-game. However, viewing them in J3dView takes the animations out of context - one would not want a happy animation when the character is burning, for example.

 Testing:  Be sure to test in all game modes: Time trials, Grand Prix, and 2-player. Like with other mods, if it works on the latest version of Dolphin, it will probably also work on console, but it never hurts to check. Some things to look out for:
 * Does it crash?
 * A character that works in the character select screen is not guaranteed to work in-game due to MRAM.arc file size restrictions
 * Some models (those with incorrect material names), will work in time trial mode, but not in grand prix mode.
 * Animations / Rigging
 * Do all the animations look natural? The range of animations in grand prix / versus mode is a lot bigger than in time trial mode.
 * Are you happy with it?
 * In the end, it all comes down to whether or not you're happy with the mod. This is something that you have to decide for yourself.

A model with partial weights may cause differences in how they look in the viewers vs how they look in-game, and may introduce more places for crashes.

Necessary Images
All necessary images for characters are .bti files. Your character mod is not complete without these files.

Character names: 
 * Kept in Filesystem/SceneData/English/menu.arc/timg
 * Dimensions: 156 x 32
 * Tool: MKDD Text Maker
 * Make the vertical scaling 75%, and the horizontal scaling at most 75%.

 Character selection icon:
 * Kept in Filesystem/MRAM.arc/race2d.arc/timg
 * Dimensions: 64 x 64
 * Try to match the vanilla angle, and the image should not have an outline.

 Minimap icon: 
 * Kept in Filesystem/MRAM.arc/race2d.arc/timg
 * Dimensions: 32x32
 * Basically a straight on headshot on the character. Should have a 2px gray outline.

 Image Conversion / How to use wimgt:  See Converting Images for information.

Custom Voices:
Custom voices can really deepen the immersion of a custom character - no one wants Baby Peach calling herself "Baby Mario." WSYSBuilder by Xayr is used for these edits. To use it:
 * 1) Inside Filesystem/AudioRes, extract the program and run "initialize.bat", which will create a folder called "Audio_Modding", where you will do the edits.
 * 2) Inside the Audio_Modding folder, there will be separate folders for each .aw file.
 * 3) Inside each of these folders, there are folders for the vanilla sound clips ("wav") and for the custom sound clips ("custom")
 * 4) To replace a vanilla sound clip, put a .wav of the same name in the "custom" folder.
 * 5) When you are done, run "rebuild_all.bat" in AudioRes.

Concerns regarding custom voices: While custom voices complete a custom character, and allow for immersion, there are some concerns about their release. However, editing these custom voice clips would replace all of the .aw files as well as the GCKart.baa file. This means that for multiple characters to have custom voices, a specific pack for just those characters has to be compiled and released. Additionally, the fact that it overwrites the .baa file means that the release with the character voices must be the first mod packed into a game on its own patch, and then everything else can be added.

 Editing the .btp Files:  .btp files are texture swapping animations that animate facial expressions on characters. Character facial animations are found in the character-specific folder in Filesystem/MRAM.arc/driver. Additionally, there is a gut.btp found in the character-specific folder in Filesystem/SceneData/selectAnm.arc. This is the animation that plays alongside character confirmation. In character selection / character waiting, the texture in Frame 0 of this animation is used.

Use BTPxT to convert each .btp file into a .txt file. The number for each frame corresponds to the image of a texture as specified in the texheader.json. When you are done editing the .txt file, convert it back to .btp using the same program.

Bone Animations:
Character select animations are kept in character-specific folders in Filesystem/SceneData/selectAnm.arc. These are .bck files .bck files can be viewed in J3dView via the steps above. If replacing Mario or Luigi, the scaling on the arms may be weird. One theoretical fix is to edit the scaling of Mario's arm bones to be 1.0 in the animations. Most of the in-game animations are kept in Filesystem/ARAM.arc/driveranm. These are .bca files. Here is an incomplete documentation of in-game animations Drifting / Juggling animations are kept in Filesystem/MRAM.arc/driver.These are .bca files.
 * enter.bck is the animation that plays when you first select a character
 * wait.bck is the idle animation
 * gut.bck is the animation that plays when you confirm the characters / kart combo.
 * a_drive_a: front seat no item
 * a_drive_b: front seat holding item
 * b-appeal: that animation that plays when the backseat character doesn't have an item, but you try to use one anyweay
 * b-dash-b: back seat starting boost animation / initial mushroom boost animation
 * b_dwait_a: backseat hanging off
 * b_dwait_b: backseat hanging off
 * c_wait_b: mushroom pose - no sideways input
 * d_run: before the timer starts, this animation occurs when you press the a button and the character runs in place
 * d_wait_a: before the timer starts basic waiting animation
 * e_1st_b: backseat first place animation
 * b_ means backseat, front facing
 * c_ means backseat, back backing
 * _a means without an item
 * _b means with an item
 * l means left drift, r means right drift, and s is the shifting animation

Why changing some animations can be a bad idea:  Some characters share in-game animations with others. Changing any shared animation changes the animation for all of the characters. Trying to "unshare" the animations by putting them in the character-specific folders is currently untested, and issues due to file size arise.

= Editing Karts =

Kart model files are kept in Filesystem/MRAM.arc/kart. It is generally expected that you edit the character’s kart to match the character if necessary, because karts are tied directly with characters in this game.

Kart Model Files:
 * body: the main body of the kart
 * tire_l: the left wheel
 * tire_r: the right wheel
 * shock: coil that connects the wheel to the body - typically on the side of the body
 * arm: metal bar that connects the wheel to the body - typically under the body

Just doing a texture hack (J3dview):
See Doing J3dView Texture Hacks for more information.

Actually editing the kart model:
Follow the steps for converting from .bmd into .dae as shown above for characters, and import the kart model into your cadding program.

Meshes:
 * Keep the geometry of the chair, back platform, steering wheel, and handle close to vanilla. Keeping their height the same is essential, but small adjustments can be made to their length and width.
 * In general, try make your kart similar in length, width, and height to the vanilla model so that it does not look weird in-game.

Rigging:
 * The main bone defines where the front character will sit.
 * There is no bone for the back character, but you can tell where the back character will be by the model
 * It is recommended to not move / scale / rotate this bone.
 * All vertices should be rigged to this bone.
 * The other bones define where the exhaust comes out
 * This is not technically necessary - no exhausts are required.
 * Having up to two exhaust bones has been tested to work. 3+ is currently untested.
 * In 3dsMax, the Skin modifier for the kart should the main bone and the exhaust bones added, but vertices should only be weighted to the main bone.

Materials / Textures:
 * Try to use the vanilla materials / texture names with the custom kart.

 Editing Kart Stats (not recommended when releasing):  The structure of each .set file is actually very simple - it’s just a bunch of floats. You can edit these with a hex editor or MKDD set file editor. The reason that releasing edited kart stats is not recommended is because they can mess up custom track staff ghosts.

 Necessary Images:  Kart Icon:
 * Kept in Filesystem/MRAM.arc/race2d.arc/timg
 * Dimensions: 64x64
 * Can be created by taking a screenshot of the kart at the desired angle in-game, and then cleaning up the image.

= Putting Everything Together = Programs:
 * See mkdd rename release files by tarsa129 for more information.