KMP (File Format)

From Custom Mario Kart
Jump to navigation Jump to search
KMP
File formats
Lists
Tutorials
Tools

Overview

A KMP file contains information about how a track is played, such as start positions and checkpoints. A variant on the KMP format has been used in Mario Kart DS. This article describes the Mario Kart Wii KMP format. The Mario Kart 7 KMP format is described here.

File Header

This is the general layout for a KMP header:

File header of a KMP file
Offset Type Description
0x00 String File magic.
0x04 UInt32 Length of the file in bytes.
0x08 UInt16 N = Number of sections in the file.
0x0A UInt16 L = Header length.
L - N * 0x04 - 0x04 UInt32 Version number. Different version numbers may cause different behavior of all sections; exact effects are unknown. The value in most Mario Kart Wii KMP files is 0x9D8 (2520). For Mario Kart 7 KMP files, it is 0x1C0C (le) = 3100.
L - N * 0x04 UInt32[N] N section offsets. The type of each section can be detected by analyzing the first four bytes of the section; it is always the section name. The offset is relative to the end of this header.
L End of this file header

Mario Kart Wii specific file header

This is specific file header for Mario Kart Wii tracks. It is a structure with 0x4C (=76) bytes. Some files like old_mario_gc_hayasi.szs have a different section layout.

File header of a typical Mario Kart Wii KMP file
Offset Type Description
0x00 String File magic. Always RKMD in ASCII.
0x04 UInt32 Length of the file in bytes.
0x08 UInt16 Number of sections in the file (15).
0x0A UInt16 The length of the header in bytes. This value is usually 0x4C.
0x0C UInt32 Version number. Different version numbers may cause different behavior of all sections; exact effects are unknown.
The value for most KMP files in Mario Kart Wii is 0x9D8 (2520). Other tracks found in the game files have earlier KMP versions: draw_demo is 0x910 (2320) and loser_demo is 0x9CE (2510); both including their multiplayer "_d" variants. Additionally, old_mario_gc_hayasi and old_mario_gc_yabuki is 0x0640 (1600), and old_mario_gc_narita's KMP has no version number.
The game's code supports other KMP versions newer than old_mario_gc_hayasi / narita's and older than draw_demo's, but none of the tracks in the game use any of those KMP versions.
0x10 UInt32 KTPT section offset (starting positions of racers).
0x14 UInt32 ENPT section offset (enemy route points).
0x18 UInt32 ENPH section offset (divide enemy points into groups).
0x1C UInt32 ITPT section offset (item route points).
0x20 UInt32 ITPH section offset (divide item points into groups).
0x24 UInt32 CKPT section offset (checkpoints).
0x28 UInt32 CKPH section offset (divide checkpoints into groups).
0x2C UInt32 GOBJ section offset (geo objects).
0x30 UInt32 POTI section offset (routes).
0x34 UInt32 AREA section offset (areas).
0x38 UInt32 CAME section offset (cameras).
0x3C UInt32 JGPT section offset (respawn positions).
0x40 UInt32 CNPT section offset (cannon target positions).
0x44 UInt32 MSPT section offset (end battle positions).
0x48 UInt32 STGI section offset (stage information).
0x4C End of this file header

All offsets are relative to the end of the header. The section order is irrelevant for the game, but all Mario Kart Wii tracks use this section order. You can swap those sections and the track will still work.

Sections

The file consists of a series of sections, each describing a different aspect of a track. Each section has a header and entries. The header structure is equal for all sections. The section order of this page reflects the order of the KMP files.

Section header for all KMP sections
Offset Type Description
0x00 String The section name in ASCII.
0x04 UInt16 Number of entries.
0x06 UInt16 Additional value. The POTI section stores the total number of points of all routes. The CAME section stores different values (see CAME section for details). For all other sections, the value is 0 (seems to be padding).
0x08 End of header and start of first entry

KTPT

The KTPT (kart point) section describes kart points; the starting position for racers.

Each entry is a 0x1C byte structure as follows:

Offset Type Description
0x00 Float[3] A 3D position vector of the start position.
0x0C Float[3] A 3D rotation vector of the start position.

