LE-CODE/Distribution Tutorial

LE-CODE

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

• Introduction
• Technical Description
• Track Tutorial
• Software Overview
• Implementation Hints

Related Categories

• LE-CODE
• Extended Presence Flags

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, 8124 slots (slot range 68..8191 = 0x44..0x1fff) 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 8192 slots are available. See »LE-CODE Slot Usage« for details.

For each slot, 4 bytes are reserved:

• Property index
• Music index
• Flags (new marker, random group header, random group member, ...)

This is a total space of 32 KiB for 8192 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 or 4 lower case hex digits and the extension .szs:

 # If LPAR setting SLOT-04X is 0 or not defined:
 std_file = sprintf("%03x.szs",slot);
 d_file   = sprintf("%03x_d.szs",slot);

 # If LPAR setting SLOT-04X is 1:
 std_file = sprintf("%04x.szs",slot);
 d_file   = sprintf("%04x_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

LE-CODE since 2024-02 supports 8192 tracks

Since 2024-02 LE-CODE (build 39) supports 8192 tracks. So the slot range for custom tracks is 68..8191 = 0x044..0x1fff. Slots ≥0x1000 need 4 hex-digits. LE-CODE support 2 variants:

1. We'll leave the calculating of the track names at %03x.szs. Slots ≥0x1000 then automatically become 4 digits. So we have a mix of 3 and 4 hex-digit names, but only if someone uses a slot ≥4096. Advantage: No change for the distribution creators. Disadvantage: No clean sorting.
2. We replace %03x.szs with %04x.szs. This means that the distribution creators have to adapt their scripts. Advantage: Uniform 4-digit numbering. Disadvantage: For every used slot <4096, one more character in the FST is needed as long as no LTA is used.

The LPAR setting SLOT-04X determines which of the two variants is used in the LE-CODE. Wiimms SZS Tools v41a or higher is required to manage slots ≥4096.

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.

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 LE-CODE:

BMG message ids

Messages	Description
6100-610b	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-62ff	Reserved for races 13 to 512. It is planned to implement a generic message with the race number as parameter.
643d-6441	Used for the 5 special random slots if a battle arena is used. So different texts for racing and battle tracks can be defined.
7000-8fff	Track names for slots 0x0000-0x1fff. See next table for more details.
9000-afff	Reserved for a further 8192 custom track names that may be added in the future.

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.
703d-7041	Used for the 5 special random slots if a racing track is used.
643d-6441	Used for the 5 special random slots if a battle arena is used. So different texts for racing and battle tracks can be defined.
7042-7043	Not used for track names.
7044-7fff	Names of up to 4028 custom tracks.
8000-8fff	Support for additional 4096 custom track names since LE-CODE build 39.
9000-afff	Reserved for a further 8192 custom track names that may be added in the future.

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.

mkw-ana

The current tool mkw-ana supports only 4096 tracks. So it prints invalid infos if using a slot ≥4094. This will be fixed soon. The folowing tables show the BMG usage for the old mkw-ana.

BMG message ids

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

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. The creator of a distribution now has the choice between the old and the new description languages:

• Old description language (file format CT-DEF).
• New description language (file format LE-DEF). This new file format is recommended!

Patch .../Scene/UI/*.szs

The files from the directory .../Scene/UI/ must be patched to adjust their functionality for LE-CODE. The general command it either

wszst patch options "./Scene/UI/*.szs"

to patch the files in place, or

wszst patch options "./Scene/UI/*.szs" -od ./path/to/output/

to patch the files and stores them into directory ./path/to/output/. options is a list of options to define the type of patching. A full command with all options looks like:

wszst patch --le-menu --9laps --cup-icons icons.tpl "./Scene/UI/*.szs" -od ./path/to/output/

At least version v2.36a of Wiimms SZS Tools is required for the modifications described here.

Track selection menu: --le-menu

Option --le-menu replaces different sub-files to change the track selection menu. It replaces the following files:

• 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

ZIP file menu-files.zip contains all updates. You can download it for investigation. The SZS Tools use internal copies of them.

Support for 9 laps: --9laps

Option --9laps implements Lap Texture Fix v1.03.

Cup Icons: --cup-icons

Options --cup-icons IMAGE-FILE --links adds the image file (width 128 pixel, height N*128 pixel) to places where LE-CODE expect the image. Before storing, the image is converted to file format TPL and image format CMPR. Option --links ensures that the image is installed only once although it is required under 2 path names. This saves storage space.

In detail the image is stored as button/timg/ct_icons.tpl and as control/timg/ct_icons.tpl to files Channel.szs, MenuMulti.szs and MenuSingle.szs.

Creating MKW-Fun like cup icons

Command wlect distrib supports the instruction cup-icons=OPTIONS=FILE to create MKW-Fun like icons. All you need is the definition file (CT-DEF or LE-DEF) with correct names:

wlect dis DEFINITION.txt cup-icons=swapped,5,space=icons.tpl

Details will be explained here later. For the moment see the Built-in Help.

Patch other files

main.dol and lecode-*.bin

File main.dol must be patched to load the lecode-*.bin file. Therefore 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 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.

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)

# wlect dump patch-dir/files/rel/lecode-PAL.bin

DUMP LE-BIN:patch-dir/files/rel/lecode-PAL.bin
  LE-CODE binary, valid=FVKfvk, file size: 11520/hex = 70944

    File header:
      Magic:             LECT
      Version:           4
      Build number:      8
      Base address:      808dd400/hex
      Entry point:       808dd478/hex
      Total size:           11520/hex = 70944
      Offset param:            40/hex
      Region code:       P  (PAL)
      Debug flag:        R  (Release)
      LE version/phase:  2
      Timestamp:         2019-05-31 13:35:39

    Parameters:
      Magic:             LPAR
      Version:           1
      Param size:        35/hex = 53
      Engine chances:    8 + 62 + 30 = 100 (100cc,150cc,mirror)
      200cc:             0 (disabled)
      Perform. monitor:  0 (disabled)

    Sections (offset,n/max):
      Cup parameters:     5380/hex
      Racing track cups:  5390/hex,   92 / 1024
      Battle arena cups:  9390/hex,    2 /    2
      Course parameters:  93c0/hex
      Property list:      93d0/hex,  680 / 4096
      Music list:         a3d0/hex,  680 / 4096
      Flags list:         b3d0/hex,  680 / 4096
      End of data:        c3d0/hex
      End of file:       11520/hex

    Cup and course parameters (n/max):
      Cup magic:         CUP2
      Racing track cups:   92 / 1024
      Battle arena cups:    2 /    2
      Course magic:      CRS2
      Total track slots:  680 / 4096
      Used racing slots:  644 /  644
      Used battle slots:   10 /   10

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

Dump example if using option --long

# wlect dump patch-dir/files/rel/lecode-PAL.bin --long
....

    2 cups with battle tracks (id[prop,music,new+head+group+alias]):
      Cup  0:  21[A11,A11,----]   20[A12,A12,----]   23[A13,A13,----]   22[A14,A14,----]   24[A15,A15,----]
      Cup  1:  27[A21,A21,----]   28[A22,A22,----]   29[A23,A23,----]   25[A24,A24,----]   26[A25,A25,----]

    92 cups with racing tracks (id[prop,music,new+head+group+alias]):
      Cup  0:   8[T11,T21,----]    1[T12,T12,----]    2[T13,T13,----]    4[T14,T14,----]
      Cup  1:  10[T51,T51,----]   14[T52,T52,----]   19[T53,T53,----]   1a[T54,T54,----]
....
      Cup 21: 184[T71,T72,----]  185[T43,T43,N---]  186[T72,T72,----]  187[T72,T72,----]
      Cup 22: 188[T72,T72,----]  189[T72,T72,-H--]  18c[T43,T43,----]  18d[T43,T43,----]
....

    279 track slots reserved for random groups (id[prop,music,new+head+group+alias]):
      Slot   69/dec :  45[T43,T43,--G-]
      Slot   70/dec :  46[T32,T32,--G-]
....

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

Dump example if using option --verbose

# wlect dump patch-dir/files/rel/lecode-PAL.bin --verbose
....

    Slot usage map for 680 slots
      A=Arena, r=Random Arena, a=Hidden Arena,  W=Wiimm Cup (random), >=Alias,
      T=Track, R=Random Track, t=Hidden Track,  n=Network, s=Special, -=unused.

        0: TTTTTTTT TTTTTTTT TTTTTTTT TTTTTTTT AAAAAAAA AA------ ------ss sss---WW
       40: WWsnRttt tttttttt tRtttttR ttttttRt tttttttt ttttRttt tttttttt tttttttR
       80: tttttttt ttRttttt tttttttt tRtttttt tttttttt tRtttttt tttttttt ttRttttt
       c0: ttttRttt tttttttt tRtttttt tttttttt ttRttttt tttRtttt tttttttt tttttttt
      100: ttRttttt tttttttt tttttttt tttRtttt tttttttt tttttttt tttttttt tRtttttt
      140: tttttttR tttttttt ttttRttt tttttRtt ttttttTT TTTTTTTT TTTTTRtt TTTTTTTT
      180: TTTTTTTT TRttTTTT TTTTTTTT TTTTTTTT TTTTTTTT TTTTTTTT TTTTTTTT TTTTTTTT
      1c0: TTTTTTTT TTTTTTTT TTTRttTT TTTTTTTT TTTTTTTT TTTTTTTT TTTTTTTT TTTTTTTT
      200: TRttTTTT TTTTTTTT TTRttTTT TTTTTTTT TTTTTTTT TTTTTTTT TTTTTTTT TTTTTTTT
      240: TTTTTTTT TTTTTTTT TTTTTTTT TTTTTTTT TTTTTTTT TTTTTTTT TTTTTTTT TTTTTTTT
      280: TTTTTTTT TTTTTTTT TTTTTTTT TTTTTTTT TTTTTTTT

The dump of above with colors:

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