How to create an LE-CODE Distribution

Introduction

LE-CODE is a code extension for Mario Kart Wii, written by Leseratte and Wiimm. It is most commonly used to create Custom Track Distributions, but also comes with a variety of additional features including:

• Increased Track slots
• Various Bugfixes
• Speedometer
• Debug Features
• Additional track features including LEX support
• Extended presence flags
• Working Battle Mode (unlike CT-CODE)
• Additional code support

While LE-CODE is a useful and extensive code extension, the documentation surrounding it and the creation of a distribution using it, is lacking in clarity, and is generally unorganised. This page is to serve a quick step-by-step guide to the creation of an LE-CODE distribution primarily targeting *nix operating systems and the command line.

Considerations

This tutorial covers the basics of creating an LE-CODE distribution, however may not the correct method of going about things. Instead it is simply the method that I've found to be the quickest and most straight-forward. Windows users should be able to follow this tutorial to an extent with some adaptation, but it is likely easier to follow with a suitable unix-like environment for Windows (such as msys2) or using the Windows Subsystem for Linux.

Prerequisite files

• A copy of Mario Kart Wii. (in ISO,WBFS,WIA or WDF format)

This should be obtained by dumping a copy of the game that you own using a tool such as CleanRip (also available at OSC).
The region does not matter, assuming you wish to target only the region of your disc.

Preparation

Step 1. Acquiring tools

There are two tool-sets that will be used extensively in this tutorial:

• Wiimm's ISO Tools
• Wiimm's SZS Tools

To obtain them, either install them via your package manager, or download the binaries for your system from the website. Each archive contains a simple install script that must be run as root. Either way, you'll primarily be using the tools:

• WIT, used to extract the MKW iso
• WSZST, used to manipulate (including extracting) U8 (SZS) archives, as well as to convert WU8 (wbz) archives.
• WLECT, the LE-CODE tool, used for everything to do with LE-CODE distribution creation.

One may also wish to download the Dolphin Emulator for testing purposes.

Step 2. Preparing tools, and environment

There's going to be lots of files at play here, so it's recommended to keep things organised. Therefore create a directory somewhere sensible that will contain your distribution while it is being prepared. This shall be referred to as the base directory.

Start out by downloading the "Track Prefixes" and "SHA-1 Reference" files from here, using the "Download LIST" button. Place both prefix.txt and sha1-reference.txt in your base directory.

Next, your MKW iso image should be extracted. (preferably this should be done at a directory level higher than your base directory, as it will be a useful reference for any future distributions one wished to make).
This is done with: wit extract [mkwii.iso]

Whereby:

  extract performs an extract operation on the file
  [mkwii.iso] is a placeholder for the filename of your copy of MKW

Optionally a directory can also be provided as an output destination.

Creating an Auto-add Library

If one wishes to utilise WU8 (.wbz) archives, then an auto-add library must be generated using WSZST. This consists of common subfiles used in tracks by Nintendo, and is created using the "/Race/Course" directory from MKW.
To create the Auto-add library: wszst autoadd [./path_to/Race/Course/]

Whereby:

  autoadd manages the autoadd library
  [./path_to/Race/Course/] is the path to /Race/Course. It is likely to begin with /DATA/files.

Once this is complete use wszst autoadd -v to verify the library, and ensure that "LIST OF MISSED FILES" is blank.

Step 3. Obtaining tracks

The best way to browse for tracks is to use the Custom Mario Kart Wiiki. Find some tracks to your liking, and then download them from either the old CT-Archive, or the new SZS Library. Be aware that the old archive does contain more information, however is no longer updated as of around June 2024. This will provide one with a set of named and/or numbered .wbz files respectively. It is recommended to use these archives as the downloads are smaller, there are no dead links involved, working tracks will actually work (with clean and normalised archives), and a standardised naming system is used. It is worth noting that Wiimm's archive has a strict limit of downloads per hour per IP.