The related start line of the minimap is not mirrored in Mirror Mode. It is recommended to only use multiples of ±90° (one of 0°, ±90°, ±180°, or ±270°) for the Y-rotation. See Start Line Bug for details.

0x18 Int16 The player index.

For races, the first entry is used to define a start area, independent of its value (usually set to -1=0xffff). See Start Position for details.

In battle arenas, the value determines which players start here. Values 0 to 5 are for the red team and values 6 to 11 are for the blue team. The order of the entries is irrelevant.

0x1A UInt16 Padding.
LE-CODE Logo (Vertical).png

For races (not battle) and Time Trials, the first entry independent of the player index is used to define the positions of all 12 drivers. There are two flags in section STGI to place the drivers a little bit closer and to define the pole position (left or right). See Start Position for more details.

With LE-CODE, an additional KTPT entry with player index = -1 can be used to define the start line position on the minimap.

ENPT

The ENPT (enemy point) section describes enemy points; the routes of CPU racers. The CPU racers attempt to follow the path described by each group of points (as determined by ENPH). More than 0xFF (255) entries will force a console freeze while loading the track.

Each entry is a 0x14 byte structure as follows:

Offset Type Description
0x00 Float[3] A 3D position vector of the enemy position.
0x0C Float This value controls how much the enemies leave the direct point-to-point line to the left and right side.
0x10 UInt16 Point setting 1. ENPT Settings.
0x12 Byte Point setting 2. ENPT Settings.
0x13 Byte Point setting 3. ENPT Settings.

ENPH

The ENPH (enemy path) section describes enemy point grouping; how the routes of CPU racers link together.

Each entry is a 0x10 byte structure as follows (same structure as ITPH and CKPH):

Offset Type Description
0x00 Byte Point start. The index of the first ENPT entry in this group.
0x01 Byte Point length. The number of ENPT entries in this group.
0x02 Byte[6] Previous group. The indices of up to six the previous ENPH group entries may have followed. Unneeded slots are set to value 0xFF. Theses values are used if a driver drives back or is respawned at an position before falling down.
0x08 Byte[6] Next group. The indices of up to six next ENPH group entries to follow. Unneeded slots are set to value 0xFF. Each driver uses one route randomly, but a shortcut item can be set as a condition (see ENPT Settings). To increase the probability of one route, enter the section index more than once.
0x0E Short Always 0 in racing tracks. A non-zero bit for bits 0 to 5 means that the group is linked to the first point of the respective previous group. A non-zero bit for bits 6-11 means that the group is linked to the last point of the respective next group.
Note

In Battle Mode, all 12 groups linked to a specific group are treated as a next group. The bitfield at 0x0E determines how the groups are linked. For details, see Enemy routes in battle arenas.

ITPT

The ITPT (item point) section describes item points; the Red Shell and Bullet Bill routes. The items attempt to follow the path described by each group of points (as determined by ITPH). More than 0xFF (255) entries will force a console freeze while loading the track.

Each entry is a 0x14 byte structure as follows:

Offset Type Description
0x00 Float[3] A 3D position vector of the item position.
0x0C Float The Bullet Bill can be controlled a little bit by left and right. This value defines the range. Factor 1 allows about 10 units of left and right movement.
0x10 UInt16 Point properties 1. ITPT Settings.
0x12 UInt16 Point properties 2. ITPT Settings.

ITPH

The ITPH (item path) section describes item point grouping; how the item routes link together. When all previous or next group indices are set to 0xFF, the game assumes the order of points as they appear in the ITPT section.

Each entry is a 0x10 byte structure as follows (same structure as ENPH and CKPH):

Offset Type Description
0x00 Byte Point start. The index of the first ITPT entry in this group.
0x01 Byte Point length. The number of ITPT entries in this group.
0x02 Byte[6] Previous group. The indices of up to six the previous ITPH groups entries may have followed. Unneeded slots are set to value 0xFF. Theses values are used if a driver drives back or is respawned at a position before falling down.
0x08 Byte[6] Next group. The indices of up to six next ITPH group entries to follow. Unneeded slots are set to value 0xFF. The first link is the standard route. The other links are only used if a driver enters the route or if a Red Shell has already selected a driver. LE-CODE supports a random selection of the standard route by defining LEX section RITP.
0x0E UInt16 Padding.

