LPAR (File Format)

From Custom Mario Kart
(Redirected from LPAR)
Jump to navigation Jump to search

LPAR (LE-CODE Parameters) is a text file format defined by Wiimm. It is used to define parameters for LE-CODE.


Introduction

A LE-CODE binary file (e.g. lecode-PAL.bin) contains a binary section with magic »LPAR«. It defines how the LE-CODE executor works. Up to Wiimms SZS Tools v2.14a, LE-CODE parameters had to be set via options while patching. As of v2.15a, there is also the possibility to define the parameters by a LPAR file. So a LPAR file is a text version of the binary LPAR section. Options are still accepted and have higher priority than a LPAR file.

This whole article is based on Wiimms SZS Tools v2.16a or later.

Using a LPAR file is recommended, because most parameters can only be set by a LPAR file. A typical command looks like this:

wlect patch lecode-PAL.bin --lpar lpar.txt  ....

Here and in this whole article the filename lpar.txt is used for the LPAR file, but any other filenames like lecode-param.txt are possible too. Read section »Use a LPAR file« for more details.

A LPAR file is a text file that always begins with the magic »#LE-LPAR« as identification. It is divided into sections. At the moment 6 sections are supported, one for General Parameters, one for Chat Messages and four for Debug Settings. So a typical LPAR file looks like this:

#LE-LPAR

[LECODE-PARAMETERS]

DEVELOPER-MODES	= 0
DEV-MODE1	= 0
DEV-MODE2	= 0
DEV-MODE3	= 0

LIMIT-MODE      = LE$AUTOMATIC

CHEAT-MODE	= 0
ENGINE		= 10,60,30
ENABLE-200CC	= 0
PERF-MONITOR	= 0
CUSTOM-TT	= 0
XPFLAGS		= 1
BLOCK-TRACK	= 0
SPEEDOMETER	= SPEEDO$OFF
DEBUG		= DEBUG$OFF
ITEM-CHEAT	= 0
DRAG-BLUE-SHELL	= 1
THCLOUD-TIME	= 300 # 5.00s
BT-WORLDWIDE	= 0 # disabled
VS-WORLDWIDE	= 0 # disabled
BT-TEXTURES	= LE$DISABLE
VS-TEXTURES	= LE$ENABLE | LE$ALTERABLE | LE$EXCLUDE
BLOCK-TEXTURES	= 1
STATICR-POINTS	= 0
DEF-ONLINE-SEC	= 340  
MIN-ONLINE-SEC	= 340
MAX-ONLINE-SEC	= 525
CUP-ICON-SIZE	= 128
SLOT-04X	= 0

[CHAT-MESSAGE-MODES]
# ....

[DEBUG-1]
# ....

Section »Create a LPAR file« explains how to create and modify a LPAR file.

Section [LECODE-PARAMETERS]

This section defines general LE-CODE parameters. The corresponding options have a higher priority. Remove or comment-out a parameter if its value should not be changed. All values will be limited to the allowed ranges.

As of SZS Tools v2.41a, all LPAR settings of this section can be queried via a variable called LPAR$xxx. xxx is the name of the parameter, with minus signs (-) replaced by underscores (_). For example, you can use VS-WORLDWIDE = LPAR$BT_WORLDWIDE to apply the battle setting for versus.

General Parameters
Parameter,
Option
Value Description
DEVELOPER-MODES int This parameter is only intended for LE-CODE developers to support development. It disables (0, the default and recommended value) or enables (1) LE-CODE developer modes. If disabled, LPAR settings DEV-MODE1 .. DEV-MODE3 and LEX section DEV1 are ignored.
DEV-MODE1
DEV-MODE2
DEV-MODE3
int These parameters are only intended for LE-CODE developers to support development. They define 3 global developer modes. A description of the parameters makes no sense, as they only have a temporary effect and are used again and again for new purposes.
LIMIT-MODE const This mode defines the allowed values for the other settings:
LE$PRODUCTIVE
Exclude test and experimental values.
LE$TESTING
Allow test values, but exclude experimental values.
LE$EXPERIMENTAL
Allow all values.
LE$AUTOMATIC
Enable automatic detection by analyzing all values.

