KMP (File Format)
A KMP File contains information about how the course is played, such as start positions and check points. A variant on the KMP format has been used in Mario Kart DS. This article describes the Mario Kart Wii KMP format.
File Header
This is the general layout for a KMP header:
Offset | Size | Description |
---|---|---|
0x00 | 4 | File magic, always 'RKMD' in ASCII |
0x04 | 4 | Length of the file in bytes. |
0x08 | 2 | N= Number of sections in the file. |
0x0a | 2 | Base offset for all sections. Add this value to all section offsets to get a file offset. |
0x0c | 4 | Unknown meaning, perhaps something like a revision number. |
0x10 | N*4 | N section offsets. The type of each section can be detected by analysing the first 4 bytes of the section; it's always the section name. Don't assume, that a section type is always at the same position. |
N*4 + 0x10 | End of this file header |
Mario Kart 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 an other section layout.
Offset | Size | Description |
---|---|---|
0x00 | 4 | File magic, always 'RKMD' in ASCII |
0x04 | 4 | Length of the file in bytes. |
0x08 | 2 | Number of sections in the file (15). |
0x0a | 2 | Base offset for all sections. Add this value to all section offsets to get a file offset. The value is usually 0x4c (76) and points to the end of this file header. |
0x0c | 4 | Unknown meaning, perhaps something like a revision number. The value for all KMP files in MKW is 0x9d8, with 2 exceptions: The value for draw_demo.txt is 0x910, and for loser_demo.txt it's 0x9ce (both incl. "_d" variant). |
0x10 | 4 | KTPT section offset. |
0x14 | 4 | ENPT section offset. |
0x18 | 4 | ENPH section offset. |
0x1C | 4 | ITPT section offset. |
0x20 | 4 | ITPH section offset. |
0x24 | 4 | CKPT section offset. |
0x28 | 4 | CKPH section offset. |
0x2C | 4 | GOBJ section offset. |
0x30 | 4 | POTI section offset. |
0x34 | 4 | AREA section offset. |
0x38 | 4 | CAME section offset. |
0x3C | 4 | JGPT section offset. |
0x40 | 4 | CNPT section offset. |
0x44 | 4 | MSPT section offset. |
0x48 | 4 | STGI section offset. |
0x4c | End of this file header |
Sections
The file consists of a series of sections, each describing a different aspect of the course. Each section has a header and entries. The header structure is equal for all sections:
Offset | Size | Description |
---|---|---|
0x00 | 4 | The section name in ASCII |
0x04 | 2 | Number of entries. |
0x06 | 2 | Additional value. The POTI section stores the total number of points of all routes. The CAME section store different values (see CAME section for details). For all other sections the value is always 0 (seems to be a padding). |
0x08 | End of header & start of first entry |
KTPT
The KTPT section describes kart points; the starting positions of racers. Each entry is a 0x1C byte structure as follows.
Offset | Type | Description |
---|---|---|
0x00 | vector | A 3D position vector of the start position. |
0x0C | vector | A 3D rotation vector of the start position. |
0x18 | short | Player ID. In courses with multiple start positions (such as battle courses), this determines which players start here. Otherwise set to 0xFFFF to set all players start positions to this point. |
0x1A | short | Padding. |
ENPT
The ENPT 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). Each entry is a 0x14 byte structure as follows.
Offset | Type | Description |
---|---|---|
0x00 | vector | A 3D position vector of the enemy position. |
0x0C | float | Scale |
0x10 | short | Point properties. ENPT Settings |
0x12 | short | Point properties. ENPT Settings |
ENPH
The ENPH section describes enemy points 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 indicies of up to 6 the previous ENPH groups entries may have followed. Unneeded slots are set to value -1. Theses values are used if a driver drives back or is respawned at an position before falling down. |
0x08 | byte[6] | Next group. The indicies of up to 6 next ENPH group entries to follow. Unneeded slots are set to value -1. Each driver uses one route randomly, but a short cut item can be set as condition (see ENPT Settings). To increase the probability of one route, enter the section index more than once. |
0x0e | short | Padding. |
ITPT
The ITPT section describes item points; the routes of items such as red shells. The items attempt to follow the path described by each group of points (as determined by ITPH). Each entry is a 0x14 byte structure as follows.
Offset | Type | Description |
---|---|---|
0x00 | vector | A 3D position vector of the item position. |
0x0C | float | Scale |
0x10 | short | Point properties. ITPT Settings |
0x12 | short | Point properties. ITPT Settings |
ITPH
The ITPH section describes item point grouping; how the routes of items link together. 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 indicies of up to 6 the previous ITPH groups entries may have followed. Unneeded slots are set to value -1. Theses values are used if a driver drives back or is respawned at an position before falling down. |
0x08 | byte[6] | Next group. The indicies of up to 6 next ITPH group entries to follow. Unneeded slots are set to value -1. 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. |
0x0E | short | Padding. |
CKPT
The CKPT section describes check points; the routes players must follow to count laps. The racers must follow the path described by each group of points (as determined by CKPH). Each entry is a 0x14 byte structure as follows.
Offset | Type | Description |
---|---|---|
0x00 | vector | A 2D position vector of the start of the check point line. |
0x08 | vector | A 2D position vector of the end of check point line. |
0x10 | byte | Respawn position. This is index link into the JGPT section to respawn players at once they have crossed this checkpoint. |
0x11 | byte | Checkpoint setting |
0x12 | byte | Last check point in this group's sequence. |
0x13 | byte | Next check point in this group's sequence. |
Checkpoint setting is separated in 3 types:
- Lap count trigger (00): When passed in right direction it increases the lap count, if you pass in reverse direction it decreases the lap count. All players start in lap 0 and after passing the line in lap 1. The shown lap number is the maximal reached one and never smaller than 1.
- Key checkpoint (01..FE): If you cross 01 you need to follow all in order before lap count trigger works. Used to prevent ultra shortcuts. These kind of check points is also relevant for respawning if falling down far away from other check points.
- Normal checkpoint (FF): Used for setting respawns and checking in which position you are. It may effects more.
CKPH
The CKPH section describes check point grouping; how the routes of check points 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 indicies of up to 6 the previous CKPH groups entries may have followed. Unneeded slots are set to value -1. |
0x08 | byte[6] | Next group. The indicies of up to 6 next CKPH group entries to follow. Unneeded slots are set to value -1. |
0x0E | short | Padding. |
GOBJ
The GOBJ section describes objects; things on the course such as item boxes, pipes and also control objects such as sound triggers. Each entry is a 0x3C byte structure as follows.
Offset | Type | Description |
---|---|---|
0x00 | short | Object ID. See Objects. |
0x02 | short | Padding. |
0x04 | vector | A 3D position vector of the object. |
0x10 | vector | A 3D angle vector of the object's rotation. |
0x1C | vector | A 3D scale vector of the object's scale. |
0x28 | short | Route used by the object. This is index link into the POTI section. The value 0xff (-1) means "no route". |
0x2A | short[8] | Object settings. See Objects. |
0x3A | short | Object presence flags. See Objects. |
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 itembox has its origin about 50 pixel below the lowest visible point. The positioning of objects is done in this order:
- First a object is scaled around the origin. The x-value is for width scaling, y for the height and z for the length (same directions as the map). For some animated objects like the itembox, the scale factors are ignored.
- The the item is rotated. The rotation is done in three steps. For some animated objects the rotation values are ignored.
- First the x-value (degree) is used to rotate the object around the x-axis of the origin. Take the right hand, let the thump show to the right (int the direction of the positive values), then the fingers show the rotation direction.
- The the y-value is used for a rotation around the y-axis of the origin.
- The the z-value is used for a rotation around the z-axis of the origin.
- As last operation the object is shifted to the position (the origin is set to the position coordinates).
POTI
The POTI section describes routes; these are routes for many things including cameras and objects.
Each entry is a 0x4 byte structure as follows, which is followed by 0x10 byte structures.
Offset | Size | Description |
---|---|---|
0x00 | 2 | Number of points in the route. |
0x02 | 1 | Route setting #1, 0 or 1 in Nintendos tracks.
|
0x03 | 1 | Route setting #2, 0 or 1 in Nintendos tracks.
|
Each point in each entry is as follows.
Offset | Type | Description |
---|---|---|
0x00 | vector | A 3D position vector of the route position. |
0x0C | short | Route point settings. If used for speed or time, the value is based of 1/60 sec. |
0x0E | short | Additional settings, depend on the object. Values found in Nintendos tracks: 0 (~94%), 1, 2, 3, 4, 5, 6, 9, 12. |
AREA
The AREA section describes areas; used to determine which camera to use for example. Each entry is a 0x30 byte structure as follows.
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. Use it only for hints 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 section describes cameras; used to determine cameras for starting routes, time trial pans, etc. The u8 value at offset 0x06 in the section header is the index of the first camera to use in the opening pan around the track. The u8 value at offset 0x7 in the section header is the first camera used in the videos on the track selection menu of the track. This value is ignored, as the videos have already been generated and stored.
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. Use it only for hints 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 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 | vector | A 3D position vector of the respawn position. |
0x0C | vector | A 3D angle vector of the direction to respawn players in. |
0x18 | short | 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 | short | Range |
- Some hints
- Place respawn points around the whole course. Don't think some think like "normally here can't anyone fall", because this assumption becomes faster false than you think. Mushrooms, Stars and Bullet Bill can throw you very high and wide. KCL bugs can do the same. And sometimes there are KCL holes.
- Link all respawn points by the CKPT points.
- Don't place respawn points to near to walls or other barriers, because the point becomes inexact if more than one player is repawned at same place and time.
- Set the horizontal direction correct. This is important for the enemies. If using Wiimms SZS Tools, give @HSNAP-TO-ENPT a chance.
- Never place a respawn point outside the course. Better is to set unused repawned anywhere over the road. But the best it, to remove such respawn points completely.
CNPT
The CNPT section describes cannon points; the cannon target positions. Each entry is a 0x1C byte structure as follows.
Offset | Type | Description |
---|---|---|
0x00 | vector | 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: 2D circle with the cannon in the middle.) |
0x0C | vector | 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 flight in the entered direction until they reach the defined tangent. |
0x18 | short | The ID of this cannon position. For all Nintendo tracks the value is set to the index. This value must be used in the KCL to make it work. |
0x1A | short | Shoot effect: 0xFFFF is straight, 0x0001 is curved, 0x0002 is curved AND slow, 0x0003 is slow. |
- 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 ). Don't forget, that many calculators use radiant instead of degree. If so, multiply the result by 180/π (~57.29578).
- If using Wiimms KMP compiler, just enter hDir(P1,P2) in the place of the y value.
MSPT
The MSPT section describes MSPT; After battles and competitions have ended the players are placed on this point(s). Each entry is a 0x1C byte structure as follows.
Offset | Type | Description |
---|---|---|
0x00 | vector | A 3D position vector of this point. |
0x0C | vector | A 3D angle vector of this point. |
0x18 | short | The ID of this entry. For all Nintendo tracks the value is set to the index. The usage is unknown. |
0x1A | short | Unknown. |
STGI
The STGI section describes stage information; information about the course. Each entry is a 0x0C byte structure as follows.
Offset | Type | Description |
---|---|---|
0x00 | byte | Lakitu. Always 0x03 in Nintendos tracks. |
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) |
0x03 | byte | Unknown. 0 or 1 in Nintendos tracks. |
0x04 | u32 | Maybe a color definition. 0xe6e6e6 or 0xffffff in Nintendos tracks. |
0x08 | u16 | Unknown. 0x3200 or 0x4b00 in Nintendos tracks. |
0x0a | u16 | Unknown. Always 0 in Nintendos tracks. |
- Notes
- The initial interpretation of this section is based on definitions in the XML file /Race/Course/koopa_course.szs/course.0. Some people made tests and change the parameters without detecting any impact except the 2 documented bytes → Resume: It seems that this section is a mostly unused relict of early development.
- Some people think that the byte at offset 0x00 controls the lap count (is always 0x03 in Nintendos tracks and the XML suggest it), but that's not true. For competitions the lap count is set in the RKC file.
Tools
The following tools can handle KMP files:
- CTools Pack, by Chadderz (announced)
- KMP Cloud, by Vulcanus2
- KMP Modifier, by kHacker35000vr
- SZS Modifier, by Chadderz
- Wiimms SZS Tools, by Wiimm
SZS Modifier, CTools Pack, KMP Modifier and KMP Editor 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. While encoding, some parameters are calculated/corrected automatically. This whole decoding/encoding process covers all KMP parameters and allow the usage of names and variables instead of integers. → How to edit KMP files