Custom Track Tutorial

See here for the making a custom track tutorial.

Introduction

 * Due to this wiki's efforts for accuracy of information, this page is protected so that only administrators can edit it. However, if you would like to make an edit, use this page's Discussion page or contact an administrator on discord.
 * 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, as well as look to see what vanilla does, 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.
 * If there is no source of the information listed, then you can assume that I came up with it myself. Anything with blender in this guide was contributed by Double Cherry in the Double Crew Server.

Important notes

 * A lot of the documentations linked, while useful and mostly correct, do leave out some information. I will try to fill in any missing information here.
 * “Vanilla” here refers to an original, unedited / unmodded file from the game.
 * When in doubt, copy from vanilla. This applies to just about everything here.
 * If you already have a program to edit a certain kind of file, that’s great for you, but if you run into difficulty with those problems, this guide won’t help you.
 * A lot of the programs listed give out error messages when something goes wrong - always check for an error message

 A note about the track-making process: Making a custom track is anything but a waterfall process, rather it is incredibly iterative. While aiming to completely finish the graphical model before starting on the collision is admirable, that aspiration is unfortunately unreasonable. Don’t worry if you find yourself going back to previous steps, everyone does that, and so will you.

Preliminary Information
What everyone needs to know for any mod, but repeated here for completeness. This section will be short because the information can be found in other tutorials on the wiki.

Breaking Open an .iso See Breaking open an ISO for more information.

Dealing with .arc files See Extracting and Packing .arc Files for more information.

Dealing with Crashes See Dealing with Crashes for more information.

Step -1: Choosing a Course Slot
The course that you will be replacing is very flexible; files for one course can easily be switched to go over another. Hopefully, as course slots become more fully implemented, this flexibility will remain. There are two main factors to consider when choosing a course slot You do not really need to worry about overriding a course slot that another non-vanilla track has taken. Most vanilla tracks have a non-vanilla track that it is "supposed" to go over.
 * Theme
 * Usually people want to change tracks to fit a certain theme - for example, an imported Rainbow Road might go over Rainbow Road.
 * As more tracks are made and as expanded course slots have not been fully realized, this factor becomes less and less important
 * Particle Effects
 * The particle effects that your track has is determined by the sound id of the course.
 * Changing around sound ids can be hard to organize, so it’s better to get a particle id that matches your track.

Step 0: An Introduction to Course.arc Files
In Filesystem/Course, you will see many different .arc files. Each of these contain the files for a course. Each course (except for Luigi Circuit) has two variants. For example, there is Peach.arc and PeachL.arc. The non-L courses are those that load in single screen mode, including Time Trial and 1-player Grand Prix mode. The L-courses are loaded in split screen mode, like multiplayer and LAN modes. There are no special .arc files for Mirror mode. The Mini .arc files are the battle maps.

A list of file formats commonly found in the main directory of course .arc files can be seen in the tables above.

Step 1: Make the BMD
Programs: Subtutorials:
 * SuperBMD - for converting to .bmd format
 * 3d CAD software (3dsMax / Blender) - for making the model
 * J3dView - Used for viewing and editing the textures of a .bmd
 * DouBOL Dash by shibboleet (viewing)
 * Using SuperBMD
 * Using J3dView

 A note about modeling software Most of the work will be done in a cadding program such as Blender/3dsmax. While you can use Sketchup, it is not the ideal option. Blender is free and open source, and for custom courses, is good enough to suit your needs. There are plenty of online tutorials for Blender and 3dsMax. In the end, no one can stop or force you to use a specific program.