Values set by an option are never limited. See parameter descriptions for limitation details.

CHEAT-MODE int LE-CODE supports cheat codes as sequence of D-Pad keys in combination with ALT1+ALT2. Here you can define, which type of cheat codes are allowed: 0: Almost all cheat codes are disabled. 1: Only cheat codes without impact to online game play are allowed. 2: All cheat codes are allowed. Value 2 is not possible if LIMIT-MODE=LE$PRODUCTIVE.

more details

ENGINE
--engine
int,int,int Defines probabilities for engine classes. A list for »100cc,150cc,mirror« is expected. If 200cc is enabled, the values are for »150cc,200cc,mirror«. Any number is accepted. They are normalized to get a total of 100 percent. Use »0,1,0« to force 150cc. Use »0,0,0« to reset to Nintendo's VR based choice.
ENABLE-200CC
--200cc
int Enables (1) or disables (0) 200cc support. LE-CODE hasn't implemented this feature yet!
PERF-MONITOR
--perf-mon
int Enables (1) or disables (0) the performance monitor for Wii and Wii U. Enabling is only possible if LIMIT-MODE!=LE$PRODUCTIVE. The special value 2 enables it for Dolphin too, but only if LIMIT-MODE=LE$EXPERIMENTAL. The performance monitor doesn't work correctly with Dolphin.
CUSTOM-TT
--custom-tt
int Enables (1) or disables (0) Time Trial for custom tracks.
XPFLAGS
--xpflags
int Enables (1) or disables (0) support for extended presence flags. Disable it only for tests! If LIMIT-MODE=LE$PRODUCTIVE, XPFLAGS is always enabled.
BLOCK-TRACK int Define the number of races that a previously used track is blocked. LE-CODE will try to find another possible track among the selected tracks. Values between 0 (deactivated at all) and 50 are allowed. Chat messages can clear the track list, enable or disable this feature.
SPEEDOMETER
--speedometer
const Enables (SPEEDO$0SPEEDO$3) or disables (SPEEDO$OFF) the speedometer. If enabled, it is displayed at bottom right of the screen using format »123.456 km/h«. In this case the digit of the constant defines the number of fraction digits in the display.
DEBUG
--debug
const Defines the basic debugging. DEBUG$OFF disabled debug output at all. All other values enable it. These other values are DEBUG$ENABLE and DEBUG$1 to DEBUG$4; they defines the start configuration. The player rotates through the five setups by a special button combination.

more details

ITEM-CHEAT int Enable (1) or disable (0) the built-in Item Cheat.
DRAG-BLUE-SHELL int Allow (1) or forbid (0) players to drag blue shells behind them. LE-CODE default is 1.
THCLOUD-TIME int Define the time in frames a player is small after being struck by a thundercloud. Only values between 1 and 32767 (0x7fff) are accepted. MKW uses 612 (10.2s) and LE-CODE default is 300 (5.0s).
BT-WORLDWIDE
VS-WORLDWIDE
int Disable (0) or enable (1) worldwide battles and/or versus. The online worldwide button is disabled, if both settings are disabled. See »LE-DEF Worldwide« for details.
BT-TEXTURES const Disable (value LE$DISABLE) or enable (value LE$ENABLE) random texture hacks for original battle arenas (slots 32 to 41). Append  | LE$ALTERABLE to allow players to toggle the value via D-PAD Cheats. Append  | LE$EXCLUDE to exclude the original track from the random selection.
VS-TEXTURES const Same as BT-TEXTURES, but for original versus tracks (slots 0 to 31).
BLOCK-TEXTURES int Disable (0) or enable (1) the blocking of recent random texture hacks. If disabled all online players select always the same texture variant. If enabled, then a texture variant will be blocked for the next 3 races. However, this has the disadvantage that players with different pasts may select different variants. But this should go away after a few races.
STATICR-POINTS int LE-CODE usually (0) overwrites the table that determines the distribution of points in private races. Nintendo has defined values between 0 and 15 in StaticR.rel, LE-CODE defines values between 1 and 25. If this parameter is set to 1, then the values are read from StaticR.rel.
DEF-ONLINE-SEC int If playing online, the racing time is limited. The original MKW uses 5:00 and LE-CODE & CTGP use 5:40. With this setting the time can be changed between 30s and 65535s (18:12:15). If the time is >525 (8:45), then the related watchdog (countdown + race_time + scoreboards) is disabled. See »Online Time Limit« for more details.
MIN-ONLINE-SEC
MAX-ONLINE-SEC
int A racing track can request a different online limit via LEX:SET1:APPLY-ONLINE-SEC. These 2 settings limit the actually used value. If either of them is zero or min>max, then the value of APPLY-ONLINE-SEC is ignored.
CUP-ICON-SIZE int As of LE-CODE build 40 & Wiimms SZS Tools v2.39a:
The parameter sets the size of a cup icon in pixels between 8x8 and 248x248 in increments of 8. The usual size is 128x128 pixels. Larger values hardly bring any advantages, small values can save a lot of space. Recommendations: 96x96 (saves 44% space) should be used for >500 cups and 64x64 (saves 75% space) for >800 cups and more. The image with the cup icons, which is loaded with the --cup-icons option, for example, must have the appropriate size.

