LE-CODE/Distribution Tutorial

From Custom Mario Kart
Jump to: navigation, search

This is the LE-CODE Distribution Tutorial. It explains how to create a custom track distribution based on LE-CODE. As addition, Distribution FAQ explain details, that are not covered here.



Introduction

Slots and filenames

In LE-CODE, 4028 slots (slot range 68..4095 = 0x044..0xfff) are reserved for custom racing tracks. Additionally, slots for 32 original racing tracks and 10 custom battle arenas are reserved. Including special slots, a total of 4096 slots are available. See »LE-CODE Slot Usage« for details.

For each slot, 3 bytes are reserved:

This is a total space of 12 KiB for 4096 slots. In contrast, CT-CODE needs 256 bytes for each used slot. This are 64 KiB for 256 slots. The main reason for the less memory is, that LE-CODE uses generic file name instead of a string list with filenames. The filename of each track, this includes original tracks and special slots, is created by 3 lower case hex digits and the extension .szs:

std_file = sprintf("%03x.szs",slot);
d_file   = sprintf("%03x_d.szs",slot);

If a _d file should be loaded but does not exists, the standard track file without _d is loaded instead. To minimize the space of a distribution ⇒ a _d file should only be added if it and the standard file differ.

This new naming scheme is also used for all 32 standard tracks, 10 arenas and 5 special files. So you have to rename 47 files. Some examples:

# tracks
000.szs = castle_course.szs
008.szs = beginner_course.szs
01f.szs = old_heyho_gba.szs
# arenas
020.szs = venice_battle.szs
029.szs = old_matenro_64.szs
# special files
036.szs = ring_mission.szs
037.szs = winningrun_demo.szs
03a.szs = ending_demo.szs

Special random slots

Some slots have a predefined random functionality. To activate it, put the slot id to the track list of cup. The titles are defined by BMG messages 0x703e–0x7041 (0x7000+slot).

0x03e: All Tracks
Select a racing track by random.
0x03f: Original Tracks
Select one of the original tracks (slots 0–31) by random.
0x040: Custom Tracks
Select one of the custom tracks (all used slots beginning from slot 68 = 0x044) by random.
0x041: New Tracks
Select a track, that is marked by flag NEW, by random. If no track is marked, an internal fallback is used. So it is save to use it, even if no NEW track is specified.

Common files