Starting from scratch
Due to the highly subjective nature of custom track design, there is not much advice that can currently be given. However, there are a few general guidelines that generally improve gameplay experience and visual appeal. None of the following bullet points are in any way necessary for creating a custom track.
 * Import the vanilla .bco (converted to a .obj, as shown below) of the course/map that you wish to replace to make sure that the course model itself, including walls and roads, are about the right size.
 * Roads do not have to be a specific width to be fun to play, and they especially don't need to match the width of any road in the game. However, roads that are too skinny can be frustrating to drive on, and roads that are too wide can seem plain.
 * The purpose of a vanilla .bco is purely as a helpful reference, not as any source of prescriptive design rule.
 * Make sure to design a boundary along the entirety of the course between where the kart can go and any other designs. You can do this with walls or deadzones.
 * If using walls, the boundary should be at most 150 units above the ground below it. This is to prevent the camera from clipping through the boundary.
 * While backface cull is automatic in SuperBMD now, if you are making your own course, it is strongly recommended that you have borders because they look nicer and are the only way to guarantee issues of looking outside the course.
 * Avoid tight, sharp corners at all costs. The game will extend these corners beyond where you want them to be, which can be very, very annoying for players.
 * Do not create any bones in your model.

Texture Tips
 * The largest texture that the game will allow you to use is 1024x1024
 * If you have a texture whose dimensions are not a power of two, you can use it, but you cannot use mipmaps;
 * If the texture dimensions are not a multiple of 8, DouBOLDash’s .bmd viewer cannot show it.
 * The game will still load the .bmd

Starting from a pre-made model
Of course, not everyone is up to making an original design from scratch. A lot of the tips from above can still be applied to this scenario. For example,
 * Importing the vanilla .bco can help with determining the scaling of the track.
 * Boundaries can be created
 * Textures that are too large may need to be downsized
 * Only vertices weighted to the root bone will load in-game. If your pre-made model has vertices weighted to a non-root bone, delete all the bones.

Using SuperBMD
See the tutorial on Using SuperBMD for information.

Editing textures via J3dView
See the tutorial on Using J3dView for information.

Step 2: Make the BCO
Programs: Subtutorials:
 * mkdd collision by Yoshi2 (converting)
 * DouBOL Dash by shibboleet - used for quickly viewing the model
 * Using mkdd-collision

The collision should generally follow the model. Of course, you may need to add deadzones. Do to the subjective nature of the model files, collision files are also subjective.

However, some general tips can still be given to help playability Triangles that are too large can greatly increase file size, but there is a workaround that is seen later in the document.
 * Collision triangles don’t move.
 * Remove ALL doubles and make sure no polygon overlaps. The game will react by taking only one of these overlapping polygons, and completely ignoring the other.
 * Delete all useless triangles. This is basically any triangle that the kart will not interact with and vertical triangles.
 * In fact, vertical triangles will cause the game to bug out and trigger basically and out of bounds.
 * The game does not handle long, steep triangles well. Any very steep section should be cut into smaller triangles.
 * Other triangles do not need to be cut into smaller triangles, in fact, needlessly splitting up triangles is a bad idea.

Collision Flags
A list of all collision flags can be found here. The more common/useful/notable ones will be described in more detail here.

