Presence flag/Extension

From Custom Mario Kart
Jump to: navigation, search
Lecode-ver-36x160.png

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:

Bit Groups and usage
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.
  • MODE=0: Standard mode, no special processing by LE-CODE or other extensions.
  • MODE=1: LE-CODE mode ⇒ process OBJECT_ID, CONDITIONS and PRESENCE_FLAGS.
  • MODE=2–3: Reserved for a future LE-CODE/LEX extension.
  • MODE=4–15: Reserved.

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:

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:

DEFINITION_OBJECT: Usage of data members
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:

DEFINITION_OBJECT: Usage of Settings
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:

CONDITION bits
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.

KMP tools and their support of extended presence flags
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.