CKPT

The CKPT (checkpoint) section describes checkpoints; the routes players must follow to count laps. The racers must follow the path described by each group of points (as determined by CKPH). More than 0xFF (255) entries are possible if the last group begins at index ≤254. This is not recommended because Lakitu will always appear on-screen.

Each entry is a 0x14 byte structure as follows:

Offset Type Description
0x00 Float[2] A 2D position vector (X and Z coordinate) of the left point of the checkpoint line.
0x08 Float[2] A 2D position vector (X and Z coordinate) of the right point of the checkpoint line.
0x10 Byte Respawn position. This is a zero-based index link into the JGPT section to respawn players at once they have entered this checkpoint. For the lap count trigger and for the key checkpoints, it is important that the respawn point is before the checkpoint.
0x11 SByte Checkpoint type (see notes below).
0x12 Byte Previous checkpoint in this group's sequence; 0xFF for the first point of the group.
0x13 Byte Next checkpoint in this group's sequence; 0xFF for the last point of the group.

The checkpoint area is a quadrilateral created by the two points of the current checkpoint and the two points of the next checkpoint. At the end of these groups, all CKPH-linked points are used to create multiple checkpoint areas. A checkpoint is triggered if a player enters (one of) this quadrilateral.

Checkpoints are separated in three type classes:

  • Lap count trigger (type 0): When passed in the right direction, it increases the lap count; if you pass in the reverse direction, it decreases the lap count. All players start in lap zero, where passing the start line increases to lap one. The shown lap number is the maximal reached one and never smaller than one. If two or more lap counters exist, the track has a Position Jump Bug: each player is in first place after crossing any lap counter with the effect of bad items.
  • Key checkpoint (types 1 – 127): If you cross key checkpoint 01, you need to follow all other key checkpoints in order to increase the lap count. This type is used to prevent Ultra Shortcuts. These kind of checkpoints is also relevant for respawning if falling down far away from other checkpoints. A good idea is to place key checkpoint directly before and behind the lap count trigger.
  • Normal checkpoint (type -1): Used for setting respawn points and checking which position you are in.

For more details, see Check Point. It explains the quadrilateral model.

CKPH

The CKPH (checkpoint path) section describes checkpoint grouping; how the routes of checkpoints link together.

Each entry is a 0x10 byte structure as follows (same structure as ENPH and ITPH):

Offset Type Description
0x00 Byte Point start. The index of the first CKPT entry in this group.
0x01 Byte Point length. The number of CKPT entries in this group.
0x02 Byte[6] Previous group. The indices of up to six the previous CKPH groups entries may have followed. Unneeded slots are set to value 0xFF.
0x08 Byte[6] Next group. The indices of up to six next CKPH group entries to follow. Unneeded slots are set to value 0xFF.
0x0E UInt16 Padding.

GOBJ

LE-CODE Logo (Horizontal).png

The GOBJ (geo object) section describes objects; things such as item boxes, pipes, trees and so on.

Each entry is a 0x3C byte structure as follows:

Three axes of the coordinate system
Offset Type Description
0x00 UInt16 Object ID to identify the object. See Object or the KMP object query.

Setting the value to an unknown ID (this includes value 0) will disable the object entirely. Bits 12 and 13 (mask 0x3000) are used as a special feature for extended presence flags.

0x02 UInt16 Padding. This is part of the extended presence flags. Make sure the value is zero if this object does not use the extension.
0x04 Float[3] A 3D position vector of the object.
0x10 Float[3] A 3D rotation vector of the object's rotation in degree.
0x1C Float[3] A 3D scale vector of the object's scale. Value 1.0 is the neutral scale.
0x28 UInt16 Route used by the object. This is the index link for the POTI section. The value 0xFFFF means "no route".
0x2A UInt16[8] Up to eight object specific settings. See Object for details.
0x3A UInt16 Presence flags. Nintendo defines bits 0–5 (mask 0x3f). The other bits (6–15, mask 0xffc0) will be used for extended presence flags. Make sure these bits are cleared if this object does not use the extension.
0x3C End of an object and start of the next object