Flags Walls - Flags that stop your movement  Deadzones / Teleportation - Flags that point to respawn points  Boosts - Flags that make you speed up 
 * First two digits give the function of the flag: 0x01__ is normal road, 0x12__ is wall, 0x00__ is mud, and 0x05__ is deadzone. All flags with the same first two digits will have the same properties in terms of driving over them.
 * The second two digits give other properties
 * For roads/walls, it differentiates different triangles for the purposes of sound
 * For deadzones, it determines which respawn point is used.
 * WALLS ARE HORIZONTAL, NOT VERTICAL
 * Wall triangles should extrude at least 200 units from walls.
 * Neither players nor items can go over the edges of 0x02__ flags. Items can go over the edges of 0x12__ flags, but players cannot.
 * If you wish to make a wall that items (like shells) bounce off of, but get thrown over (like bananas), stack a 0x02__ triangle under a 0x12__ triangle.
 * You cannot simply have a big rectangle of 0x0200 flags underneath a course and have them work as regular walls, because it is the edges that matter.
 * As a general rule, below each ledge is a 0x02__ flag. Yoshi Circuit is a great example for this; under the edge triangles on the course, there are 0x02__ triangles. This keeps karts from clipping out of a ledge.
 * Rainbow Road and the bridge on Bowser Castle near the start are examples where there are no underlying 0x02__ triangles. Near the edges, it is possible to go under the course and then back on it due to this.
 * Walls or deadzones should surround the entire course, just like you designed earlier. This is to stop players from seeing outside the course / into the course when their kart is right up against it.
 * Deadzones are not out of bounds - deadzones refer specifically to collision triangles / areas that will put you back at a respawn point.
 * Out of Bounds refers specifically to a lack of collision that will put you back at the starting point.
 * The exact flag (the last two digits) determines which respawn point will be used. 
 * Deadzone Flags - These flags will take away your items.
 * 0x05__: these produce vertical lines when you fall into them / respawn
 * 0x0A__: these produce a circle, and are used when you are falling into air
 * 0x0E__: these produce the sand / falling animations, and are used only in Dry Dry Desert deadzone sand
 * 0x0F__: these are used when you fall into water / lava. They produce a wave line that rises.
 * In vanilla, these triangles are associated with GeoSplash objects in the .bol. However, due to problems with the conversion software, neither the wave lines nor the GeoSplash objects work in custom tracks.
 * 0x11__: these are the flags for Peach Beach sand, you don’t die if you go into them, but it determines the respawn point if you get killed by the dark water
 * Teleportation Flags - These flags will let you keep your items
 * 0x09__: Go super fast to the corresponding respawn point.
 * You need a GeoCannon object with the respawn point specified in its object settings in the .bol or the game will crash.
 * Also, the angle that the kart takes during its travel depends on the angle of the GeoCannon object.
 * 0x0D__: instant teleportation to the corresponding respawn point
 * 0x07__/ 0x47__ /0x37__: Zippers linked with a respawn point.
 * While these flags have an associated respawn point, your kart will still function like a normal zipper (0x0800) flag.
 * 0x020__ triangles surround all deadzones to prevent the player from going out of bounds, but this is not necessary for the game to function.
 * 0x08__: The basic boost
 * 0x09__: Explained above
 * 0x07__: Used on ramps - stops the falling animation from playing, (probably)
 * 0x37__/0x47__: Used on ramps - stops the falling animation from playing, (probably)

Step 3: Make the BOL
Programs:
 * mkdd track editor by Yoshi2 - used for viewing and editing the data

Due to the large amount of settings involved with the .bol, it recommend for users to read through the documentation, play around with the program, and look at vanilla .bol files.

General Information
 * Coordinate changes from the modeling software to the .bol editor: X stays the same, Y in the editor = z in the software, Z in the editor = -y in the software
 * The editor can load either a .bol file or an .arc containing a .bol file. In either case, only the .bol will be edited.
 * Loading an .arc file can be useful for long periods of only .bol editing.
 * You have the option of editing the vanilla .bol file, or just erasing everything from the vanilla .bol file and starting from scratch. Either way, you pretty much have to “make” the .bol file yourself as there are no good editors from other games to .bol.
 * Before testing something out in-game, always check for common errors using Misc -> Check for Common Errors
 * If you don’t know how to implement something, look around in vanilla .bol files and copy their implementation.
 * The "Ground Object(s)" button is very useful
 * You can load .obj / .bco / .bmd files by clicking on “Geometry” and then selecting the appropriate action
 * Note that to load a .obj, the .mtl file must be in the same folder
 * You add anything by clicking on the “Add Objects” button on the top right.
 * Then, click on the drop-down menu to change the type of object being added