In order to create less work later, any numbered tracks should be renamed with at least the name of the track. (See #Automated Track Naming)

Step 4. Creating a LE-DEF file

A LE-DEF file is an LE-CODE definition file, it defines all the tracks and battle arenas including names, slots etc; as well as the cups they belong to. This can be generated automatically with wlect, and then edited if desired. To generate a starting file:
wlect dis ledef=temp.ledef

Whereby:

   dis is shorthand for distribution, the distrib management command
   ledef= tells wlect to output a ledef file 

The resulting file is well-commented, and can be easily edited via any good text editor. Do read and review the options provided within.

Next, the LE-DEF file must be filled with the downloaded tracks, this can be also be done with:
wlect dis temp.ledef prefix.txt "$TRACKDIR/*.wbz" ledef=dist.ledef

Whereby:

  temp.ledef is our starter file from earlier
  prefix.txt contains a list of track prefixes
  "$TRACKDIR/*.wbz" refers to a directory containing WU8 (.wbz) archives

This will produce a new LE-DEF file containing all the tracks, placed automagically into cups. This should be verified, and can edited to correct filenames and/or track/music slots. Be aware that certain tracks will not work on certain slots. Both archives have information on this. Most commonly tracks are incompatible with slot 4.2 (Moonview Highway), 6.1 (N64 Sherbet Land) or 6.2 (GBA Shy Guy Beach). The music slot (ID) only defines music, and does not have to match with the regular slot.

Step 5. SZS conversion and movement

In order to be playable in Mario Kart Wii, tracks must be converted from WU8 (.wbz) format, to U8 (.szs) format. WSZST includes this functionality, and all tracks can simply be converted using:
wszst normalize "*.wbz" --szs --overwrite --dest "%N.szs"

Whereby:

  normalize does this
  "*.wbz" selects all .wbz files
  --szs ensures .szs output and conversion
  --dest makes the program output with the correct file extension

This will produce .szs copies of all your downloaded tracks.

Next, tracks must renamed to the their slot number in hexadecimal, instead of doing this manually, the distribution command of WLECT allows the automatic copying and renaming of tracks to a directory. At the same time, vanilla tracks from the game must be copied and named correctly. Before hand, create a new directory for this such as "Course" (this will match the name of the folder on disc).
And then run: wlect dis dist.ledef --track-dir "$DESTDIR" --copy-tracks "$SRCDIR1" --copy-tracks "$SRCDIR2" --move-tracks "$DESTDIR" tracks=log

Whereby:

  $DESTDIR is your preferred output directory
  $SRCDIR1 is the directory containing .szs files of your downloaded tracks
  $SRCDIR2 is the directory containing the original track files (the same as you used for the Auto-add library

Files will created in DESTDIR with 00A.szs or 043.szs for example, matching the slot numbers contained in the LE-DEF file. An additional step is to extract the unique common files from tracks for LE-CODE to load. Firstly, create a new directory such as "Common".
Then run: wszst xcommon "$COURSEDIR/*.szs" -qiod "$COMMONDIR/%N/"

Whereby:

  xcommon This extracts files under the common directory
  $COURSEDIR is the directory containing renamed .szs files
  $COMMONDIR is the newly created Common directory

Step 6. LPAR creation

An LPAR file is effectively an LE-CODE settings file, and defines basic parameters. A sample lpar file can be created with:
wlect create lpar > lpar.txt

This can be edited via any good text editor. Some example settings you may wish to edit:

• SPEEDOMETER, sets the type of speedometer used
• DEBUG, enables the debug monitor
• DRAG-BLUE-SHELL, blue-shell dragging (like a banana or green shell)

The file itself by default is well commented, with descriptions for each settings.

Step 7. More file creation

Some more files need to be created before final patching and preparation can begin.

LE-CODE Binaries

LE-CODE itself comes in the form of a binary blob that is loaded into the game via a patched main executable. This can be downloaded, and then patched, however WSZST includes a copy, meaning a single command can be used to generate a suitable binary.
Run: wlect dis dist.ledef lpar.txt [email protected]

This will create LE-CODE binaries for each region of the game.

Cup Icons

As part of this tutorial, automatically generated cup icons will be used. Custom cup icons can be created manually, and packed into a .tpl file if desired. Alternatively, a .tpl file can be automatically generated, and the images inside replaced. Either way, to generate a basic set of cup icons, run:
wlect dis dist.ledef cup-icons=swapped,5,space=icons.tpl

Whereby:

  swapped uses the original 8 cup icons
  5 defines the maximum characters for icon text
  space finishes the name at first space

common.bmg

BMG files contains strings that are assigned IDs for use in game. In order for the modded tracks to actually have names, they must be inserted into a file known as "common.bmg", a file (as the name implies) common to most UI files in the game. To create a patched common.bmg file:
wlect dis dist.ledef bmg=-, then verify the output, before running: wlect dis dist.ledef bmg=common.bmg to actually create the file.

Step 8. UI file patching

In order for LE-CODE to work correctly, menu and UI files must be patched.

Extra Info

Further Reading

• Slot Usage of MKW, and various code mods
• Slot information, including unique slot features

Automated Track Naming

Unfortunately, SZS Library uses system whereby .wbz downloads are simply named based on their track ID, this makes it nigh impossible to identify a track based on its filename. A partial automated workaround is possible using Wiimm's CT archive as a resource for names. Using my wcta_browser, the ID's can be searched, and a proper filename returned.

Example script:
TRACKDIR=""

for i in "$TRACKDIR"/*.wbz;
do i=${i##*/};
mv "$TRACKDIR"/"$i" "$TRACKDIR/$(python wcta_browser.py -i "${i%.wbz}" -p title).wbz";
done

Whereby:

   TRACKDIR refers to a directory containing tracks in the WU8 (.wbz) format

Do backup any files just in case, and be aware that any track not in the archive (ie. newer than June 2024) will be renamed to an error message.

   TODO:
  finish the damn thing
  add images
  add alternatives
  proper language support
  custom chars
  author credits