Each object has a origin. The origin is a well defined point. If it is placed directly on the ground, the position of the object is perfect. For example, the item box has its origin about 50 units below the lowest visible point. The positioning of objects is done in this order:

  1. First, an object is scaled around the origin. See the picture on the right for the axes. For some animated objects like the item box, the scale factors are ignored.
  2. Then, the object is rotated. The rotation is done in three steps. For some animated objects, the rotation values are ignored.
    1. Right-handed rotation around the X-axis using the X-coordinate of the 3D vector.
    2. Right-handed rotation around the Y-axis using the Y-coordinate of the 3D vector.
    3. Right-handed rotation around the Z-axis using the Z-coordinate of the 3D vector.
  3. As the last operation, the object is shifted to the position (the origin is set to the position coordinates). For some objects with a route, the start position is the first (or indexed) point of the route.

POTI

The POTI (point information) section describes routes; these are routes for many things including cameras and objects.

Each entry is a 0x04 byte structure as follows, which is followed by 0x10 byte structures:

Route Header
Offset Type Description
0x00 UInt16 Number of points in the route.
0x02 Byte Route setting 1, 0 or 1 in Nintendo's tracks.
  • 0: Object or camera goes directly from point to point with a hard direction change.
  • 1: Enables a smooth motion. The game will freeze if this setting is used on a route with two or less points.
0x03 Byte Route setting 2, 0 or 1 in Nintendo's tracks.
  • 0: Use route cyclic (go to first point after leaving last point).
  • 1: Use route forward, then backward, then forward, and so on.

Each point in each entry is as follows:

Route Points
Offset Type Description
0x00 Float[3] A 3D position vector of the route position.
0x0C UInt16 Route point settings. If used for speed or time, the value is based of 1/60s.
0x0E UInt16 Additional settings, depending on the object. Values found in Nintendo's tracks: 0 (~94%), 1, 2, 3, 4, 5, 6, 9, 12.

AREA

The AREA (area) section describes areas; used to determine which camera to use, for example. The size is 5000 for both the positive and negative sides of the X and Z-axes, and 10000 for only the positive side of the Y-axis.

Each entry is a 0x30 byte structure as follows:

AREA entry data structure (0x30 bytes)
Offset Type Description
0x00 Byte Area shape. 0 = box, 1 = cylinder.
0x01 Byte Area type. Values 0–A.
0x02 Byte Index of CAME if type = 0x00, 0xFF else.
0x03 Byte Priority value. A higher number means a higher priority to choose which area activates if multiple areas are intersected.
0x04 Float[3] A 3D position vector of the area.
0x10 Float[3] A 3D rotation vector of the area's rotation.
0x1C Float[3] A 3D scale vector of the area's scale.
0x28 UInt16 AREA setting 1. Used by AREA type 2, 3, 6, 8 and 9.
0x2A UInt16 AREA setting 2. Used by AREA type 6 and 3.
0x2C Byte Route ID used by AREA type 3.
0x2D Byte Enemy point ID. This value is used by AREA type 4.
0x2E UInt16 Padding? Always 0 in Nintendo tracks.

The list can be found in the XML file /Race/Course/koopa_course.szs/course.0. Only use it for hints on how it can work: 

	menu      AREAtype  7
	item      Camera  0
	item      ObjClip  1
	item      EfControl  2
	item      FogControl  3
	item      PullControl  4
	item      EnemyFall  5
	item      2DmapArea  6

CAME

The CAME (camera) section describes cameras; used to determine cameras for starting routes, Time Trial pans, etc.

The U8 at offset 0x06 in the section header is the index of the first camera to use in the opening pan around the track. Usually, a sequence of three cameras of type 5 (with route) is used, but a single camera of type 1 without any route is possible too. The U8 value at offset 0x7 in the section header is the first camera used in track selection menu videos of the track. This value is ignored, as the videos have already been generated and stored.

Each entry is a 0x48 byte structure as follows:

CAME entry data structure (0x48 bytes)
Offset Type Description Box name in
SZS Modifier 		Names in
Wiimms Tools 		Column name in
KMP Modifier 		Box name in
KMP Cloud
0x00 Byte Camera type. Settings
(box 1, first 2 digits) 		type Type Type
0x01 Byte Next camera entry index. Value 0xFF means: no next camera. Settings
(box 1, second 2 digits) 		next Next Next
0x02 Byte Camshake. Exact meanings unknown (always 0). Settings
(box 1, third 2 digits) 		unknown Shake Shake
0x03 Byte Route used by the camera. This is index link into the POTI section. The value 0xFF means "no route". Settings
(box 1, last 2 digits) 		route Route Route
0x04 UInt16 Velocity of the camera point in units per 100/60 sec (=distance/1.67 sec). Settings
(box 2, first 4 digits) 		v(came) V(Cam) Pointspeed
0x06 UInt16 Velocity of zooming in units per 100/60 sec (=units/1.67 sec) (tested with camera type 5). Settings
(box 2, last 4 digits) 		v(zoom) V(Zoom) Zoomspeed
0x08 UInt16 Velocity of the view point in distance per 100/60 sec (=distance/1.67 sec) (tested with camera type 5). Settings
(box 3, first 4 digits) 		v(v.pt) V(View) Viewspeed
0x0A Byte Start flag. Exact meanings unknown. Settings
(box 3, third 2 digits) 		unknown Flag
(First 2 digits) 		Start
0x0B Byte Movie flag. Exact meanings unknown. Settings
(box 3, last 2 digits) 		unknown Flag
(Second 2 digits) 		Movie
0x0C Float[3] A 3D position vector of the camera. X, Y and Z position (x,y,z) X, Y and Z PositionX, PositionY and PositionZ
0x18 Float[3] A rotation 3D vector. Almost always 0,0,0. X2, Y2 and Z2 rotation (x,y,z) Roll, Yaw and Pitch RotationX, RotationY and RotationZ
0x24 Float Zoom start: The angle of view (field of view). Angles >180 create curious effects. X3 zoom beg Zoom Zoomstart
0x28 Float Zoom end. The camera changes the zoom to this value. Offset 0x06 (Velocity) controls the speed of zooming. Y3 zoom end Zoom2 Zoomend.
0x2C Float[3] Start vector of the view point (camera type 5) or the relative camera position (camera type 3). Z3, X4 and Y4 view point beg (x,y,z) View(x), View(y) and View(z) ViewStartX, ViewStartY and ViewStartZ
0x38 Float[3] (Destination) vector of the view point. Z4, X5 and Y5 view point end (x,y,z) View2(x), View2(y) and View2(z) ViewEndX, ViewEndY and ViewEndZ
0x44 Float The time how long this Camera is active. (in units of 1/60 seconds). Z5 sec*60 Time Time

The list can be found in the XML file /Race/Course/koopa_course.szs/course.0. Only use it for hints on how it can work: 

	menu      CAMType  9
	item      Goal  0
	item      FixSearch  1
	item      PathSearch  2
	item      KartFollow  3
	item      KartPathFollow  4
	item      OP_FixMoveAt  5
	item      OP_PathMoveAt  6
	item      MiniGame  7
	item      MissionSuccess  8

JGPT

The JGPT (jugem point) section describes "Jugem" points; the respawn positions. The index is relevant for the link of the CKPT section.

Each entry is a 0x1C byte structure as follows:

Offset Type Description
0x00 Float[3] A 3D position vector of the respawn position.
0x0C Float[3] A 3D rotation vector to define the direction for the players.
0x18 UInt16 The ID of this respawn position. For all Nintendo tracks, the value is set to the index. The usage is unknown and links of the CKPT section points to the index and are not related to this ID (tested by Wiimm).
0x1A Int16 Extra user data. Hundreds value minus one is the ID of the sound to trigger (see Sound Trigger) after respawning the player. Only used if this field is greater than 0. The final two decimal digits of the field represent a value that seems to be used to adjust the respawn points on Delfino Pier as the water level rises in some way.

Read Respawn Point for more information and hints about placing respawn points.

CNPT

The CNPT (cannon point) section describes cannon points; the cannon target positions.