Header
 * Most of the time, "Tilt" should be set as “None”
 * If you want to use Daisy Cruiser tables, set this to “Only Sky / Items”
 * If you want the course itself to move, set this to “Entire Track”. This will make the course function like Tilt-A-Kart
 * However, this might make your track unplayable without serious collision modification
 * Lap Count
 * Beyond seven laps, the game is unable to store individual lap splits in ghosts.
 * Course music:
 * Individual course music is dealt with via the patcher. In development, this value can be left alone.
 * The particles that come out of the kart when you drive over a certain collision flag is determined by the sound id.
 * SL Environment effects: Should be unchecked unless you are making a snow-based course.
 * Create the snow falling effect and the ice when respawn from a deadzone

Enemy points
 * The “scale” setting specifies how far off the path enemies can go. A larger value means more potential separation.
 * A black line between two points means that the two points are in the same group. A blue line between two points means that the two points are in different groups, but still connected.
 * To link groups together:
 * All points in a group that are not at the start/end of their group should have a link setting of -1.
 * All start/end points in an enemy group should have a nonnegative link setting.
 * No two points in the same group should have the same non -1 link setting.
 * All points that you want to link should have the same link setting. Start with 0 for the first connection and then go up by 1.
 * You may run into an issue with how the kart follows these paths after a time trial run is completed. This means that towards the end of the course, the kart went off the “path” specified by the point / scale setting. You can fix this by moving the points around or increasing the “scale” value.

Checkpoints
 * Make sure that all checkpoints are pointing the right way and evenly spaced.
 * You can see the direction of the checkpoints by the arrow in the editor.
 * The red point should be to the “left” of the blue point from the perspective of the kart start point.
 * All checkpoint boxes should form a convex quadrilateral, or else the game will not count them and you will not be able to finish a lap.
 * Checkpoint boxes are formed by the four points of two consecutive checkpoints
 * This can easily be checked by Misc -> Check for common errors
 * Checkpoint Settings
 * Unknown One: Used to make dev-intended shortcuts, like in Yoshi Circuit and Bowser’s Castle
 * Normally 0 - leave as 0 if unsure
 * All checkpoints in the group use the same number; different groups should use different numbers. If checkpoint 20 has “1”, and checkpoint “50” also has “1”, checkpoints 20 - 50 will be thought of having “1”.
 * Having too many checkpoints are in any group could affect lap completion.
 * Unknown Two: Used when going back over the same course - only used in LC
 * Having the checkpoint boxes cover the entire driveable area of a course helps deal potential lap completion issues.

