Extended presence flags/Technical Description
- Extended presence flags
- Related articles
- LE-CODE: FAQ for track creators
- LE-CODE: Distribution Tutorial
- LE-CODE: FAQ for distribution creators
- LEX: File format and definitions
- Wiimm's Test Tracks
- Related Categories
.png){kind=logo}
This page explains the technical details of the Extended presence flags (XPF) defined by Wiimm. It is an extension for the classic Presence flags by Nintendo. It allows to disable or enable objects by many more conditions than the old model does.
Introduction
For the technical implementation only records KMP:GOBJ are interpreted in a different way. Bits are used for this that previously had no meaning. A test with all tracks from the Wiimms archive has shown that none of the tracks use these bits.
Data members
The idea: Bits of objects of KMP:GOBJ that are not used before for this extension and ensure the uniqueness between standard objects and extended objects.
The implementation distinguish 2 different methods:
- Use the padding word (offset 2) as predefined extended condition.
- Use the padding word as link to another object, that defines a combined condition.
The extension interprets 3 data fields of the objects in a different way:
- Data member presence_flag is used to find out, if the the object is subject for this extension.
- Data member reference_id (padding in the old model) is either used as predefined condition or as reference to a definition-object.
- Data member object_id is either extended to disable or enable the object, or to define a definition-object.
Offline and online tests for racing tracks and battle arenas confirmed, that this extended use of the data members have no other impact to the original game.
Presence_flag (and MODE)
The presence_flags is a 16 bit value, but Nintendo has only defined bits 0–5 (mask 0x003f) and Mario Kart Wii uses only bits 0–2. So bits 6–15 (mask 0xffc0) can be used for this extension.
Bits 12-15 (highest hex digit, mask 0xf000) are used to select one of 16 general MODES. MODE=0 is the classic mode and MODE=1 is used for this extension. Other modes are reserved for the future.
The remaining bits 6-11 can be used for other settings like loading low poly model. Wiimm tested all objects of 8124 tracks of his track archive, and all objects are in MODE=0.
| Bits | Mask | Description |
|---|---|---|
| 0–2 | 0x0007 | Standard bits defined by Nintendo and used by Mario Kart Wii. Ignored by LE-CODE and fallback for non LE-CODE. |
| 3–5 | 0x0038 | Standard bits defined by Nintendo, but not used by Mario Kart Wii. Ignored by LE-CODE. |
| 6–11 | 0x0fc0 | Parameters (6 bits), ignored by Mario Kart Wii, custom meaning depends on MODE. |
| 12–15 | 0xf000 | MODE: Define the meaning of parameters and conditions. Mario Kart Wii ignores it. |
The following description of this page is only valid, if MODE=1.
Reference_id (padding)
The padding word at offset 2 (16 bits) is ignored by Mario Kart Wii. This extension uses it as reference_id (but ony if MODE=1):
- Values between 0x1000 and 0x1fff are used as reference for a predifinded condition.
- Values greater or equal 0x2000 are used as reference to a definition object. Here bit 12 (0x1000) is used as negation indicator.
A general issue of most KMP tools is, that they ignore these padding bytes totally (don't view, don't allow edit, store always 0). See »Implementation Hints« for details.
Object_id
The object_id (16 bit, values between 0x0001–0x02f3 ⇒ mask 0x03ff) is used to identify the type of the object. Other bits (mask 0xfc00) can be used to hide and disable an object. Mario Kart Wii will simply ignore unknown objects. Value 0 is a special case for it.
This extension uses the object_id in 2 different ways (but ony if MODE=1):
- Values greater or equal 0x2000 are used by definition objects.
- Bit 12 (mask 0x1000) is used to disable or enable an object if object_id<0x2000.
Bits 10 and 11 (mask 0x0c00) are not used (yet?).
Predifined Conditions
One importand idea of this extension is, to disable or enable objects by complex conditions. Therefore definition objects are defined. But mostly the user needs only simple conditions like only online or only in coin runners. So this extension defines a series of predefined conditions. The user must simply add the code as reference_id. Wiimms ISO Tools support names too.
For each predefined condition there is another condition that says exactly the opposite (negation).
The predifined conditions can be divided into 3 groups:
- Hard coded conditions (0x1000 – 0x17ff)
- Engine Selection (0x1e00 – 0x1e7f)
- Random Scenarios (0x1f00 – 0x1fff)
There is enough space to define more groups and conditions. Undefined values are interpreted as FALSE. The object is thus disabled (or enabled if negated).
Hard coded conditions
The following predefined condition appears always as pair: The second one is always the reverse of the first one. The following table shows all predefined conditions:
| Value | Technical Name |
Alias for Name |
Condition |
|---|---|---|---|
| 0x1000 | never | — | LE-CODE interpretes this condition as always false. |
| 0x1001 | lecode | p1234 | LE-CODE interpretes this condition as always true. |
| 0x1002 | p1 | single | If 1 player at Wii. |
| 0x1003 | p234 | multi | If 2–4 players at Wii. |
| 0x102e | p2 | — | If 2 players at Wii. |
| 0x102f | p134 | — | If 1, 3 or 4 players at Wii. |
| 0x1030 | p3 | — | If 3 players at Wii. |
| 0x1031 | p124 | — | If 1, 2 or 4 players at Wii. |
| 0x1032 | p4 | — | If 4 players at Wii. |
| 0x1033 | p123 | — | If 1–3 players at Wii. |
| 0x1034 | p12 | — | If 1 or 2 players at Wii. |
| 0x1035 | p34 | — | If 3 or 4 players at Wii. |
| 0x1036 | p13 | — | If 1 or 3 players at Wii. |
| 0x1037 | p24 | — | If 2 or 4 players at Wii. |
| 0x1038 | p14 | — | If 1 or 4 players at Wii. |
| 0x1039 | p23 | — | If 2 or 3 players at Wii. |
| 0x1006 | 1_6 | le6 | If total number of human players is less or equal 6. |
| 0x1007 | 7_99 | ge7 | If total number of human players is greater or equal 7. |
| 0x1008 | 1_9 | le9 | If total number of human players is less or equal 9. |
| 0x1009 | 10_99 | ge10 | If total number of human players is greater or equal 10. |
| 0x100a | 1_12 | le12 | If total number of human players is less or equal 12. |
| 0x100b | 13_99 | ge13 | If total number of human players is greater or equal 13. |
| 0x100c | 1_18 | le18 | If total number of human players is less or equal 18. |
| 0x100d | 19_99 | ge19 | If total number of human players is greater or equal 19. |
| 0x100e | 7_9 | — | If total number of human players is between 7 and 9. |
| 0x100f | not_7_9 | — | If total number of human players is less 7 or greater 9. |
| 0x1010 | 7_12 | — | If total number of human players is between 7 and 12. |
| 0x1011 | not_7_12 | — | If total number of human players is less 7 or greater 12. |
| 0x1012 | 7_18 | — | If total number of human players is between 7 and 18. |
| 0x1013 | not_7_18 | — | If total number of human players is less 7 or greater 18. |
| 0x1014 | 10_12 | — | If total number of human players is between 10 and 12. |
| 0x1015 | not_10_12 | — | If total number of human players is less 10 or greater 12. |
| 0x1016 | 10_18 | — | If total number of human players is between 10 and 18. |
| 0x1017 | not_10_18 | — | If total number of human players is less 10 or greater 18. |
| 0x1018 | 13_18 | — | If total number of human players is between 13 and 18. |
| 0x1019 | not_13_18 | — | If total number of human players is less 13 or greater 18. |
| 0x1004 | offline | — | If playing offline. |
| 0x1005 | online | — | If playing online. |
| 0x101a | timetrial | tt | If playing time trial. |
| 0x101b | not_timetrial | nott | If playing any other than time trial. |
| 0x101c | battle | — | If playing battle (balloon battle or coin runners). |
| 0x101d | race | — | If playing a race (versus or itemrain). |
| 0x101e | balloon | — | If playing balloon battle. |
| 0x101f | not_balloon | — | If playing any other than balloon battle. |
| 0x1020 | coin | — | If playing coin runners. |
| 0x1021 | not_coin | — | If playing any other than coin runners. |
| 0x1022 | versus | — | If playing versus. |
| 0x1023 | not_versus | — | If playing any other than versus. |
| 0x1024 | itemrain | — | If playing item rain. |
| 0x1025 | not_itemrain | — | If playing any other than item rain. |
Engine Selection
It is possible to select objects by engine. The range between 0x1e00 to 0x1e7f is reserved for this feature. So we have 7 bits (0-6, mask 0x007f) for 7 different engine classes:
| Bit | Mask | Description |
|---|---|---|
| 0 | 0x01 | Battle |
| 1 | 0x02 | 50cc |
| 2 | 0x04 | 100cc |
| 3 | 0x08 | 150cc and time trial |
| 4 | 0x10 | 200cc (not supported by LE-CODE yet) |
| 5 | 0x20 | 150cc mirror |
| 6 | 0x40 | 200cc mirror (not supported by LE-CODE yet) |
Random Scenarios
It is possible the enable or disable objects by random. So a track can varies for each race:
- Enable fences to disable ways.
- Enable ramps to allow short cuts.
- Varies the routes or times of enemies to confuse the players.
The range between 0x1f00 to 0x1fff is reserved for this feature. So we have 8 bits (0-7, mask 0x00ff) for 8 different scenarios. The game executor (e.g. LE-CODE) creates a random number between 1 and 8 before racing to select the random scenario N. It is guaranteed that all online players use the same random number. If the the correspondent bit of the REFERENCE_ID is set, the object is enabled, otherwise it is disabled.
Time Trial runs always in random scenario 1. Random scenarios can be combined with other conditions by using a definition object.
Definition Objects
A definition_object is one element of KMP:GOBJ with an object_id ≥0x2000. Since one of the bits 13 to 15 (mask 0xe000) is always set, it is an invalid object for Mario Kart Wii and is ignored by it. So the only usage of these objects is to define extended conditions. A definition object can be referenced by any number of standard objects.
Definition objects can be divided into 3 groups:
- Values between 0x2000 and 0x2fff are used for definition objects of type BIT: Each bit of the 8 settings (128 bits total) represents an other combination of game mode, number of players and offline/online.
- Values between 0x4000 and 0x4fff are used definition objects of type OR: The 8 settings are interpreted as predefined conditions. If at least one is true, the result is true, otherwise it is false.
- Values between 0x6000 and 0x6fff are used for definition objects of type AND: The 8 settings are interpreted as predefined conditions. If all conditions are true, the result is true, otherwise it is false.
Each definition_object returns either false or true. Bit 12 (0x1000) of the reference_id is used as negation indicator. If set, the result is negated.
Entry Condition
The reference_id of each definition object can be used as entry condition. If the reference_id is not 0, it is analyzed as predefined condition. If this conditions returns false, the analysis is aborted and the result of the definition object is false too.
Type BIT
This mode is called »BIT« mode, because each of the 128 bits of the 8 settings has an own meaning. The bit is addressed by game mode, offline or online and number of players.
Select a Setting
The 8 settings are used for the condition. Each setting is related to a general game mode. At the beginning, only settings 1–4 are used for different game modes:
| Index | Description |
|---|---|
| 1 | CONDITIONS for Balloon Battles. |
| 2 | CONDITIONS for Coin Runners. |
| 3 | CONDITIONS for Versus Races, Grand Prix and Time Trial. |
| 4 | CONDITIONS for Item Rain. |
| 5–8 | Not used yet. Set it to the same value as setting #3 (Versus) to have a good default if new game modes become available. |
Condition Bits
The bits of each setting are defined in the same way to make implementation easier:
| Bit | Mask | Description |
|---|---|---|
| 0 | 0x0001 | Offline race/battle with 1 human player. |
| 1 | 0x0002 | Offline race/battle with 2 human players. |
| 2 | 0x0004 | Offline race/battle with 3 human players. |
| 3 | 0x0008 | Offline race/battle with 4 human players. |
| 4 | 0x0010 | Online race/battle with 1–6 players total and 1 human player at Wii. |
| 5 | 0x0020 | Online race/battle with 1–6 players total and 2 human players at Wii. |
| 6 | 0x0040 | Online race/battle with 7–9 players total and 1 human player at Wii. |
| 7 | 0x0080 | Online race/battle with 7–9 players total and 2 human players at Wii. |
| 8 | 0x0100 | Online race/battle with 10–12 players total and 1 human player at Wii. |
| 9 | 0x0200 | Online race/battle with 10–12 players total and 2 human players at Wii. |
| 10 | 0x0400 | Online race/battle with 13–18 players total and 1 human player at Wii. |
| 11 | 0x0800 | Online race/battle with 13–18 players total and 2 human players at Wii. |
| 12 | 0x1000 | Online race/battle with 19 or more players total and 1 human player at Wii. |
| 13 | 0x2000 | Online race/battle with 19 or more players total and 2 human players at Wii. |
| 14 | 0x4000 | RESERVED1. In Versus (setting #3) it is used for Time Trial. |
| 15 | 0x8000 | RESERVED2. |
Type OR
All 8 settings are analyzed. If the setting is 0, false is assumed. If a setting is not 0, it is analyzed as predefined condition. If at least 1 setting returns true, the analysis is aborted and the result of this definition object is true. Otherwise all conditions are false and the result is false too.
Together with the entry condition we have the following logical expression:
entry && ( s1 || s2 || s3 || s4 || s5 || s6 || s7 || s8 )
If the negation flag is set, the logical expression is changed to:
!( entry && ( s1 || s2 || s3 || s4 || s5 || s6 || s7 || s8 )) == !entry || ( !s1 && !s2 && !s3 && !s4 && !s5 && !s6 && !s7 && !s8 )
Type AND
All 8 settings are analyzed. If the setting is 0, true is assumed. If a setting is not 0, it is analyzed as predefined condition. If at least 1 setting, that is not 0, returns false, the analysis is aborted and the result of this definition object is false too. Otherwise all conditions are either 0 (no condition) or true and the result is true.
Together with the entry condition we have this following logical expression:
entry && s1 && s2 && s3 && s4 && s5 && s6 && s7 && s8
Summary of data members
The following table declares the new usage of all data members of a KMP:GOBJ element used as definition object:
| Offset | Type | Description |
|---|---|---|
| 0x00 | UInt16 | Object ID to identify the DEFINITION_OBJECT. At least one bit of 13–15 (mask 0xe000) is always set, so that the object is always ignored by standard Mario Kart Wii. |
| 0x02 | UInt16 | REFERENCE. 0 or any predifined condition. |
| 0x04 | Float[3] | 3D position vector. Not used. Set it to vector (0,0,0). |
| 0x10 | Float[3] | 3D rotation vector. Not used. Set it to vector (0,0,0). |
| 0x1C | Float[3] | 3D scale vector. Not used. Set it to vector (0,0,0). |
| 0x28 | UInt16 | Route. Not used. Set it to -1 (0xffff). |
| 0x2A | UInt16[8] | 8 conditions, dependent on type of definition object (see descriptions above). |
| 0x3A | UInt16 | Presence flags. Payload is not used. But set it to 0x1000 for MODE=1. |
Behavior of the executors
Standard code
Standard code (Mario Kart Wii and CT-CODE too) ignores …
- … the complete object, if its OBJECT_ID is unknown (e.g. if bit 12, 13, 14 or 15 is set).
- … the reference_id (16 bit padding at offset 2).
- … bits 3–15 of presence_flags.
So only standard objects are processed in the old standard way. Objects with bit 12–15 set are ignored.
LE-CODE
LE-CODE analyses MODE, REFERENCES and CONDITIONS for each object:
- If MODE is unknown or not supported (mode!=1), LE-CODE aborts the processing does nothing.
- If reference_id is between 0x1000 and 0x1fff), a predefined condition is found. If is either evaluated as false or as true. The processing is continued with step 2.
- Otherwise, if the reference_id is ≥0x2000, search a definition object:
- If a definition object is found, its conditions are evaluated and the definition object returns false or true.
- Otherwise, no condition is defined and the result is false.
- If the negation flag of the reference (bit 12, mask 0x1000) is set, the result is negated.
- Otherwise, the reference_id is not valid the result is false.
Now, if not aborted before, LE-CODE processes a second step:
- If the result is true, the object is activated. Therefor bit 12 of object_id is cleared and the presence_flags is set to value 0x3f. Reference is set to 0. So Mario Kart Wii recognizes the object (if bits 13—15 not set) and use it like usual.
- Otherwise the result is false and the object is deactivated. Therefore object_id is set value 0 (=invalid).
After the analysis off all objects LE-CODE removes all invalid and disabled objects from the GOBJ list and updates the number of objects in the section header before Mario Kart Wii sees it.