Each entry is a 0x1C byte structure as follows:

Offset Type Description
0x00 Float[3] A 3D destination of the cannon. This point defines a destination tangent or border of a ball around the cannon, which is the landing zone. (Think of a 2D circle with a cannon in the middle.)
0x0C Float[3] A 3D angle vector of the direction to release players from the cannon in. The second value (Y-rotation from cannon start point) is the most important value because it declares the shooting direction. The players fly in the entered direction until they reach the defined tangent.

If the X value is >0.0 and ≤100.0, it is possible that a driver turns right or left if landing. See this video as an example.

0x18 UInt16 The ID of this cannon position. For all Nintendo tracks, the value is set to the index. This value seems to be irrelevant. For the KCL flag, the zero-based index is important.
0x1A Int16 Shoot effect: 0 (same as -1 or 0xFFFF) is straight, 1 is curved, 2 is curved and slow. See Cannon Properties for details.
How to calculate the Y-rotation
  • First, find out the cannon point and call it "P1". It is the middle of the cannon area in the KCL.
  • Now find out the destination point and call it "P2".
  • The horizontal direction is now calculated by: atan2( P2.x - P1.x, P2.z - P1.z ). Do not forget that many calculators use radiant instead of degree. If so, multiply the result by 180/π (~57.29578).
  • If atan2() is not available, atan( (P2.x-P1.x) / (P2.z-P1.z) ) can be used, but the sign of the result must be determined by yourself.
  • If using Wiimms KMP compiler, just enter hDir(P1,P2) in the place of the Y-value.

See Creating a Cannon for more details.

MSPT

The MSPT (mission success point) section describes end positions. After battles and tournaments have ended, the players are placed on this point(s).

Each entry is a 0x1C byte structure as follows:

Offset Type Description
0x00 Float[3] A 3D position vector of this point.
0x0C Float[3] A 3D angle vector of this point.
0x18 UInt16 The ID of this entry. For all Nintendo tracks, the value is set to the index. The usage is unknown.
0x1A UInt16 Unknown.

For battle arenas, four records are always defined.

STGI

The STGI (stage info) section describes stage information; information about a track.

Each entry is a 0x0C byte structure as follows:

Offset Type Description
0x00 Byte Lap count. Always 03 in Nintendo tracks. This byte was used in early development and is no longer in use, but it is still set correctly for all race tracks (03) and tournaments with a different lap count. There is a cheat code which makes the game use this value as lap count in normal races.
0x01 Byte 0: Pole position is left.
1: Pole position is right.
0x02 Byte 0: Normal distance.
1: Driver are closer together (in driving direction, narrow mode).
0x03 Byte 0x01 to enable lens flare flashing.
0x04 UInt32 Flare color, as defined in course.0. 0xE6E6E6 or 0xFFFFFF in Nintendo tracks. This is the lighting color that covers the screen by the lensFX object in RGB format.
0x08 Byte Flare transparency. 0x32 or 0x4B in Nintendo tracks. This is the alpha value for the lighting color.
0x09 UInt16 Always 0 in Nintendo tracks. The last byte is used as the first byte of a floating point for the speed modifier cheat code.
0x0B Byte Always 0 in Nintendo tracks (padding). This byte is used as the second byte of a floating point for the speed modifier cheat code.
Notes
  • The initial interpretation of this section is based on definitions in the XML file /Race/Course/koopa_course.szs/course.0.
  • See Start Position for more details about the pole position and the narrow mode.

Tools

The following tools can handle KMP files:

Modern Tools
Old Tools

SZS Modifier, KMP Modifier and KMP Cloud allow a GUI supported interactive modification of most parameters.

Wiimms SZS Tools converts a KMP file into a text representation including a small documentation. This text file can be edited with any editor or external tool. After modification, the text file must be encoded into the binary representation. This encoding is done by a parser and compiler. While encoding, some parameters are calculated/corrected automatically. This entire decoding/encoding process covers all KMP parameters and allow the usage of names, variables and numerical expressions instead of simple numbers. → How to edit KMP files

Retrieved from "https://wiki.tockdom.com/w/index.php?title=KMP_(File_Format)&oldid=454803"