As of build 41, LE-CODE supports the TPLx file format. If the cup icons are in this format and a valid signature is found, then this setting will be ignored.

SLOT-04X int As of LE-CODE build 40 & Wiimms SZS Tools v2.41a:
Define the index format for slots. It is either %03x (value 0) or %04x (value 1). Format %04x ensures that all slots are displayed in the same format (same number of characters). However, this is only relevant if a slot ≥0x1000 (≥4096) is used. The distribution creator must ensure that the files in ./Race/Course/ and directories in ./Race/Common/ are in the same format.

As of build 41, LE-CODE scans the ./Race/Course/ directory and finds out which format is used. This setting is then only used as a fallback.

Section [CHAT-MESSAGE-MODES]

LE-CODE supports a special feature for chat messages in private rooms. If a message is sent by the host and at least one guest is present, then some messages change the behavior of the game. Until LE-CODE build 16 the functions were hard coded to the messages (see below). As of LE-CODE build 17 and Wiimms SZS Tools v2.15 each function can be assigned to any message, and also to more than 1 message.

As of LE-CODE build 19 and Wiimms SZS Tools v2.17 it is possible to assign 2 comma separated modes to each message.

Only the definitions at the host's side are relevant. The host stores the settings in an internal data structure. The data is sent to all guests when starting a Grand Prix. This guarantees that late guests will be informed about the modified settings even if they never received the related chat messages. The settings are reset after finishing or aborting the Grand Prix, or on message mode CHAT$RESET.

List of available functions
Category Parameter in
Wiimms SZS Tools
Description
CHAT$OFF Default mode: Message has no special function.
CHAT$RESET Resets all special settings to their defaults.
select_track CHAT$TRACK_BY_HOST The host selects a track and wins the lottery. The track selection for guests is disabled.
CHAT$ANY_TRACK Cancels CHAT$TRACK_BY_HOST and enables standard track lottery.
block_track CHAT$BLOCK_CLEAR Clear the used-tracks list immediately.
CHAT$BLOCK_DISABLE Clear the used-tracks list immediately and disable the block-track functionality.
CHAT$BLOCK_ENABLE Enable the block-track functionality. This is the default, but have only impact, if BLOCK-TRACK > 0.

See section »Blocking tracks« for more details.

vehicle chat$vehicles(mode,...) Create a chat modus for a vehicle group. 0 to N values are expected as function parameters. Each parameter is either from the group VEH$SMALL, VEH$MEDIUM, VEH$LARGE and VEH$ANY_SIZE for size selections and/or from the group VEH$KART, VEH$BIKE, VEH$ANY_TYPE for type selections. Negative values are an alias for all of group except. VEH$ANY is a short cut for VEH$ANY_SIZE,VEH$ANY_TYPE.

