Difference between revisions of "LE-CODE/Distribution Tutorial"

Revision as of 14:58, 20 February 2020

Under Construction

This article is not finished. Help improve it by adding accurate information or correcting grammar and spelling.

LE-CODE

LE-CODE & related file formats

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 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.

Special random slots

Some slots have a predefined random functionality. To activated 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.

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.

BMG message ids
Messages	Used by	Description
`6800-6bff`	mkw-ana	Cup names for 1024 racing cups.
`6c00-6c01`	mkw-ana	Cup names for 2 battle cups.
`7000-7fff`	mkw-ana & LE-CODE	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 the option.

Setting option --le-code implies option --ct-code.

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).

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) searched in game. (This MUST match the actual track's filename!) Options --track-dir, --copy-tracks, --move-tracks, --move1-tracks and --link-tracks use the filenames to copy/move/link the source files to the slot dependent file name.

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

???

»«

Resources:

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 pat lecode-patch.bin --ledef lecode-source.bin -o
wlect pat lecode-orig.bin  --ledef lecode-source.bin -od lecode-new.bin

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/.

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.

Hardlinks

???

Creating an ISO image with wit

???

Creating a Riivolution setup (XML files)

???

Videos

???

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

Download

Download Directory: Base directory for the following downloads.
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
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.

@@ Line 21: / Line 21: @@
 If a ''_d file'' should be loaded but does not exists, the standard track file without <tt>_d</tt> is loaded instead. To minimize the space of a distribution ⇒ a ''_d file'' should only be added if it and the standard file differ.
-=== Special random slots ===
+=== <span id=random>Special random slots</span> ===
 Some slots have a predefined random functionality. To activated it, put the slot id to the track list of [[#cup|cup]]. The titles are defined by [[#bmg|BMG messages]] 0x703e–0x7041 (<tt>0x7000+slot</tt>).
@@ Line 33: / Line 33: @@
 <dd>Select one of the custom tracks (all used slots beginning from slot 68 = 0x044) by random.</dd>
 <dt id=slot-041>0x041: New Tracks</dt>
-<dd>Select a track, that is marked by [[#flag-new|flag NEW]], by random. If no track is marked, an internal fallback is used.<dd>
+<dd>Select a track, that is marked by [[#flag-new|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.<dd>
 </dl>