Extended presence flags
This page explains an extension for the Presence flags. The definition is completed now. It will be implemented in LE-CODE, Wiimms SZS Tools and ct.wiimm.de in the next months. Other software will follow.
Issues of the current model
MKWii uses the presence flags to conditionally enable or disable objects. Only the number of human players can be used as a condition. But there are many more parameters to differentiate between the activation of objects. A few wishes follow:
- I want to activate an object in Ballon Battle only, but not in Coin Runners.
- I want to disable some objects at time trial.
- I want to disable some objects online.
- I want to disable some objects only if many players are online.
- I want to disable some objects in item rain.
- I want to exchange an object by another one, if 7 or more players are online.
- Because of different timings of objects online and offline I have to offer 2 versions of the track to synchchronize objects. Is there a way, to include both variants of objects and activate one set offline and another set online?
- LE-CODE supports modifications of ObjFlow.bin, but CTGP and standard code does not. So I have to provide 2 versions of the track. Is it possbible to deliver only 1 track file for both cases?
Some questions aim at things that may be implemented in the future:
- I want to load the low-poly-model for some objects away from the main routes to reduce the slow motion effect.
- Is it possible, that one object enables/triggers another object if touched during the race?
So the LE-CODE team tries to find a definition that can fulfill all of these wishes and more. Future extensions were also considered, if known. However, space was also left for extensions that had not yet been considered. LE-CODE will implement the extensions first. CTGP could follow.
Data members
This third idea is based on an idea of Leseratte: Use some objects of KMP/GOBJ for a definition of settings. They are ignored by standard MKWii. Other objects can reference them using the padding word.
3 different variables of KMP/GOBJ are used for the extension:
- The OBJECT_ID (16 bit, values between 0x0001–0x02f3 ⇒ mask 0x03ff) is used to identify the object. Other bits (mask 0xfc00) can be used to hide and disable an object. MKWii will simply ignore unknown objects. Value 0 is a special case for it. LE-CODE uses bit 12 (mask 0x1000) to enable objects on CONDITIONS, that are otherwise disabled. LE-CODE uses bit 13 (mask 0x2000) for DEFINITION_OBJECTS. Such object can be referenced by using the same OBJECT_ID as REFERENCE. (see below).
- The padding at offset 2 (16 bits) is ignored by MKWii. LE-CODE will use it for the definition as REFERENCE to DEFINITION_OBJECTS.
- PRESENCE_FLAGS is a 16 bit value, but Nintendo has only defined bits 0–5 and MKWii uses only bits 0–2. So bits 6–15 (mask 0xffc0) can be used for custom/LE-CODE. The idea is, that 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 LE-CODE extension. Bits 6-11 can be used for other settings like "loading low poly model". Wiimm tested all objects of 8124 tracks of his archive, and all objects are in MODE=0.
Offline and online tests for racing tracks confirmed, that the extensions have no other impact to the original game. Tests for arenas will be done soon.
After the final definition, Wiimm will implement a web page as easy calculator. He will implement special functionality in his KMP tools too.
Presence Flags and MODE
The bits of the Presence Flags can be divided into 4 groups:
| Bits | Mask | Description |
|---|---|---|
| 0–2 | 0x0007 | Standard bits defined by Nintendo and used by MKWii. Ignored by LE-CODE and fallback for non LE-CODE. |
| 3–5 | 0x0038 | Standard bits defined by Nintendo, but not used by MKWii. Ignored by LE-CODE. |
| 6–11 | 0x0fc0 | PARAMETERS (7 bits), ignored by MKWii, custom meaning depends on MODE. |
| 12–15 | 0xf000 | MODE: Define the meaning of PARAMETERS and CONDITIONS, ignored by MKWii. |
REFERENCES on MODE=1
The 16 bit of the padding (offset 2) are used as REFERENCE_ID to a DEFINITION_OBJECT. The reference is only valid, if bit 13 (mask 0x2000) is set. In this case, the first DEFINITION_OBJECT with the ID REFERENCE_ID is searched. If no DEFINITION_OBJECT is found, the original object is deactivated. Otherwise the CONDITIONS are evaluated.
If bit 13 is not set, then no CONDITIONS are defined and the object becomes active.
- Recommendation:
- Use REFERENCE_ID 0x2000 for objects, that should be disabled by LE-CODE. And do not define an object with this ID.
DEFINITION_OBJECTS
The DEFINITION_OBJECT is one element of KMP/GOBJ. Since bit 13 (mask 0x2000) is always set, it is an invalid object and is ignored by MKWii. So its only usage is to define CONDITIONS. Use the default values as explained in the table!
And advantage is, that 1 DEFINITION_OBJECT can be used for many standard objects of different types. So standard objects are grouped into functionality groups.
| 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 MKWii. |
| 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. Not used. Set it to 0. |
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 Ballon Battles. |
| 2 | CONDITIONS for Coin Runners. |
| 3 | CONDITIONS for Versus Races, Grand Prix and Time Trial (RESERVED1). |
| 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. |
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. |
Behavior ot the executors
Standard code
Standard code (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 or 13 set are ignored.
LE-CODE
LE-CODE analyses MODE, REFERENCES and CONDITIONS:
- If MODE is unknown or not supported, LE-CODE does nothing.
- On MODE=1, the REFERENCE_ID of the object is read. It is only valid, if bit 13 (mask 0x2000) is set. See below for more details.
If the REFERENCE_ID is valid, then the CONDITIONS are processed and the object becomes either active of inactive:
- 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 MKWii recognizes the object (if bit 13 not set) and use it like usual.
- If the object is inactive, OBJECT_ID, REFERENCE and PRESENCE_FLAGS are set to value 0. So MKWii ignores the object at least because of invalid OBJECT_ID.
Examples
Here some examples are explained to make understanding easier:
- Define an object, that is only used by standard code.
- Set MODE=1 and REFERENCE_ID to value 0x2000 and don't define an object with this id. LE-CODE will process the conditions, but will not find any. So it deactivates the object.
- Define an object, that is only used by LE-CODE
- Set MODE=1, set bit 12 of the OBJECT_ID and set REFERENCE_ID=0. The standard code will ignore the object (invalid ID). LE-CODE will clear bit 12 and enable the object.
- 2 alternative objects: 1 for standard code and 1 for LE-CODE
- Define a standard object. Set REFERENCE_ID to 0x2000, but don't define a DEFINITION_OBJECT for this id. Set MODE=1 at PRESENCE_FLAGS. This Object is active for standard code. LE-CODE will deactivate it, because of MODE=1 and a valid REFERENCE_ID without defined CONDITIONS.
- Define a second object with. Set bit 12 of OBJECT_ID to disable it for standard code. Set REFERENCE_ID to 0 to tell LE-CODE, that no CONDITIONS needed (assume TRUE).
- 2 alternative objects: 1 for single player at Wii, another for multipe players at Wii.
- Define a standard object. Set REFERENCE_ID to 0x2001. Define a DEFINITION_OBJECT with CONDITIONS for single player and this id. Set PRESENCE_FLAGS to 0x1001 (MODE=1, 1 player). This Object is active for standard code for 1 player. LE-CODE will activate it based on the CONDITIONS.
- Define a standard object. Set REFERENCE_ID to 0x2002. Define a DEFINITION_OBJECT with inverted CONDITIONS of above and this id. Set PRESENCE_FLAGS to 0x103e (MODE=1, >1 player). This Object is active for standard code for 2-4 players. LE-CODE will activate it based on the CONDITIONS.
Software support
LE-CODE
Leseratte and Wiimm will start with the implementation soon.
- Support of LEX session TEST.
- Implement a function, that is called after loading and unpacking the track file, but before the SZS files is analyzed by MKWii.
Wiimms SZS Tools
Wiimm planned software support for his SZS Tools:
- The KMP text processor of his tools will detect DEFINITION_OBJECTS and will display them in an alternative view including a cross reference.
- The KMP parser+compiler of his tools accepts alternative syntax for entering DEFINITION_OBJECTS.
- New warnings will be added to »wkmpt check«.
Already implemented (comparechange log):
- LEX: A new section named »TEST« will be added. It contains variables to force conditions like "10 players online" event ft playing offline and alone. So you can test any of the CONDITIONS privately. The new options --lt-clear, --lt-online, --lt-n-players and --lt-game-mode allow easy patching of a track with the new settings.
ct.wiimm.de
Wiimm planned software support for his website ct.wiimm.de:
- A new web page at ct.wiimm.de will help to define and calculate CONDITIONS and DEFINITION_OBJECTS.
- Statistics about the usage of this extension.
- In the distant future a special web page at ct.wiimm.de is planned: The user uploads some tracks and defines some parameters. Then the website creates a LE-CODE distribution, where the track is included many times to cover all CONDITIONS.
KMP Tools
All KMP tools must be proofed, if they don't clear but COPY the additional data and if they allow to EDIT the extensions. Maybe some authors will add a special support (=MANAGE).
| Tool | Author | Extended Object ID |
Values for padding |
Extended bits of Presence flags |
Special support of conditions | ||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
| Copy | Edit | Manage | Copy | Edit | Manage | Copy | Edit | Manage | |||
| KMP Cloud | Vulcanus2 | ? | ? | ✖ | ? | ? | ✖ | ? | ? | ✖ | ✖ |
| KMP Modifier | kHacker35000vr | ? | ? | ✖ | ? | ? | ✖ | ? | ? | ✖ | ✖ |
| KMP3D | zatchi | ? | ? | ✖ | ? | ? | ✖ | ? | ? | ✖ | ✖ |
| Lorenzi's KMP Editor | Hlorenzi | ? | ? | ✖ | ? | ? | ✖ | ? | ? | ✖ | ✖ |
| SZS Modifier | Chadderz | ? | ? | ✖ | ? | ? | ✖ | ? | ? | ✖ | ✖ |
| Wexos's Toolbox | Wexos | ? | ? | ✖ | ? | ? | ✖ | ? | ? | ✖ | ✖ |
| Wiimms SZS Tools | Wiimm | ✔ | ✔ | ✖ | ✔ | ✔ | ✖ | ✔ | ✔ | ✖ | ✖ |
- Notes
- Copy: Tool reads values and stores them at least when object was not edited.
- Edit: Tool allows simple (hex) edit of the values.
- Manage: Tool supports and interprets the extension.