See section »Vehicle Limitations« for more details.

CHAT$KARTS_ONLY Each player must select a kart.

Deprecated alias for chat$vehicles(VEH$KART)

CHAT$BIKES_ONLY Each player must select a bike.

Deprecated alias for chat$vehicles(VEH$BIKE)

CHAT$ANY_VEHICLE Cancels vehicle requirement.

Deprecated alias for chat$vehicles(VEH$ANY)

engine CHAT$USE_ENGINE_1 Forces the first engine class. Usually this is 100cc. If 200cc mode is activated, then it is 150cc.
CHAT$USE_ENGINE_2 Forces the second engine class. Usually this is 150cc. If 200cc mode is activated, then it is 200cc.
CHAT$USE_ENGINE_3 Forces the third engine class. Usually this is 150cc-mirror. If 200cc mode is activated, then it is 200cc-mirror.
CHAT$RESET_ENGINE Cancels engine selection.
n_races chat$n_races(N) Defines the number of races in the next Grand Prix. N is a number between 1 and 512 (inclusive).

The original game uses BMG messages 582 to 585 (hex) to announce the races. LE-CODE uses messages from 6100 (first race) to 62ff (512th race) for race announcements at the moment. It is planned to use message 610c for all races ≥13.

Notes
  • Constants are written here with upper case letters and the function-calls with lower case letters. Anyway, constant, variable and function names are case-insensitive.
  • Only messages sent by the host are relevant.
  • Only one option of each category can be active. A later messages cancels the previous message of the same category.

Legacy settings (old MKW-Fun settings)

Beginning with LE-CODE build 17, no chat messages have a special functionality by default. Each special functionality must be defined explicitly. If you want to use the old behavior defined for MKW-Fun, you will need to create a file (e.g. with name lpar.txt):

#LE-LPAR
[CHAT-MESSAGE-MODES]
@legacy = 1

This is equivalent to:

#LE-LPAR
[CHAT-MESSAGE-MODES]
M65 = chat$vehicles(VEH$ANY)
M69 = chat$vehicles(VEH$KART)
M70 = chat$vehicles(VEH$BIKE)
M71 = CHAT$TRACK_BY_HOST
M72 = CHAT$ANY_TRACK
M73 = chat$n_races(1)
M74 = chat$n_races(2)
M75 = chat$n_races(3)
M76 = chat$n_races(4)
M77 = chat$n_races(5)
M78 = chat$n_races(6)
M79 = chat$n_races(8)
M80 = chat$n_races(10)

Then use option --lpar lpar.txt when patching the LE-CODE binary.

The original game uses BMG messages 582 to 585 (hex) to announce the races. LE-CODE moved the messages to range 6100 to 6109 to support 10 races. MKW-Fun defines the following messages:

6100 = \z{802,110002}\z{802,110000} - 1st Race (\z{a02,1000000000} players)
6101 = \z{802,110002}\z{802,110000} - 2nd Race (\z{a02,1000000000} players)
6102 = \z{802,110002}\z{802,110000} - 3rd Race (\z{a02,1000000000} players)
6103 = \z{802,110002}\z{802,110000} - 4th Race (\z{a02,1000000000} players)
6104 = \z{802,110002}\z{802,110000} - 5th Race (\z{a02,1000000000} players)
6105 = \z{802,110002}\z{802,110000} - 6th Race (\z{a02,1000000000} players)
6106 = \z{802,110002}\z{802,110000} - 7th Race (\z{a02,1000000000} players)
6107 = \z{802,110002}\z{802,110000} - 8th Race (\z{a02,1000000000} players)
6108 = \z{802,110002}\z{802,110000} - 9th Race (\z{a02,1000000000} players)
6109 = \z{802,110002}\z{802,110000} - 10th Race (\z{a02,1000000000} players)

Sections [DEBUG-*]

The user can define 4 different debug configurations (=screens) by sections [DEBUG-1] to [DEBUG-4]. Each of theses configuration is independent of each other. The start configuration is defined by global parameter DEBUG.

