LE-CODE/Distribution Tutorial
- LE-CODE & related file formats
- LE-CODE: General description
- LE-CODE: History
- LE-CODE: FAQ for track creators
- LE-CODE: Distribution Tutorial
- LE-CODE: Definition file for distributions
- LE-CODE: FAQ for distribution creators
- LE-CODE: Item Cheat
- LE-CODE: Controllers & Buttons
- LE-CODE: Slot usage
- LE-CODE: Exception Handler
- LPAR: File format for parameters
- LEX: File format and definitions
- LTA: LE-CODE Track Archive
- LFL: LE-CODE File List
- Wiimm's Test Tracks
- Extended presence flags
- Related Categories
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:
- Property index
- Music index
- Flags (new marker, random group header, random group member)
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 names instead of a string list with file names. The file name 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, the bit numbers are or'ed:
Example: LE$F_HEAD|LE$F_NEW (value 3) means: Begin of a random group (value 2) and marked as new track (value 1).
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:
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:
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«). Therefore 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
In May 2022, Wiimm started to develop a new internal data model for his SZS Tools, which contains all relevant data of a LE-CODE distribution. This development is still ongoing. The creator of a distribution now has the choice between the old and the new description language.
- Old description language (file format CT-DEF).
- Old description language (file format LE-DEF). As it is still under development, the new format and associated commands should be considered experimental.
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. So …
wlect patch lecode-PAL.bin --le-define lecode-USA.bin --overwrite
… can be used to copy the settings from the USA to the PAL version.
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 wlect patch lecode-PAL.bin --ledef lecode-USA.bin -o
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.
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