Extended presence flags/Technical Description

From Custom Mario Kart
Jump to: navigation, search

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.

Bit Groups and usage
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.
  • MODE=0: Standard mode: No special processing by LE-CODE or other executor.
  • 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.

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. Therefor 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:

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:

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 multi 13_99 If total number of human players is greater or equal 13.
0x100c 1_18 ge13 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:

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_id0x2000. 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:

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

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:

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