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 Balloon 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 synchronize 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 possible 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
The idea: Use some objects of KMP/GOBJ with invalid object id for a definition of settings. Such objects are ignored by standard MKWii. Other objects can reference them using the padding word, that is not used otherwise.
3 different variables of KMP/GOBJ are used for the extension:
- 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. MKWii will simply ignore unknown objects. Value 0 is a special case for it. This extension uses bit 12 (mask 0x1000) to enable objects on CONDITIONS, that are otherwise disabled. It uses bit 13 (mask 0x2000) for DEFINITION_OBJECTS. Such object can be referenced by using the same OBJECT_ID as REFERENCE_ID. (see below).
- REFERENCE_ID
- The padding word at offset 2 (16 bits) is ignored by MKWii. This extension uses it as REFERENCE_ID for predifined (hard coded) conditions and to find a DEFINITION_OBJECT with same id. 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).
- PRESENCE_FLAGS
- The PRESENCE_FLAGS is a 16 bit value, but Nintendo has only defined bits 0–5 (mask 0x003f) and MKWii 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. 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 archive, and all objects are in MODE=0.
Offline and online tests for racing tracks and battle arenas confirmed, that the extensions have no other impact to the original game.
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. |
REFERENCE_ID if MODE=1
The 16 bit of the padding (offset 2) are used as REFERENCE_ID either for a hard coded CONDITION (bit 12 set, range 0x1000 to 0x1fff) or to a DEFINITION_OBJECT (bit 13 set, range 0x2000 to 0x2fff).
Hard coded CONDITIONS
Hard coded conditions are simple predefined condition pairs; the scond one is always the reverse of the first one. The following table shows all predefined conditions:
| Value | Technical Name |
Description |
|---|---|---|
| 0x1000 | never | LE-CODE will always disable this object. |
| 0x1001 | lecode | LE-CODE will always enable this object. |
| 0x1002 | single | Enabled for single player at Wii. |
| 0x1003 | multi | Enabled for multiple player at Wii. |
| 0x1004 | offline | Enabled if playing offline. |
| 0x1005 | online | Enabled if playing online. |
| 0x1006 | timetrial | Enabled if playing time trial. |
| 0x1007 | not_timetrial | Enabled if playing any other than time trial. |
| 0x100e | battle | Enabled if playing battle (ballon battle or coin runners). |
| 0x100f | racing | Enabled if playing a race (versus or itemrain) |
| 0x1080 | balloon | Enabled if playing ballon battle. |
| 0x1081 | not_balloon | Enabled if playing any other than ballon battle. |
| 0x1082 | coin | Enabled if playing coin runners. |
| 0x1083 | not_coin | Enabled if playing any other than coin runners. |
| 0x1084 | versus | Enabled if playing versus. |
| 0x1085 | not_versus | Enabled if playing any other than versus. |
| 0x1086 | itemrain | Enabled if playing item rain. |
| 0x1087 | not_itemrain | Enabled if playing any other than item rain. |
DEFINITION_OBJECT if MODE=1
The DEFINITION_OBJECT is one element of KMP:GOBJ with an OBJECT_ID in range from 0x2000 to 0x2fff. 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.
There are 2 great advantages of this model:
- This extension can use the 128 bits of settings of a DEFINITION_OBJECT, and if needed, other members too. So it is important to use the default values for as explained in the table below!
- 1 DEFINITION_OBJECT can be used for many standard objects of different types. So standard objects are grouped into functionality groups.
- it is possible, that a DEFINITION_OBJECT uses another object by setting the REFERENCE_ID. So chains of definitions are possbile if ever needed.
Usage 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 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. |
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 (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. |
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. |
Behavior of 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 (mode!=1), LE-CODE aborts the processing does nothing.
- If REFERENCE_ID is between 0x1000 and 0x1fff), a hard coded CONDITION is found. If is either evaluated as ACTIVE or as INACTIVE. The processing is continued with step 2.
- Otherwise, if REFERENCE_ID is not valid (not inside range 0x2000 and 0x2fff), LE-CODE aborts the processing does nothing.
- Otherwise the REFERENCE_ID is between 0x2000 and 0x2fff.
- If a DEFINITON_OBJECT is found, its CONDITIONS are evaluated.
- Otherwise, no CONDITIONS are defined and 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 MKWii recognizes the object (if bit 13 not set) and use it like usual.
- If the object is inactive, OBJECT_ID, REFERENCE_ID and PRESENCE_FLAGS are set to value 0. So MKWii ignores the object at least because of invalid OBJECT_ID.
Examples
Here are some examples to make understanding easier:
- Define an object, that is only used by standard code.
- Set MODE=1 and REFERENCE_ID to value 0x1000 (=always disabled).
- Define an object, that is only used by LE-CODE
- Set MODE=1, set bit 12 of the OBJECT_ID and set REFERENCE_ID to value 0x1001 (=always enabled). LE-CODE will clear bit 12 to make the object valid.
- 2 alternative objects: 1 for standard code and 1 for LE-CODE
- Define a standard object. Set MODE=1 and REFERENCE_ID to value 0x2000 (=always disabled).
- Define a second object. Set MODE=1, set bit 12 of the OBJECT_ID and set REFERENCE_ID to value 0x2001 (=always enabled). LE-CODE will clear bit 12 to make the object valid.
- 2 alternative objects: 1 for single player at Wii, another for multiple players at Wii.
- Define a standard object. Set REFERENCE_ID to 0x2101. 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 1 player if running standard code. LE-CODE will activate it based on the CONDITIONS.
- Define a standard object. Set REFERENCE_ID to 0x2102. 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 2-4 players if running standard code. LE-CODE will activate it based on the CONDITIONS.
- 2 alternative objects: 1 for offline and 1 for online.
- Define a standard object. Set REFERENCE_ID to 0x2201. Define a DEFINITION_OBJECT with CONDITIONS for online only and this id. Set PRESENCE_FLAGS to 0x103f (MODE=1). This object is active if running standard code. LE-CODE will activate it based on the CONDITIONS.
- Define a standard object and set bit 12 of the OBJECT_ID. Set REFERENCE_ID to 0x2202. Define a DEFINITION_OBJECT with inverted CONDITIONS of above (offline only) and this id. Set PRESENCE_FLAGS to 0x103f (MODE=1). This object is disabled if running standard code. LE-CODE will activate it based on the CONDITIONS.
Software support
LE-CODE
Implentation in progress. Already implemented:
- Support of LEX section TEST.
- Simulation part of different scenarios controlled by LEX section TEST.
- Detection if game is online or offline.
- Count number of total players if online.
- Patching of OBJECT_ID, REFERENCE_ID and PRESENCE_FLAGS after analysis of all settings.
Not implemented yet and harder to find out:
- Number of players at local Wii
- Game mode: Versus, Time trial, Balloon battle or Coin runners.
Wiimms SZS Tools
Wiimm planned software support for his SZS Tools:
- New warnings will be added to »wkmpt check«.
Already implemented (compare change log):
- The KMP text processor detects DEFINITION_OBJECTS and displays them in an alternative view including some hints and statistics.
- The KMP parser+compiler accepts alternative syntax for entering DEFINITION_OBJECTS: Commands $DEFOBJ-BATTLE and $DEFOBJ-RACE will define DEFINITION_OBJECTS. Command $REFERENCE adds an REFERENCE_ID to the current object.
- The KMP parser+compiler can fix wrong REFERENCES and DEFINITION_OBJECTS, and can sort them in various ways.
- wkmpt check: New hints for usage of MODES>0 added.
- New command: wkmpt GAMEMODES: Analyze the presence flags combinations with and without extension support and print a list.
- New command: wszst DUPLICATE: It reads a single track file and duplicates it several times. Therefor it analyzes the presence flags combinations with and without extension support and creates one file for each relevant scenario. A LEX section TEST will be inserted to force the execution mode for offline tests.
- LEX: A new section named »TEST« was added. It contains variables to force conditions like "10 players online" even if 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 will help to define and calculate CONDITIONS and DEFINITION_OBJECTS.
- Track statistics about the usage of this extension.
- In the distant future a special web page is planned: The user uploads some tracks and defines some parameters. Then the website creates a LE-CODE distribution, where the track is included in many variants, where the settings of LEX:TEST varies to cover all CONDITIONS.
KMP Tools
All KMP tools must be checked to see 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).
Tools that either directly work on the file itself (like the SZS Modifier), which is not recommended, or tools like Wiimms SZS Tools (in any version) that load the entire GOBJ section into a structure, including padding, will properly keep the additional data in the KMP when editing. Other tools that try to be smart and verify the OBJECT_ID (KMP Cloud, KMP Modifier) and/or ignore the seemingly unused padding (KMP Cloud, KMP Modifier, Lorenzi's KMP Editor, Wexos's Toolbox and probably more) will break KMP files that use these features — these tools should be updated.
| 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 | [1] | ✖ | ✖ | [2] | ✖ | ✖ | ✔ | ✔ | ✖ | ✖ |
| KMP Modifier | kHacker35000vr | [3] | ✖ | ✖ | [2] | ✖ | ✖ | ✔ | ✔ | ✖ | ✖ |
| KMP3D | zatchi | ? | ? | ✖ | ? | ? | ✖ | ? | ? | ✖ | ✖ |
| Lorenzi's KMP Editor | Hlorenzi | ✔ | ✔ | ✖ | [2] | ✖ | ✖ | ✔ | ✔ | ✖ | ✖ |
| SZS Modifier | Chadderz | ✔ | ✔ | ✖ | ✔ | [4] | ✖ | ✔ | ✔ | ✖ | ✖ |
| Wexos's Toolbox | Wexos | ✔ | ✔ | ✖ | [2] | ✖ | ✖ | ✔ | ✔ | ✖ | ✖ |
| Wiimms SZS Tools | Wiimm | ✔ | ✔ | v2.11 | ✔ | ✔ | v2.11 | ✔ | ✔ | v2.11 | v2.11 |
- Column 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.
- Status Notes
- [1]: KMP Cloud clears the high unused bits of the object id.
- [2]: KMP Cloud, KMP Modifier, Lorenzi's KMP Editor and Wexos's Toolbox ignore the padding completely and set all paddings to value 0 if writing the KMP.
- [3]: KMP Modifier doesn't accept unknown objects, prints a warning for each such object and set OBJECT_ID to 0.
- [4]: SZS Modifier prints padding as decimal value, but scans it as hexadecimal value. So editing this member is complicated.
- v2.11: Already implemented in Wiimms SZS Tools. Will be available with the next release.
Implementation hints
For implementation hints read Presence_flag/Extension/Implementation_hints.