The player can cycle forward and backward through the definitions using ALT1+D-Pad Left and ALT1+D-Pad Right. In some debug screens, ALT1+D-Pad Up and ALT1+D-Pad Down can be used to scroll. Only the first controller of each type is supported.

Configuration

Each debug section consists of a SETUP command, a HIDE-SPEEDO command and up to 10 line definition sets. Each command is optional. Generally value 0 means disabled and all other values enabled.

SETUP = DEBUG$OFF | DEBUG$CLEAR | DEBUG$STANDARD | DEBUG$OPPONENT | DEBUG$VERTICAL
This global command is independent from lines. It defines a basic setup and overwrites all definitions. An exception is DEBUG$OFF, that deactivates this command.
HIDE-SPEEDO = 0 | 1
This global command is independent from lines. If set and this configuration becomes active, then hide the speedometer. This helps if many lines are defined. Otherwise a smaller font is selected by the system.
LINE = 0 .. 9
Select a line. All following commands until the next LINE command disable or enable the output for the current line. If an invalid index is entered, the following commands are ignored. So set LINE=-1 to disable a complete line.
ENABLED = 0 | 1
With this command you can deactivate a line. All line parameters are still stored.
OPPONENT = 0 | 1
Usually the data of the current player is printed (font color yellow). If OPPONENT is enabled, then print the data of the first opponent and use a blue font color as indicator.
SPACE = 0 | 1
Usually the lines are separated by a line terminator (line feed). If SPACE is set, then a space is used instead, so that the previous and the current line are displayed in one visual line.
POSITION = 0 | 1
Output: P=x,y,z
If enabled then print the current position (x, y and z coordinates) of the player. Coordinates outside the range ±131071 (see Item position bug) are highlighted by an orange font, or a white font it the position is fixed by LEX ITEM-POS-FACTOR.
CHECK-POINT = 0 .. 3
Output: C=c   or   C=c,k   or   C=c,k^m
If enabled print a check point info. The mode defines how many parts are printed. c is the current check point. k is the last relevant key check point. m is the highest reached key check point in the current lap. If driving backwards, k is decreased, but m not.
RESPAWN = 0 | 1
Output: R=r
If enabled then print the respawn index defined by the current check point. This information may help to test all respawn points of a track.
ITEM-POINT = 0 | 1
Output: I=i
If enabled print the current item point index of the player. If an item point does not belong to a group in ITPH, then a g is appended. If the associated group is missing the PREV link, the NEXT link or both links, then one of the letters pnb is appended. In all error cases the output is in orange.
KCL-TYPE= 0 | 1
Output: K:t,v
If enabled print current KCL type (t=00-1F) and KCL variant (v=000-7FF). The colon after the K indicates a hex value.
LAP-POS = 0 | 1
Output: L=lap
Print the current lap position as floating point value with 3 digits. The integer number reflects the current lap number, and the decimal (0.000 to 0.999) the progress within the current lap. Together with the opponent view it can help to investigate different paths of a track and to place the check points at good positions.
TRACK-ID= 0 | 1
Output: T:id
If enabled and a random texture hack was selected, then the track id is printed. The colon after the T indicates a hex value.
XPF= 0 | 1 | 2
Output: X:...
If enabled, a short (1) or long (2) information about the usage of Extended presence flags is printed, but only if an information is available. The long information is similar to the short one, but with more or extended members. Only relevant members are printed. See below for details.

XPF

The debug output XPF is very generic. Only parts are printed, if they are relevant to the current track. The complete X:... is only printed if at least one element is printed. At the moment, short and long information are the same.

XPF Elements
Type Output Description
SL e=… GOBJ with engine selection used. … is the selected engine class.
SL r=… GOBJ with random scenario selection used. … is the scenario number.

The type defines when and how an element is printed:

XPF Types
Type Description
SL Available for modes short and long.
SL+ Available for mode short and as extended version for mode long.
L Available for mode long only.

Manage LPAR files

Create a LPAR file

