SpaghettiKart/docs/tracks/trackoverview.md

\page trackoverview Overview

Custom Track Overview

This guide is not all-encompassing but rather covers the utmost basics for track creation.

Dependencies

• Blender v4.3 or older.
• Harbour Masters Fast64 https://github.com/HarbourMasters/fast64

Configuration

• Set Fast64 Global Settings to MK64
• Set F3D Microcode to F3DEX

Adding the surface

• Add an empty and place it at coordinates 0, 0, 0

• Select the empty and in the object panel select Track Root

  • This is the root of the custom track. All mesh and path are placed within.

• Remove the default cube

• Add a plane and place it at coordinates 0, 0, 0

• The drivable surface must be a flat mesh. It cannot be a cube.

• Select the plane and scale it to a reasonable size by pressing the s key and dragging with the mouse.

  • Z coordinate -420.0f must have mesh under it for the players to spawn correctly.
  • This is approximately -16.8 Y in Blender units (420 / scale of 25)

• One method to test the plane size is by adding a cube

• You will likely want the surface mesh to be a bit bigger. However, this size will meet the spawn requirements.

• Delete the cube

You now have a valid surface for racers to drive on. Multiple surfaces, hills, bumps, cubes, walls, spheres, etc. are all applicable types of mesh to add to the track. The specifics of crafting the track will be covered in another guide. Just know that there are proper ways to connect mesh together so the racers do not fall through while traversing from one mesh to another mesh.

Adding a Path

• Allows CPUs to follow the track

• Allows game to track players progress as they navigate the track

• Add a nurbs path or bezier curve

  • The nurbs path is easier to use and outputs very smooth results
  • The steps below apply to both types of curve/path

• Select the path

• Enter Edit mode (Press tab)

• Enable Normals

• Normals shows these arrows which tell us which way is forward.

Thus, the point marked as 1 is the first path point. This must be placed at 0, 0, 0. If it were to be placed at 5, 0, 0, it would have an unexpected offset in-game.

• Move the other points farther forward so that they do not get in the way, and then set the first point at 0, 0, 0.

• If you zoom out, this point should be placed at the very center of the plane. If it is not at the center, press tab to switch to object mode, and move the whole path to 0,0,0. Then switch back to edit mode and place the first path point at 0, 0, 0

• The point should now be at the center (presuming the plane is also centered at 0, 0, 0)

• This next step is incredibly important

• See the green Y in the compass at the top right corner? This shows the positive Y-axis. This is the direction players are facing when they spawn. As such, your path must go in this direction. If it goes in any other direction the CPUs will turn 90 degrees and drive off the track.

Path Point Alignment

• Enter Quad View as this allows moving points from the top-down

• Next enable Magnet mode (shift-tab) and Snap Target set to Face

• Now you can drag using the all-axis mode (the white circle) and the points will snap to the mesh surface.

• Path points are now running in the correct direction

• Next select that last point in the path and press E to extrude (add) another point to the path and place it farther forward.

• Continue adding new path points until you make a complete circle.

• The average track has ~800 path points. There's no specific number required, just enough that the CPUs traverse smoothly.

  • If using the Nurbs Path, do not worry about how many path points. Just that the line connecting the points is smooth.
  • If using the bezier curve, ignore the line that connects the points. Only the points matter!

• Keep adding points until you have a complete circle

• Note that the start/end points do not need to connect to each other or anything like that. Just make them close

• If using the bezier curve you must place at least ten points behind the starting line in a straight line.

  • The NurbsPath requires this as well. However, you don't actually have control over the number of points. So, just make sure there's 16.8 units of space behind the finishline.

Prepare for export

• Drag and drop the mesh and path into the empty so that they are within it. This can be done at the beginning or prior to export, either is fine.

• Hold shift while dragging an object --> place the cursor over the empty, and drop the object

• Note that these objects have been named. This is not required.

• All the objects that need to be exported, must be inside the empty.

Export

• Name the track
• Choose a mods path
• Set scale to 100

Mods Path

• This should be something like desktop/mycoolmods or similar. All your mods will go here.

Name

• This will determine what folders your track will be placed in.

• If you name your track mytrack then it will be placed in desktop/mycoolmods/tracks/mytrack/files_are_placed_here

• Select the empty or any object inside of the empty and click export. If it says Success! then you should see files in the track folder.

Packaging

The track is now ready for packaging and import into the game for your first test!

• Find the desktop/mycoolmods/tracks folder and place a mods.toml file beside the tracks folder. Place the following in it and save:

[mod]
name = "mymod"
version = "1.0.0"

• Highlight the tracks folder and the mods.toml file.

• Right-click --> Add To Archive and turn into a stored zip archive.

  • This file should not be compressed.

• If you wish, you may rename this file to mod_name.o2r or mod_name.zip

If you open the zip folder, you should immediately see the tracks folder and the mods.toml file. Inside tracks should be a folder with the name of your track, and some files inside of that folder.

If it does not contain any files similar to the below then something has gone wrong.

• If all checks out, go to your game executable
• Add a mods folder. Drag and drop your mod into the mods folder.

Game Test

• Launch the game

• Press ESC and enable Debug Mode

• Navigate away and back to the start screen and a debug menu should pop up. Use the left/right arrow keys to switch tracks. Custom tracks are placed at the end of the list.

• Press Launch HM64 Labs to configure your track and place actors.

• Select your track

• Navigate to the Track Properties winow to modify track name and settings

Extra info

• Goto the object menu and select a surface type (asphalt, grass, etc.)

• Stuff like buildings or walls should be separate meshes to not mess with the collision generator.

• The track/pavement should be a separate mesh from the rest of the scene.

• Any number of tracks may be placed in the tracks folder

• After opening your track in the editor for the first time. A scene.json file is created in your tracks data folder.

  • If something ever goes horribly wrong you could manually edit this file or back it up to restore it later.

• If the game crashes when you try to play it. Then there is an issue with track path or mesh.

  • The game generates the collision mesh automatically.

• Lighting changes are not currently saving to the scene file yet.

Materials

• Youtube tutorials discuss how materials work.
• Fast64 often defaults to a CI8 palette texture, always change Format to RGBA-16 bit or RGBA-32 bit The Colour Index (CI8) format can cause issues if not used correctly. It's easy to confuse this as directly below this box it says RGBA 16-bit Example of incorrect texture format:

Example of correct texture format

Export

• Check Ignore Textures Restrictions failing to do so may result in errors