KMP (File Format)

From Custom Mario Kart
Revision as of 16:00, 11 August 2015 by Omonimo747 (talk | contribs)
Jump to navigation Jump to search
KMP
File formats
Lists
Tutorials
Tools

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:

File header of a KMP file
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. The value of MK7 KMP files is 0x1c0c (le) = 3100
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.

File header of a typical MKW track KMP file
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 (2520), with 2 exceptions: The value for draw_demo.txt is 0x910 (2320), and for loser_demo.txt it's 0x9ce (2510); both incl. "_d" variant.
0x10 4 KTPT section offset (Starting positions of racers).
0x14 4 ENPT section offset (Enemy route points).
0x18 4 ENPH section offset (Divide enemy points into groups).
0x1C 4 ITPT section offset (Item route points).
0x20 4 ITPH section offset (Divide item points into groups).
0x24 4 CKPT section offset (Check points).
0x28 4 CKPH section offset (Divide checkpoints into groups).
0x2C 4 GOBJ section offset (Global objects).
0x30 4 POTI section offset (Routes).
0x34 4 AREA section offset (Camera and other areas).
0x38 4 CAME section offset (Cameras).
0x3C 4 JGPT section offset (Respawn positions)
0x40 4 CNPT section offset (Cannon target positions).
0x44 4 MSPT section offset (End battle positions).
0x48 4 STGI section offset (Stage information).
0x4c End of this file header

All MKWii tracks use this section order, but it is irrelevant for the game. 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 the course. Each section has a header and entries. The header structure is equal for all sections:

Section header for all KMP 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 (kart point) 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 The player index. 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.

For races (not battle) and time trial always the first entry independent of the player index is used to define the positions of all 12 drivers. There are 2 flags in section STGI to place the drivers a little bit closer and to define the pool position (left or right). See »Start Position« for more details.

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). Each entry is a 0x14 byte structure as follows.

Offset Type Description
0x00 vector 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 short Point properties. ENPT Settings
0x12 short Point properties. ENPT Settings

ENPH

The ENPH (enemy path) 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 (item point) 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 Bullet Bill can be controlled a little bit by left and right. And this value defines the range. Factor 1 allows about 10 units left and right movement.
0x10 short Point properties. ITPT Settings
0x12 short Point properties. ITPT Settings

ITPH

The ITPH (item path) 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 (checkpoint) 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 (X and Z coordinate) of the left point of the check point line.
0x08 vector A 2D position vector (X and Z coordinate) of the right point of the check point 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 check points it is important, that the respawn point is before (>1000 units) the check point.
0x11 byte Checkpoint type (see notes below).
0x12 byte Previous check point in this group's sequence; 0xff for the first point of the group.
0x13 byte Next check point in this group's sequence; 0xff for the last point of the group.

The check point area is a quadrilateral created by the 2 points of the current check point and the 2 points of the next check point. For end of groups, all by CKPH linked points are used to create multiple check point areas. A check point is triggered, if a player enters (one of) this quadrilateral.

Checkpoints are separated in 3 type classes:

  • Lap count trigger (type 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. If 2 or more lap counters exist, the track has an online positioning bug: Each player is counted as position 1 after crossing any lap counter with the effect of bad items.
  • Key checkpoint (types 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. A good idea is to place a key check point directly before and another behind the lap count trigger.
  • Normal checkpoint (type FF): Used for setting respawns and checking in which position you are. It may effects more.

⇒ For more details, see article »Check Point«, that explains the quadrilateral model.

CKPH

The CKPH (checkpoint path) 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 (game object) 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 to identify the Object. See »Object« or »KMP Object Query«.
0x02 short Padding.
0x04 vector A 3D position vector of the object.
0x10 vector A 3D rotation vector of the object's rotation in degree.
0x1C vector A 3D scale vector of the object's scale. Value 1.0 is the neutral 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] Up to 8 object specific settings. See »Object«.
0x3A short Object presence flags. See »Object«.
0x3C End of object & start of 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 itembox has its origin about 50 units below the lowest visible point. The positioning of objects is done in this order:

  1. 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.
  2. Then the object is rotated. The rotation is done in three steps. For some animated objects the rotation values are ignored.
    1. 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 (into the direction of the positive values), then the fingers show the rotation direction.
    2. The the y-value is used for a rotation around the y-axis of the origin.
    3. The the z-value is used for a rotation around the z-axis of the origin.
  3. As 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 point of the route.

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.

Route Header
Offset Size Description
0x00 2 Number of points in the route.
0x02 1 Route setting 1, 0 or 1 in Nintendos tracks.
  • 0: Object or camera goes directly from point to point with a hard direction change.
  • 1: Enables a smooth motion.
0x03 1 Route setting 2, 0 or 1 in Nintendos tracks.
  • 0: Use route cyclic.
  • 1: Use route forward and than backward.

Each point in each entry is as follows.

Route Points
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/60s.
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.

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

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. 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 rotation vector to define the direction for the players.
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

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

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.

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

0x18 short The ID of this cannon position. For all Nintendo tracks the value is set to the index. This value seems do be irrelevant. For the KCL flag the zero based index is important.
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 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 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 0: Not defined. Disable Lakitu when driving backwards. Used in special files (winning_course) or competitions. Official name: "(null)"
1: No differences to 3 found. Official name: "Test"
2: No differences to 3 found. Official name: "MINI_GAME"
3: Standard race track. Official name: "Grandprix"

Values greater than 3 are not defined (only the lowest 2 bits are being used by the game).
Controls lap count in some Custom Track Distributions.

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 Unknown. 0 or 1 in Nintendo tracks.
0x04 u32 Maybe a color definition. 0xE6E6E6 or 0xFFFFFF in Nintendo tracks.
0x08 u16 Unknown. 0x3200 or 0x4B00 in Nintendo tracks.
0x0A u16 Unknown. Always 0 in Nintendo tracks.

This value is also used as speed modifier in some Custom Track Distributions. Therefore the 2 most significant bytes of the floating point speed factor are stored in this member.

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 (it is always 0x03 in Nintendo tracks). While this is not true in the context of the vanilla game, some distributions such as the CTGP-R and the CTT Pack have a code that allows the lap count to be modified using this setting, as the setting does not appear to have any other uses for settings 01 and higher. For competitions the lap count is set in the RKC file. The XML file /Race/Course/koopa_course.szs/course.0 clearly says that this byte is NOT the lap count.
  • See »Start Position« for more details about the pole position and the narrow mode.

Tools

The following tools can handle KMP files:

Modern Tools (in alphabetical order)
Old Tools


SZS Modifier, CTools Pack, 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 whole decoding/encoding process covers all KMP parameters and allow the usage of names and variables instead of integers. → How to edit KMP files

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