A LPAR file can be created from scratch, by reading an old LPAR file or by reading a LE-CODE binary file:

# create LPAR from scratch
wlect create lpar > lpar.txt

# create updated LPAR after reading old LPAR file
wlect create lpar --lpar old-lpar.txt > lpar.txt

# create LPAR by reading a LE-CODE binary file
wlect lpar lecode-PAL.bin > lpar.txt

# create LPAR by LE-CODE binary file and update by old LPAR file
wlect lpar lecode-PAL.bin --lpar old-lpar.txt > lpar.txt

All examples create a file with name lpar.txt. After creation you can edit the file. It contains explanations about syntax and meanings. To suppress these explanations, use either option --no-header (-H) or option --brief (-B).

After creation you can edit a LPAR file with any text editor.

Use a LPAR file

A LPAR file is included by option --lpar FILE. Use it with command PATCH when defining the tracks:

wlect patch lecode-PAL.bin  --le-define DEFINITION  --lpar lpar.txt

It is also possible to change the parameters of a LE-CODE binary without definition file:

wlect patch lecode-PAL.bin  --lpar lpar.txt

Blocking tracks

Since LE-CODE build 20 recent used tracks can be blocked for the next selection. LE-CODE uses a multi-stage random selection of the tracks (see example below). This had to be taken into account during the implementation. Therefore, Wiimm and Leseratte decided to choose multiple tracks and awarded penalty points for each tracks that was rolled out. The track with the fewest penalty points is then selected.

Example for 3-stage random selection (MKW-Fun)
The player selects »Random Track«. Next, the game selects »Any DS track«. In a third step »DS Bowser Castle« is selected. And here we have 2 variants (»beam« and »fireball«). So we have 3 random selections.

Algorithm

If the block tracks feature is activated, attempts will be made up to 60 times to find a track that is not on the block list. If one is found, the pair consisting of player and track has won the lottery. Otherwise, the pair with the least penalty points will be used. There are the most penalty points for the last used track and fewer for the tracks further back on the list. A quadratic method is used to calculate the penalty points.

A selected track is inserted at the top of the block list. The list is reset by chat messages, or if entering region, or if opening a new private room.

Effects of the algorithm
  • Only tracks chosen by the players can win the lottery.
  • If all players select the same track, it is used even if played before. But if this track has random variants, the cheapest variant is chosen.
  • If the track is selected by host only, than its choice is used.
  • In worst case, all 60 tries choose a track that was used before. In this case, the cheapest of these tracks is selected.

Vehicle Limitations

Since LE-CODE build 20 there is a new algorithm to limit driver and vehicle selection in private rooms. The selection is done using Chat Messages send by the host. Wiimms SZS Tools support it by parser function chat$vehicles() (see above).

It is now possible to limit drivers and vehicles by size (small, medium, large) or by type (kart, bike), or by both. As example: MKW-Fun uses this chat setup:

M85 = chat$vehicles(VEH$ANY)
M86 = chat$vehicles(VEH$SMALL)
M87 = chat$vehicles(VEH$MEDIUM)
M88 = chat$vehicles(VEH$LARGE)
M89 = chat$vehicles(VEH$KART)
M90 = chat$vehicles(VEH$BIKE)

Message M85 allows all drivers. Message M86 to M88 limit the size and messages M89 and M90 the vehicle type. If the hosts send messages M87 and M89, only medium karts are allowed.

Combinations are possible too:

# exclude large vehicles:
M11 = chat$vehicles(VEH$SMALL,VEH$MEDIUM)

# limit to medium karts in one step:
M12 = chat$vehicles(VEH$SMALL,VEH$KART)

# limit to bikes, but exclude large ones
M13 = chat$vehicles(VEH$SMALL,VEH$MEDIUM,VEH$BIKE)
Some notes
  • The limitations works for versus and for battle.
  • The Mii can only be selected, if there are no size restrictions.
  • At the moment the vehicle type limitations don't work, if the player is online with a guest.
  • Wiimms SZS Tools support the function chat$vehicles() as of v2.17a. The built-in documentation is enabled as of v2.18a.