Objects/Object Routes Item Boxes
 * Most of the known object settings can be found in the latest version of the editor, but a complete list of item settings can be found on the Objects page.
 * Making sure that each object has its required assets is very important, as the game will crash without them.
 * If you plan on using items that are normally found in the game, copy their implementation from how they are used in vanilla, and then tweak it from there. This includes object setting values and necessary assets (.bmds / shadow .bmds / animation files).
 * Making custom item models
 * If you want to make a custom model for an object, all of the animation files for that object that are found in vanilla need to be included. Information about how to make animations is listed later.
 * Item collision are hardcoded, meaning that you cannot change them.
 * Routing objects
 * Items that don’t already have routes, as a general rule, cannot suddenly be routed, and items that normally have a route need a route.
 * Different items go along their paths differently; WS piranhas will always face the same direction, but DC seagulls will change direction to follow the path. The MB/MuC vehicles will teleport from their last route point to their first.
 * Only the MB/MuC vehicles and SL Shy Guys use object route parameter. For the vehicles, if non-zero, it it set to the next value. For the Shy Guys, a "1" will cause the Shy Guy to jump at that point.
 * Types of Item Boxes
 * GeoItemBox (id # 0x01): The standard in-place item box. Can be double or single. Its model is shared by all courses.
 * GeoF-ItemBox (id# 0x0a): The standard routed item box. Can be double or single. Its model is shared by all courses.
 * TMapObjMoveItemBoxLimit (id# 0xdb0): The routed item box used on DC that is synced with the tables. Are only single. Its model is shared by all courses.
 * GeoItemCar (id# fa8): The routed item box used on MB/MuC. Are only single. Its model is kept in the objects folder of the course.arc
 * Object settings for GeoItemBox and GeoF-ItemBox
 * 1 - Height Offset: How much the item box is raised from its y-value. Should be set to 135. Also used by TMapObjMoveItemBoxLimit
 * 2 - Item Box type - 0: Either. 1: Always single. 3: Always double.

Areas/Cameras Replay cameras Grand prix course intro specific cameras Camera type 8 - the immediate post-race camera Camera Settings
 * 0: Unrouted camera
 * 1,7: Routed camera. 1 is more standard
 * Require an associated area in which it will be used
 * 4 ("DoStartFixPathCam"): Will travel on the path specified, but only focus at its start point
 * 5 (“DoStartPathCam”): Will travel on the path specified, but move its focus between the start / end points
 * 6 ("DoStartLookPathCam"): Will remain stationary, but move its focus between the start / end points
 * Other types of cameras can be used for the grand prix course intro, but it is not common.
 * Grand prix cameras are the only cameras that use the “next camera” setting. The first camera is specified by a “1” for the “Start Cam” setting, and the last camera has a ‘next camera” of -1, like normal cameras.
 * The sum of the durations is usually around 600. Higher durations won’t cause the game to crash, but there will be an awkward time after the music is done and the cameras are still running.
 * Identical in all courses - should not be touched
 * Its direction is used in replay cams when a kart is not inside Type 1 area
 * Zoom - the angle of viewing
 * A higher zoom means a wider angle
 * Should be kept within (0, 90).

Areas
 * 0: Shadows
 * 1: Have a camera
 * 2: Disable SL environment effects and function as a ceiling
 * 7: Used for special lighting - connects with a LightParam index
 * The y position value is always at zero, but you may need to adjust the value of the y scale to get it to work

Testing
 * Can be tested by watching the replay of the course after a time trial or grand prix mode.
 * If there is a section of the course which is not in an area, then the replay camera will view the kart from one fixed view, as seen here.

Respawn points
 * Every deadzone area should have a respawn point associated with it, if not, the triangles will act like normal road.
 * If there are issues with lap completion after respawning, moving the respawn point backwards by a few checkpoints usually fixes the trick.
 * The route point setting, which defines which route point karts will seek out after respawning, must be set.
 * There is a setting for the checkpoint preceding the respawn point - should be left as -1 if unsure.

Step 4: Make the BTI
Programs: Subtutorials:
 * Wiimm's SZS Tools by Wiimm
 * mkdd track editor by Yoshi2
 * Converting Images

Minimaps are less subjective than the previous steps, so stricter advice can be gen.
 * Each minimap image has the dimensions of 128px in length, 256px in height
 * Course minimaps are in grayscale, while battle minimaps are colored. However, a course can load a colored minimap.
 * Colored minimaps for courses are often difficult to see (defeating their purpose), and whenever implemented so far, they have looked plain bad. Don't color your course minimap.
 * The transparency of the minimap is applied by the game; all minimap image pixels are either fully opaque or transparent. Basically, use the CMPR image format.
 * Cannons and notable areas of offroad (such as the pit in Dry Dry Desert) are usually indicated in gray.

 Creating a mimimap image in Blender
 * 1) Trace over the road collision mesh/object with a Nurbs curve.
 * 2) Solidify the curve by going to the “Modifier” section and adding a “Solidify” modifier. The thickness of the Solidify modifier will determine how thick the outline will be.
 * 3) The outline is a faux outline in which the solidified curve is duplicated, and further thickened and extruded less.

 Creating a minimap image using the mkdd track editor 
 * 1) Load the .bco into the course editor, and make everything invisible. If only one road collision flag it used, highlight it. Take a screenshot of the main workspace.
 * 2) In an editing software, get rid of all the non-road pixels, and make the resulting image white.
 * 3) Shrink the image to fit into a 128x256 image. Apply a 1-3 px solid colored black outline.

