LE-CODE/Distribution Tutorial/CT-DEF

New Definition Format

As of v2.28a.beta of the SZS Tools, a new file format (LE-DEF) will be supported as an alternative. It has a simpler syntax and will be added with future LE-CODE extensions.

This article describes the use of the old file format CT-DEF, which is still supported.

LE-CODE

LE-CODE & related file formats

Extended presence flags

Related Categories

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


[SETUP-ARENA]
# Assign new property slot and optionally a new music id to an arena slot
# Syntax: SLOT NEW_PROPERTY_SLOT [NEW_MUSIC_ID]
A11 A21
A12 A22 T33

General syntax rules:

Spaces and Tabs outside of strings are ignored, but used as separators at some places.
Comments are started by a hash sign »#«. Comments are treated as a single space.
Empty lines and pure comment lines are ignored.
The file is scanned by a 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. 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. To do this, replace the »T« from the track definition with 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.

Change property slots and music ids of arenas

Usually LE-CODE uses the standard property slot and music id for arenas. As of SZS Tools v2.27a a section named [SETUP-ARENA] is scanned to change the defaults:

Example:

[SETUP-ARENA]
# Assign new property slot and optionally a new music id to an arena slot
# Syntax: SLOT NEW_PROPERTY_SLOT [NEW_MUSIC_ID]
A11 A21
A12 A22 T33

Here the properties for arenas 1.1 and 1.2 are changed (first column). The arenas use the properties of slots 2.1 and 2.2 (second column). Additionally, the music id of arena 1.2 is changed to the music of racing track 3.3 (Maple Treeway).

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.