Difference between revisions of "LPAR (File Format)"

Revision as of 04:52, 3 August 2020

LE-CODE

LE-CODE & related file formats

Extended presence flags

Related Categories

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 some 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 2 sections are supported, one for General Parameters and one for Chat Messages. So a typical LPAR file looks like this:

#LE-LPAR

[LECODE-PARAMETERS]

LIMIT-MODE	= LE$PRODUCTIVE

ENGINE          = 10,60,30
ENABLE-200CC    = 0
PERF-MONITOR    = 0
CUSTOM-TT       = 0
XPFLAGS         = 1


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

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

Sections

General Parameters [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.

General Parameters
Parameter Name	Value	Related Option	Description
`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.
`ENGINE`	`int,int,int`	`--engine`	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`	`int`	`--200cc`	Enables (1) or disables (0) 200cc support. LE-CODE hasn't implemented this feature yet!
`PERF-MONITOR`	`int`	`--perf-mon`	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`	`int`	`--custom-tt`	Enables (1) or disables (0) Time Trial for custom tracks.
`XPFLAGS`	`int`	`--xpflags`	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.

Chat Messages [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 will be 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 tracks and wins the lottery. The track selection for guests is disabled.
select_track	`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-call with lower case letters. Anyway, the text parser accepts constant, variable and function names in any case.
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$ANY_VEHICLE
M69 = CHAT$KARTS_ONLY
M70 = CHAT$BIKES_ONLY
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)

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

Implementation notes

This section describes details of how some properties are implemented in Wiimms SZS Tools and LE-CODE Executor

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 is 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$KART)

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.