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 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 disbale 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.
Data member: 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.
Data member: 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 definiton object.
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.
Data member: 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 definiton objects.
- Bit 12 (mask 0x1000) is used to disable or enable an object.
Bits 10 and 11 (mask 0x0c00) are not used.
Predifined Conditions
One importand idea of this extension is, to disable or enable objects by complex conditions. Therefor definiton objects are defined. But mostly the user needs only simple conditions like only online or 'only in coin runners. The this extension defines a series of predefined conditions. The user must simply add the code as reference_id. Wiimms ISO Tools support names too.
The predifined conditions can be divided into 3 groups:
- Engine Selection (0x1e00 – 0x1e7f)
- Random Scenarios (0x1f00 – 0x1e3f)
- Hard coded conditions (0x1000 – 0x17ff)
There is enough space to define more groups and conditions. Undefined values are interpreted as FALSE. The object is thus disabled.
Engine Selection
It will be possible to select objects by engine. This is in development now. Implemented engine modes are:
- Battle
- 50cc
- 100cc
- 150cc and time trial
- 200cc
- 150cc mirror
- 200cc mirror
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 0x1f3f is reserved for this feature. So we have 6 bits (0-5, mask 0x003f) for 6 different scenarios. The game executor (e.g. LE-CODE) creates a random number between 1 and 6 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.
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 |
Description |
|---|---|---|---|
| 0x1000 | never | — | LE-CODE will always disable this object. |
| 0x1001 | lecode | — | LE-CODE will always enable this object. |
| 0x1002 | p1 | single | Enabled for 1 player at Wii. |
| 0x1003 | p234 | multi | Enabled for 2–4 players at Wii. |
| 0x102e | p2 | — | Enabled for 2 players at Wii. |
| 0x102f | p134 | — | Enabled for 1, 3 or 4 players at Wii. |
| 0x1030 | p3 | — | Enabled for 3 players at Wii. |
| 0x1031 | p124 | — | Enabled for 1, 2 or 4 players at Wii. |
| 0x1032 | p4 | — | Enabled for 4 players at Wii. |
| 0x1033 | p123 | — | Enabled for 1–3 players at Wii. |
| 0x1034 | p12 | — | Enabled for 1 or 2 players at Wii. |
| 0x1035 | p34 | — | Enabled for 3 or 4 players at Wii. |
| 0x1036 | p13 | — | Enabled for 1 or 3 players at Wii. |
| 0x1037 | p24 | — | Enabled for 2 or 4 players at Wii. |
| 0x1038 | p14 | — | Enabled for 1 or 4 players at Wii. |
| 0x1039 | p23 | — | Enabled for 2 or 3 players at Wii. |
| 0x1006 | 1_6 | le6 | Enabled if total number of human players is less or equal 6. |
| 0x1007 | 7_99 | ge7 | Enabled if total number of human players is greater or equal 7. |
| 0x1008 | 1_9 | le9 | Enabled if total number of human players is less or equal 9. |
| 0x1009 | 10_99 | ge10 | Enabled if total number of human players is greater or equal 10. |
| 0x100a | 1_12 | le12 | Enabled if total number of human players is less or equal 12. |
| 0x100b | multi | 13_99 | Enabled if total number of human players is greater or equal 13. |
| 0x100c | 1_18 | ge13 | Enabled if total number of human players is less or equal 18. |
| 0x100d | 19_99 | ge19 | Enabled if total number of human players is greater or equal 19. |
| 0x100e | 7_9 | — | Enabled if total number of human players is between 7 and 9. |
| 0x100f | not_7_9 | — | Enabled if total number of human players is less 7 or greater 9. |
| 0x1010 | 7_12 | — | Enabled if total number of human players is between 7 and 12. |
| 0x1011 | not_7_12 | — | Enabled if total number of human players is less 7 or greater 12. |
| 0x1012 | 7_18 | — | Enabled if total number of human players is between 7 and 18. |
| 0x1013 | not_7_18 | — | Enabled if total number of human players is less 7 or greater 18. |
| 0x1014 | 10_12 | — | Enabled if total number of human players is between 10 and 12. |
| 0x1015 | not_10_12 | — | Enabled if total number of human players is less 10 or greater 12. |
| 0x1016 | 10_18 | — | Enabled if total number of human players is between 10 and 18. |
| 0x1017 | not_10_18 | — | Enabled if total number of human players is less 10 or greater 18. |
| 0x1018 | 13_18 | — | Enabled if total number of human players is between 13 and 18. |
| 0x1019 | not_13_18 | — | Enabled if total number of human players is less 13 or greater 18. |
| 0x1004 | offline | — | Enabled if playing offline. |
| 0x1005 | online | — | Enabled if playing online. |
| 0x101a | timetrial | — | Enabled if playing time trial. |
| 0x101b | not_timetrial | — | Enabled if playing any other than time trial. |
| 0x101c | battle | — | Enabled if playing battle (balloon battle or coin runners). |
| 0x101d | race | — | Enabled if playing a race (versus or itemrain). |
| 0x101e | balloon | — | Enabled if playing balloon battle. |
| 0x101f | not_balloon | — | Enabled if playing any other than balloon battle. |
| 0x1020 | coin | — | Enabled if playing coin runners. |
| 0x1021 | not_coin | — | Enabled if playing any other than coin runners. |
| 0x1022 | versus | — | Enabled if playing versus. |
| 0x1023 | not_versus | — | Enabled if playing any other than versus. |
| 0x1024 | itemrain | — | Enabled if playing item rain. |
| 0x1025 | not_itemrain | — | Enabled if playing any other than item rain. |
Definition Objects
A definition_object is one element of KMP:GOBJ with an object_id ≥0x2000 to 0x2fff. 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. So its only usage is to define extended conditions. A defintion 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 mdoe, number of palyers and offline/onloine.
- Values between 0x4000 and 0x4fff are used as reference ence for definition objects of type OR: The 8 settings are interpreted as predifend conditions. If at least one is true, the object is enabled.
- Values between 0x2000 and 0x2fff are used for definiton objects of type AND: The 8 settings are interpreted as predifend conditions. If all conditions are true, the object is enabled.
Predifined Condition
???
Type BIT
???
Usage of Settings
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
???
Type AND
???
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. Bit 13 (mask 0x2000) is always set, so that the object is always inactive for Mario Kart Wii. |
| 0x02 | UInt16 | REFERENCE. Not used. Set it to 0. |
| 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] | CONDITIONS for 8 game modes. See table below for details. |
| 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 or 13 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:
- 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 ACTIVE or as INACTIVE. 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.
- Otherwise, no conditions are defined and the object will be deactivated.
- Otherwise, the reference_id is not valid the object will be deactivated.
Now, if not aborted before, LE-CODE processes a second step:
- If the object is active, 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 bit 13 not set) and use it like usual.
- If the object is inactive, object_id is set value 0 (=invalid).
In a final step, LE-CODE removes all invalid objects form the list before Mario Kart Wii sees it.