The track files are placed in directory ./files/Race/Course/*.szs. Some of the track files contain the sub-directory ./Common/ with private versions of different files. These file must be extracted to ./files/Race/Common/%N, where %N is the slot number. See »Distribution FAQ: Common Files« for details.

Track flags

Besides the standard properties property slot and music id, LE-CODE support a third property: flags. Each of the 3 properties is stored as a byte array of 4096 elements (3*4096 = 12288 byte total).

flags is a bit field with following features:

New (Bit 0 = 0x01, symbol LE$F_NEW
This track is marked as NEW. It has only impact to the random selection at slot 0x041.

Random header (Bit 1 = 0x02, symbol LE$F_HEAD)
Begin of a random group. The group ends, if either the Random group flag is not set or the next random group starts.

If such track is selected (directly or by random), one of the following group members is selected by random. If the group header itself is group member too (both bits set), then it is included into the random selection; otherwise it is excluded.

Random group (Bit 2 = 0x04, symbol LE$F_GROUP)
Track is member of the current random group. See Random header above.

Cups

Currently LE-CODE supports 2 battle cups with 5 arenas each and 1024 racing cups with 4 tracks each.

For battle cups and arenas, the standard definition of slots and properties are predefined. The maintainer can exchange the SZS files and arena names, but not the property and music id. This will be changed in the future.

For racing cups, a CT-CODE configuration file is used to define and assign tracks and slots. It optional supports and additional flag member. See section below for details.

Cups have no names. The reason is that the buttons are tied to a BMG ID that doesn't change when scrolling.

BMG

LE-CODE uses BMG messages 7000 to 7fff (by convention, message ids are always hex) for slots 0x000 to 0xfff. Messages 6800 to 6c01 and 8000 to 8fff are used for cup names and cup references. These cup references are only used by mkw-ana to print an additional information about the track selection. The following table lists all messages used by either LE-CODE or mkw-ana:

BMG message ids
Messages Used by Description
6100-610b LE-CODE Messages that appear at race start in private rooms for races 1 to 12. It is an extension for the original messages 582 to 585 for 1 to 4 players. A standard definition looks like:

\z{802,110002}\z{802,110000} - 1st Race (\z{a02,1000000000} players).

610c LE-CODE Reserved for races 13 to 512.

It is planned to implement a generic message with the race number as parameter.

6800-6bff mkw-ana Cup names for 1024 racing cups.
6c00-6c01 mkw-ana Cup names for 2 battle cups.
7000-7fff LE-CODE mkw-ana Track names for slots 0x000-0xfff. See next table for more details.
8000-8fff mkw-ana Track-to-Cup references for slots 0x000-0xfff.

For the game, the range from 7000 to 7fff is most important. Here the track names are defined, that are displayed in menus and before race start. The ids are related to the slot numbers:

BMG message ids for track and arena names
Messages Description
7000-701f 32 names for the original racing tracks.
7020-7029 10 names for the battle arenas (original or custom).
702a-703d Not used for track names.
703e-7041 Used for the 4 special random slots.
7042-7043 Not used for track names.
7044-7fff Names of up to 4028 custom tracks.

Create a BMG track list

Tool wctct of Wiimms SZS Tools can create a BMG list from the definition file (see »Define Slots and Cups«). Therefor use command:

wctct bmg --le-code --long CTFILE.txt >tracks.bmg.txt

Command bmg creates a BMG file and write it to the standard output (stdout). Option --le-code is mandatory to enable LE-CODE support. Option --long is optional and enables additional messages for mkw-ana. CTFILE.txt is the file name of the definition file. The part »>tracks.bmg.txt« redirects the output to file tracks.bmg.txt.

Wiimms SZS Tools and option --le-code

As of version 2.00a of Wiimms SZS Tools, all tools accept global option --le-code (or --lecode) for all commands. It enables the LE-CODE support. But this option is only relevant for some tools and some commands:

  • Tool wlect (the LE-CODE tool) enables LE-CODE support always and independent of option --le-code.
  • Tools wszst, wctct and wbmgt change their behavior if --le-code is set.
  • All other tools ignore this option.

If option --le-code is set, then option --ct-code is enabled too.

Define Slots and Cups

The definition of track and slot assignment is done by a CT-CODE configuration file with extensions. The following tools can use a definition file (with several commands)

wlect COMMAND OPTIONS ARGUMENTS
wctct --lecode COMMAND OPTIONS ARGUMENTS

Example for a Definition File

A definition file looks like this:

#CT-CODE

[RACING-TRACK-LIST]

# enable support for LE-CODE flags
%LE-FLAGS  = 1

# auto insert a Wiimm cup (4 special random slots)
%WIIMM-CUP = 1

# standard setup
N N$SWAP | N$F_WII
 
C "Mushroom" # 1
T 153; T81; 0x00; "T_000"; "SNES Mario Circuit 1"; "14b2b4b4514f5a593418e14b001518cbce1b12b1"
....

General syntax rules:

  • Spaces and Tabs outside of strings are ignored, but used as separators at some places.
  • Comments are started by an has sign »#«.
  • Empty lines are ignored and pure comment lines are ignored.
  • The file is scanned by an parser. So number 17 can be alternatively written as 0x11 (hex), (7+10) (expression), VARNAME (pre-defined variable name) or get17() (function call).

Resources

Section Header

The very first line is always  »#CT-CODE« to identify the file type. After this, names enclosed in square brackets are used top separate sections. For the cup and slot definition only section »[RACING-TRACK-LIST]« is relevant.

First we define some global settings. »%LE-FLAGS = 1« enables the LE-CODE extension. »%WIIMM-CUP = 1« creates automatically a cup with 4 different random selection:

  • Random: All Tracks
  • Random: Original Tracks
  • Random: Custom Tracks
  • Random: New Tracks

Therefore slots 0x03e..0x041 are reserved. Use BMG messages 703e..7041 to define names.

Setting »N N$SWAP | N$F_WII« enables the Nintendo tracks and swap the internal order, so that the visual order is the same as in the original game (Wii cups in first row and retro cups in second row).

The section body defines the cups and tracks using the definitions of above. For LE-CODE, only commands »C«, »T«, »H« and »A« are used.

Cup definition

'C' name_of_cup
Example: C "Mushroom" # any optional comment

This command closes the current cup and fill it with default tracks. Then a new cup is opened. The name is only used for for references and for exported lists. If a cup is full, then a nameless cup is opened automatically.

It is optional, to use flag 'S' before the Track Definition to specify the order that the tracks in the cup go by.

'C' name_of_cup
'S' t1! t2! t3! t4!

This tells wlect that the tracks found in this cup MUST go in this slot order. It is a good option to use when editing the music/track slots of the first 32 tracks, to maintain the natural order when using global option 'N N$NONE'.

Example:
C "Koopa" #any optional comment
S 0x08! 0x01! 0x02! 0x04!

Track definition

When %LE-FLAGS = 1:
  'T' music_id ';' property_id ';' le_flags ';' file_name ';' info ';' id
  Example: T 153; T81; 0x00; "T_000"; "SNES Mario Circuit 1"; "SHA1"
When %LE-FLAGS = 0:
  'T' music_id ';' property_id ';' file_name ';' info ';' id
  Example: T 153; T81; "T_000"; "SNES Mario Circuit 1"; "SHA1"

A track definitions consists of 6 parts:

music_id 
Define a music id for the slot. Usually are all odd numbers between 0x75 (=117) and 0xb3 (=179). Compare this table table. If a number between 0 and 0x29 (=41) is provided, it is interpreted as property slot. In this case, the number is replaced by the standard music id of the property slot. So you can use predefined names like »T53« of »sGV2« instead of a number.
property_id 
The property ID defines the slot, on which the track is run. Here only values between 0 and 31 (or names T11..T84 or LC..nBC) are allowed.
le_flags 
Define the track flags for this track.
file_name 
Define the filename (without the extension .szs) of the related and real existing SZS file. It is used copy/move/link the tracks's SZS file from a source directory into a destination directory. While doing that, the file is renamed automatically to SLOT.szs with correct slot index. Read »Copy, move and/or link track files« for details.
info 
Optional name used by Wiimm's SZS Tools to create BMG files and reference lists. If unused, simply leave the space empty ("";).
id 
Optional identifier for optimization. While creating references, it is assumed, that tracks with equal identifiers are equal. Empty strings and a single "-" means: no identifier available. Equal files can be linked together to save space.

There are 4028 Racing Slots (0x44=68 up to 0xfff=4095) available for custom tracks. In between there is not any reserved slot. So tools wlect and wctct will use them in increasing order. The LE-CODE executor is not interested in the slot order with one exception: Tracks for random selections must be grouped together. So holes and multiple usage of the same track slot is technically allowed.

Hidden track definition

It is possible to add tracks, but to hide them from cups. Therefor the »T« from the track definition is replaced by a »H«:

H 153; T81; 0x00; "FILENAME"; "SNES Mario Circuit 1"; "SHA1"

The usual case for hidden files are random selections. Example:

T 153; T81; 0x02; "FILENAME1"; "Menu Name"; "SHA1_1"
H 153; T81; 0x04; "FILENAME1"; "Track Name 1"; "SHA1_1"
H 155; T72; 0x04; "FILENAME2"; "Track Name Two"; "SHA1_2"

With that definition, »Menu Name« is displayed for the track selection and the other both tracks are hidden. If the track is selected by the lottery or user, one of »Track Name 1« or »Track Name Two« is selected in a second step by random. From this point on, the real track name is displayed and loaded.

You can also change the probabilities of the random selection by repeating track entries:

T 153; T81; 0x02; "FILENAME1"; "Menu Name"; "SHA1_1"
H 153; T81; 0x04; "FILENAME1"; "Track Name 1"; "SHA1_1"
H 155; T72; 0x04; "FILENAME2"; "Track Name Two"; "SHA1_2"
H 155; T72; 0x04; "FILENAME2"; "Track Name Two"; "SHA1_2"
H 155; T72; 0x04; "FILENAME2"; "Track Name Two"; "SHA1_2"

Here the probability of »Track Name 1« is 25% and of »Track Name Two« 75%.

Arena definition

The 10 battle arenas are always loaded from slots 32 to 41 (file names from 020.szs to 029.szs). The slot features are hard coded, but can be modified by editing the file minigame.kmg. It is also possible to provide a private minigame.kmg with the track file. See Track FAQ for details.

The arena names are loaded from BMG. Here message ids 7020 to 7029 (hex values) are used. Compare section »BMG« of this article.

Copy, move and/or link track files

Command wlect PATCH supports an automated collecting and renaming of the track files. Therefor options --track-dir, --copy-tracks, --move-tracks, --move1-tracks and --link-tracks define the operation.

Option --track-dir DIRECTORY
With this option you define a destination directory, where all track files (type SZS) are copied, moved or linked to. Existing files with the same name are removed before without any notice. The usual destination directory is files/Race/Course/. The files are automatically renamed to 123.szs (and 123_d.szs), where »123« are the 3 hex digits representing the slot index.

Each filename of the definition file (option --def-lecode) is searched in the directories defined by the other 4 options in the order of the definition. Each option can be used multiple times and in any order to define any number of source directories. The option name itself defines only, how to copy the source file. After coping and renaming to 123.szs the main file, a _d file is searched too, and copied and renamed if found.

Option --copy-tracks DIRECTORY
Files found in this directory are copied to the destination directory. This is the recommended option, if you don't understand the concepts and the advantages of moving and linking files.
Option --move-tracks DIRECTORY
Files found in this directory are moved to the destination directory. If moving fails, the file is copied and the source removed.
Option --move1-tracks DIRECTORY
Files found in this directory are moved to the destination directory, but only if a file has not more than one hard link (no other usage). This guarantees an unique version of the file. If the file has more hard links or moving fails, the file is copied and the source removed.
Option --link-tracks DIRECTORY
Files found in this directory are hard linked to the destination directory. If linking fails, the file is copied.

It is possible, that the destination directory defined by option --track-dir is the same as one of the source directories. Here usually --move-tracks is the best choice to define it — the files are simply renamed.

Example for an usual command line (1 line only!):

wlect patch lecode-PAL.bin  -od new/lecode-PAL.bin  --le-define config.txt  --lpar lecode-param.txt
    --track-dir DESTDIR  --copy-tracks SRCDIR1  --copy-tracks SRCDIR2

Read  »LPAR (File Format)« for details about option --lpar.

Modified files

main.dol and lecode-*.bin

File main.dol must be patched to load the lecode-*.bin file. Therefor use command

wstrt patch sys/main.dol --clean-dol --add-lecode

Option --clean-dol is optional and tries to remove old patches from main.dol and to reset it to its original state. Anyway, best is to use an original main.dol as base. Option --add-lecode adds a special LE-CODE starter to main.dol. This starter code is region dependent, but always the same since first LE-CODE release. You can combine the command with other options, e.g. for patching a login region or for adding cheats.

If so patched, the game will try to load file files/rel/lecode-REGION.bin (same directory as StaticR.rel) after game start, where keyword »REGION« is one of »PAL«, »USA«, »JAP« or »KOR« (upper case letters). This lecode binary file contains the code to modify the game and the settings like cup and track assignments. So it must be patched with the game data.

You can copy the settings from one lecode binary to another one by …

wlect patch lecode-patch.bin --le-define lecode-source.bin --overwrite

… to overwrite the setting of lecode-patch.bin. Alternatively you can use …

wlect patch lecode-orig.bin --le-define lecode-source.bin --overwrite --dest lecode-new.bin

… to create a new copy of the lecode binary. Both commands work across regions and across lecode releases.

The commands of above with short options:

wlect patch lecode-patch.bin --ledef lecode-source.bin -o
wlect patch lecode-orig.bin  --ledef lecode-source.bin -od lecode-new.bin

LE-CODE Parameters and Chat Messages

LE-CODE supports general parameters and special feature for chat messages in private rooms. Both are defined by a special configuration file. See »LPAR (File Format)« for details.

Cup Icons

First, create a TPL with cup icons. Each icon is of size 128*128 pixels. The cup icons are ordered vertically, so that the final image size is 128*N, where N:=num_of_icons*128. You can create a PNG file and convert it to a TPL with command:

wimgt copy "MY.png" -rqo "ct_icons.tpl" -x tpl.CMPR

Option -x tpl.CMPR forces the creation of a TPL file using image format CMPR. CT-CODE uses format RGB5A3. Using CMPR instead reduces the needed space to 25%.

The TPL file ct_icons.tpl must be stored as button/timg/ct_icons.tpl and as control/timg/ct_icons.tpl in the files Channel.szs, MenuMulti.szs and MenuSingle.szs. For Korean patch the files Channel_R.szs, MenuMulti_R.szs and MenuSingle_R.szs instead. You will find all files in directory ./files/Scene/UI/.

Cup Videos

The original game has 8 videos, that present the current cup, and 1 more video for the cup selection. All videos show scenes from the original tracks. It is best to replace all 9 videos by an empty video. Download the following video and copy it to all files. To save space, they can be linked instead copied.

  • Download ZIP file video.zip and extract it.

Track selection menu

You have to replace some sub-files of SZS files in directory .../Scene/UI/

  • Download ZIP file menu-files.zip and extract it.
  • Extract files Award.szs, Channel.szs, Event.szs, Globe.szs, MenuMulti.szs, MenuOther.szs, MenuSingle.szs, Present.szs, Race.szs and Title.szs.
    • Korean: Modify »<FILE>_R.szs« instead of »<FILE>.szs«.
  • Replace the following sub-files, if they exists, by the files of the ZIP file:
    • button/blyt/cup_icon_64x64_common.brlyt
    • button/ctrl/Back.brctr
    • button/ctrl/CupSelectCup.brctr
    • control/blyt/cup_icon_64x64_common.brlyt
    • control/ctrl/CourseSelectCup.brctr
    • demo/blyt/course_name.brlyt
    • demo/timg/tt_hatena_64x64.tpl
Recent updates
  • On 2020-02-08 the file tt_hatena_64x64.tpl was added to hide an unwanted question mark in the offline Grand Prix mode if playing custom cups. It belongs only Race.szs.

Debugging

Verify the lecode file

Command wlect dump LECODE_FILE dumps the settings of a lecode file as human readable text file. For terminal output, the dump is colored. To force colors, use cdump instead of dump.

Dump example (MKW-Fun 2019-06)


If adding option --long (short -l), a cup and slot reference is added:

Dump example if using option --long


If adding option --verbose (short -v, can be combined with --long), a slot usage map is added:

Dump example if using option --verbose


Downloads

Download Directory 
Base directory for the following downloads.
LE-CODE binary files 
Directory with current LE-CODE files (binary data + executor code) for regions PAL, USA, Japan and Korea. Use tool wlect of Wiimms SZS Tools to list and define settings.
Menu Files 
ZIP files to patch menus in files Award.szs, Channel.szs, Event.szs, Globe.szs, MenuMulti.szs, MenuOther.szs, MenuSingle.szs, Present.szs, Race.szs and Title.szs of directory .../Scene/UI/
Details
Empty cup video 
ZIP file with an empty video to overwrite all videos of .../files/thp/course/Details