Changing game Minimap positions
 * 1) In the mkdd track editor, Minimap -> Load Minimap Image, also, load the .bco
 * 2) Move the corners so that the .bco/.bmd and the image line up
 * 3) Minimap -> Save data to JSON. This will create a file that can be shared to others who want to play the course.
 * 4) Minimap -> Save data to .dol. Then, choose the .dol that will affect your gameplay. This will edit the actual .dol so that the minimap works in-game.

Step 5: Make the Animations
Programs:
 * btk-conv by Yoshi2 for BTK files
 * bark-conv by Yoshi2 for BRK files
 * BTPxT by MasterF0x for BTP files

While all the above steps are mandatory for a custom course to load, animations are not. Nevertheless, animations are an easy way to add movement and excitement to a stage.

BTK / BRK Specifics
 * These files have keyframes, meaning that an animator only needs to specify values at specific, important frames.
 * Every material animation in the same file will share the same duration and loop mode
 * Tangent values define what the value will be in between the keyframes
 * For Bezier Interpolation, set the tangent at "0"
 * For linear interpolation, set the second tangent of the current keyframe and the first tangent of the next keyframe to be (next value - current value) / (next time - current time)

BTP Specifics
 * In .btp files, every frame of an animation must have a defined value
 * The values in a .btp file correspond to the order of the textures in the texheader .json file
 * Specifying "0" for a frame in the .btp file will cause the texture at the 0th index in the texheader file (the first one) to be loaded in for that frame.
 * Each material animation, even in the same file, has its own duration. There is no loop mode for .btp files.

Step 6: Make the GHT
Program: Subtutorial:
 * Dolphin Emulator or Nintendont - to create a ghost .gci file
 * Any hex editor - for editing the .gci file
 * gci2ght by tarsa129 - for .gci -> .ght conversion
 * Replaying Ghost Files

The .ght file is the staff ghost. It defines the inputs that the staff ghost will do when it is enabled.

To make a staff ghost file, first make a regular ghost file
 * 1) Boot up the game without any gameplay modifying mods / ar codes. This includes anything that affects the collision, any edits to kart stats, or any speedup ar codes, and more.
 * 2) Turn on ghosts in the Options menu, and then play a course to completion and save the ghost.
 * 3) Get the .gci file of the ghost, either by looking into the Dolphin folders or extracting it from a .raw using Dolphin’s memory card manager.
 * 4) Every time the collision is edited, a staff ghost may have to be remade

Then, edit the .gci file to make it staff ghost compatible.
 * One method is to use gci2ght by tarsa129. Simply drag the .gci onto the .py file, and an appropriately named .ght will be made.

Another method is to do it manually
 * Open the .gci file in a hex editor, like HxD.
 * Scroll down to offset 0x1480, and delete everything before that. The first 16 bytes of the modified file should have your time trial tag.
 * You could also delete the last four bytes (the checksum for the .gci) but it is not necessary.
 * Do not edit anything else - they will / could mess up the staff ghost
 * Save the resulting file as .ght. The resulting .ght file should be 35 kb.

Testing the staff ghost: One can test the staff ghost by putting into game files and then running it in-game. Time Trials Mode: Show Staff Ghosts [Ralf] 22MC-1MAZ-QYZUQ 3KD7-PHV6-M0QVA TU4W-M2DF-VUZK1
 * 1) First, turn on the above ar code by Ralf from here
 * 2) This will ensure that the staff ghost is visible without having to "unlock" it.
 * 3) Then, play a round of time trials. Make sure that the staff ghost stays on the course for the entire duration of the course.

Another method is to use MKDD Ghost Info and Dolphin Lua Core by SwareJonge to replay the ghost. See Replaying Ghost Files for more information.