LE-CODE/Distribution Tutorial

From Custom Mario Kart
Jump to: navigation, search
Under Construction
This article is not finished. Help improve it by adding accurate information or correcting grammar and spelling.
Lecode-circ-160x160.png

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.

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.

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.

Messages Used by Description
6800-6bff mkw-ana Cup names for 1024 racing cups.
6c00-6c01 mkw-ana Cup names for 2 battle cups.
8000-8fff mkw-ana & LE-CODE Track names for slots 0x000-0xfff.
9000-9fff mkw-ana Track-to-Cup references for slots 0x000-0xfff.

???

  • wctct --le-code --long bmg CTFILE >tracks.bmg.txt
    • Option --le-code is mandatory to enable LE-CODE support.
    • Option --long enables the additional messages for mkw-ana.

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 Tabe outside of strings are ignored. By used somtimes as separators.
  • 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 nsme) 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.

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 uses the filename to copy/move/link the source files ti 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. 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 the 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

???

Arena definition

???

»«

Resources:

Modified files

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

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.