Custom Track Tutorial/BOL

The BOL file format as an anime girl

mkdd track editor Basics

There is only one tool that is practical for editing .bol files, the mkdd track editor by Yoshi2, updated by Cristian64. It loads the course features in a viewport in the middle. There are many different features, but the basic ones are described on this page. More advanced features are described in the link above.

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.
With one or more objects selected, the "Ground Object(s)" button will change their y-values to be the closest y-value in the model loaded (if any). It 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.

Basics for Course Functionality

These two parts of a .bol file, especially starting points, are the basic necessities required to play a track.

Starting Point

The starting point defines where a player will start on the course. For normal racing track files, there is only one of these with a player ID of 255 / -1. Move this to the desired starting point, rotate it as needed, and ground the point.

Checkpoints

Checkpoints track the progress of a racer around the track. Consecutive checkpoints form boxes, and the entirely of the track should be contained with these checkpoint boxes.

Make sure that all checkpoints are pointing the right way and evenly spaced. The red point should be to the “left” of the blue point from the perspective of a racer.
You can see the direction of the checkpoints by the arrow in the editor.
All checkpoint boxes should form a convex quadrilateral, or else the game will not count them and a player 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 in any skippable group could affect lap completion, making a lap unfinishable.

Extended Basics for Course Functionality

While these sections are not strictly necessary for a track to be played, they provide such necessary functionality that they should be done for all tracks.

Header

This section defines miscellaneous course information, such as lap count, course music, light colors, and more.

Most of the time, "Tilt" should be set as “None”.
- For using Daisy Cruiser tables, set this to “Only Sky / Items”.
- For Tilt-a-Kart style tilted, set this to “Entire Track”. This might make your track unplayable without serious collision modification.
Lap Count should be 3 most of the time, but never greater than 7.
- Beyond seven laps, the game is unable to store individual lap splits in ghosts.
Course music:
- Individual course music is dealt with via the MKDD Track 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.
- Creates the snow falling effect and the ice when respawning from a deadzone.

Enemy points

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 unless there is only one group.
- 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 see when this occurs by hooking the editor into Dolphin and seeing when an enemy path point is not highlighted.

Objects, specifically Item Boxes

Item boxes enable players to collect items in non time trials modes.
There are four objects that modders can use to add item boxes:

GeoItemBox (id # 0x01): The standard in-place item box. Can be double or single. Its model is shared by all courses. This is the item box that modders should default to.
GeoF-ItemBox (id# 0x0a): The standard routed item box. Can be double or single. Its model is shared by all courses. This is the routed item box that modders should default to.
- Routes will be discussed in a later section.
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

The two basic item boxes have two important settings.

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.

Respawn Points

Uses
Respawn points are most commonly used to define where a kart respawns after hitting a deadzone. However, they are also used to define where a kart will travel to from a cannon and to define a goal point for a kart when it goes on a certain type of zipper flag (0x37__ and 0x47__).
Settings

Respawn ID is the second byte of the flag (deadzone, cannon, and zipper) that the current respawn point is used for.
The Next Enemy Point of a respawn point determines the enemy point that the CPUs will travel to after respawning. It must be set to a valid enemy point, preferably the next enemy point after the respawn point. The index of each enemy point can be seen on the of the editor. For example, setting this value to "56" will cause cpus to travel to the point labeled as Enemy Point 56 in the editor.
The "Previous Checkpoint" is useful when one respawn point exists in multiple checkpoint boxes. Setting this value to be the checkpoint right before the respawn point will help avoid errors related to lap completion. When this is not necessary, set this value to -1

More Advanced Core Sections

Paths / Routes

Routes are paths that certain objects and cameras can travel along. They are defined by two more more object path points. Each object and camera have a field for a path id, which is set to -1 if not used, and the index of the intended path if used. The index of each path can be found on the left of the editor. For example, setting a path id to "7" will connect it to the path labeled as "Object Path 7" in the editor. The specifics of routes will be discussed in the specific Object and Camera sections.

Objects

Additional objects are great for adding to the environment and gameplay of a track.
Basic Settings

Whether or not an object shows up in any given mode is determined by the Presence Mask and the Presence.
- Presence Mask = 255 means that it will show up in time trial and non time trial modes. If this value is set to 15, it will not show up in time trial mode.
- Presence = 1 means that it will only show up in single-screen modes. Presence = 2 means that it will only show up in split-screen modes. Presence = 3 means that it will show up in single screen and split screen modes. In cases where including an object in a split screen mode will cause lag, setting a Presence to 1 will allow the object to show up only in a mode where it will not cause lag.
Collision determines whether or not an object has collision. Not all objects will have collision.
Each object has fields for 8 additional settings, but very few (if any) objects actually use all 8 fields. Most use around 2-3. These settings change by object; setting 3 of one object will not necessarily function in the same way as setting 3 of another object. 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.

Adding an Object to a Course

Many objects have a list of required assets. With an object selected in the editor, the required assets are listed on the bottom right hand site, under all of the object settings. These assets are found in a subfolder within each .arc file called "objects". The game will crash if all required assets cannot be found in this folder.
When using an object for the first time, it is highly recommended to copy their implementations from vanilla (including whether or not they are routed and any object settings), and tweaking from there.

Editing Objects

Reskinned objects and edited animations can be made for each objects. The process for this is the same as editing course models / animations.
- Item collisions are hardcoded, meaning that you cannot change them.

Routes

Objects, as a general rule, are either routed or not. Adding routes to a normally unrouted object will probably do nothing.
- 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.
Each object's Path Point ID defines the point in the path that the object starts at.

When Areas and Cameras Work Together

Areas of type 1 connect to a camera. Replay cameras

0, 2: Unrouted camera
1, 7: Routed camera. 1 is more standard
Require an associated area in which it will be used

Camera Settings

Field of View - Should be kept within (0, 90).

Areas Alone

There are more area types than just for cameras. A quick rundown of them is below.

0: Shadows
2: Disable SL environment effects and function as a ceiling
3: Unknown (Used in Waluigi Stadium over the final gap)
5: Used to disable falling animation when going off a zipper
6: Unknown
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

Cameras Alone

Grand Prix course intro specific cameras

1: Travels on the path specified, looking at the direction where it is pointed.
4: Will travel on the path specified, but only focus at its start point
5: Will travel on the path specified, but move its focus between the start / end points
6: Will remain stationary, but move its focus between the start / end points
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.

Immediate post-race camera

All vanilla post race cameras have a type of 8, but that is actually not used. The camera used for immediate post-race cameras is determined by the "name" field, which must be "para".
Settings are identical to type 7 cameras.

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.