KCL (File Format)
KCL Files are collision files used in Mario Kart Wii and many other games. They have been used since at least Mario Kart DS. The documentation here is specifically for the Mario Kart Wii implmentation, although other implmentations are likely to be similar.
The KCL files contain simplified versions of model files in order to allow rapid collision detection. They use an octree for efficient spatial indexing, as well as storing the actual triangles of the models in a more rapidly accessible format.
Available editors:
File Format
The basic file format consists of a header, and four data sections.
Header
The header is a 0x3c byte structure as follows.
| Offset | Type | Description |
|---|---|---|
| 0x00 | u32 | Offset to section 1 |
| 0x04 | u32 | Offset to section 2 |
| 0x08 | u32 | Offset to section 3 |
| 0x0c | u32 | Offset to section 4 |
| 0x10 | single | Unknown (300.0 typical) |
| 0x14 | single3 | Spatial grid first coordinate |
| 0x20 | u32 | X mask |
| 0x24 | u32 | Y mask |
| 0x28 | u32 | Z mask |
| 0x2c | u32 | Coordinate shift |
| 0x30 | u32 | Y shift |
| 0x34 | u32 | Z shift |
| 0x38 | single | Unknown (250.0 typical) |
All offsets are relative to the start of the file.
The meaning of the shift and mask values is explained in section 4.
Section 1 - Verticies
Section 1 is simply a large array of verticies, stored as 3 successive singles for x, y and z. The length of this array is not stored, but can usually be calculated by subtracting the section 1 offset from the section 2 offset and dividing by 0xc.
Section 2 - Normals
Section 2 is much the same as section 1, in that it is a large array of normals. Again the values are stored as 3 successive singles for x, y and z. The length of this array is not stored, but can usually be calculated by subtracting the section 2 offset from the section 3 offset + 0x10 and dividing by 0xc.
Section 3 - Triangles
The third section is the section containg the actual model information. The offset to this section is stored as 0x10 less than the actual location of the data, because this section is one indexed in section 4. The strcutre of each entry in this section is a 0x10 byte strcutre given below.
| Offset | Type | Description |
|---|---|---|
| 0x00 | single | Length |
| 0x04 | u16 | Position index |
| 0x06 | u16 | Direction index |
| 0x08 | u16 | Normal A index |
| 0x0a | u16 | Normal B index |
| 0x0c | u16 | Normal C index |
| 0x0e | u16 | Collision flags |
All indicies in this section are 0 indexed. The position index is an index for section 1, and the others are indicies to section 2. The exact manner in which the values are used for collision detection is unknown, however a method for converting this form of triangle to a set of three coordinates is outlined below. The coordinate system is right handed.
Vertex1 = Position Vertex2 = Position + Cross(Direction, NormalA) * (Length / Dot(NormalA, NormalC)) Vertex3 = Position + Cross(NormalB, Direction) * (Length / Dot(NormalB, NormalC))
A method for converting three verticies into the KCL form is given below. This method assumes the verticies are arranged anti clockwise when viewed from the collidable side.
Position = Vertex1 Direction = Cross(Normalize(Vertex2 - Vertex1), Normalize(Vertex3 - Vertex1)) Length = Dot(Normalize(Vertex2 - Vertex1), Direction) NormalA = Cross(Direction, Normalize(Vertex2 - Vertex1)) NormalB = Cross(Normalize(Vertex3 - Vertex1), Direction) NormalC = Cross(Direction, Normalize(Vertex3 - Vertex2))
Section 4
Section 4 is a spatial index. It is a series of u32 values, followed by lists of u16s. It subdivides three dimensional space using an octree, and indicates which triangles from section 3, if any, appear in each cube of the space. Given a coordinate (x,y,z) in world space, in order to find which triangles are at in range of that location, the spatial gird first coordinate is subtracted from the coordinate. If the value is negative, it is not colliding. If the value is positive, it is rounded to a u32, and then each component is ANDed with the mask. If the value is non zero, it is also not colliding. If not, the the original u32 components are all shifted right by coordinate shift. The y and z coordinates are then shifted left by their shift values. The resulting components are ORed with each other to produce an index into the octree.
The octree is then to be followed until a triangle list is found. At each stage, if the top bit of the current u32 is set, then the remaining 31 bits are an offset to a list of u16 triangle indicies. Each of these is a 1 based index to section 3, which is a triangle that must be checked by an object at the original location. The list is 0 terminated. If the top bit is not set, then the remaining 31 bits are an offset to 8 more of the u32s in the octree. The index into these 8 values is calculated by getting the next least significant bit in the u32 of each component, and then shifting z left by 2, y left by 1 and oring them all together. The procedure then repeats with the value at that offset.
Mario Kart Wii Collision Flags
In Mario Kart Wii the collision flag values are normally split. The 5 least significant bits determine the basic type of the flag. The next 11 bits determine the variation upon the type. The list below describes these types and their variants.
Collision Types
| Type | What is it? |
|---|---|
| 0x00 | Road |
| 0x01 | Weak off road |
| 0x02 | Very weak offroad with a dirt effect |
| 0x03 | Offroad |
| 0x04 | Heavy offroad with a sand effect |
| 0x05 | Off road |
| 0x06 | Boost |
| 0x07 | Fast trick |
| 0x08 | Trick ramp |
| 0x09 | Out of bounds |
| 0x0A | Solid fall |
| 0x0B | Shallow Water (weak offroad, like on Shy Guy Beach) |
| 0x0C | Wall |
| 0x0D | Wall, but makes no sound effect when touched. Sparks still appear. |
| 0x0E | Does nothing |
| 0x0F | Normal wall |
| 0x10 | Fall boundary |
| 0x11 | Cannon Activator |
| 0x12 | Does nothing |
| 0x13 | Half-Pipe blue ramp (like the ones on DK Summit) |
| 0x14 | Normal Wall |
| 0x15 | Moving terrain |
| 0x16 | Sticky Road |
| 0x17 | Road, slightly different than 0x00 |
| 0x18 | Sound Trigger |
| 0x19 | Does nothing |
| 0x1A | Music channel activator??? |
| 0x1B | Does nothing |
| 0x1C | Does nothing |
| 0x1D | Gravelroad |
| 0x1E | Spin-out when touched |
| 0x1F | Wall |
Variants
Here comes a list with variants, they are also used by kcl files and control the effects. Thanks to bigoto for the list
Road (0x00)
| ID | What is it? |
|---|---|
| 000 | Normal Road |
| 001 | Dirt Road |
| 002 | Sand |
| 003 | Slippery Road |
| 004 | Wood Road |
| 005 | Snow Road |
| 006 | Metal Grid/Chain Link Road |
| 008 | Concrete Road (slightly different than 000) |
| 00B | Ice Road |
| 10x | Trickable road |
| 20x | No drivable road |
Tickable road: x = road variant (ex. 104 is trickable wood road)
No drivable road: means you can't drive further, you will be pushed back if you try it. Can be used to determine boundaries or very pronounced slopes.
Off road (0x03)
| ID | What is it? |
|---|---|
| 000 | Dirt |
| 002 | Mud |
| 004 | Grass |
| 008 | Weak Dirt |
| 00C | Grass with bigger effect (more plants come out) |
Wall (0x0C)
| ID | What is it? |
|---|---|
| 000 | Normal Wall |
| 001 | Rock Wall |
| 002 | Metal Wall |
| 003 | Guard Rail |
| 004 | Short tree wall sound effect |
| 005 | Tree Wall |
| 006 | Tree Wall without leaf effect |
| 007 | Rubber Wall |
| 008 | Hollow Wall |
| 159 | Wall without being bumped |
Fall Boundary (0x10)
| ID | What is it? |
|---|---|
| 000 | Air fall |
| 001 | Water (activates pocha) |
Road (0x17)
| ID | What is it? |
|---|---|
| 002 | Sand sound, with dirt effect |
| 003 | Same as 0x00 variant 000, but the sound it makes is in a lower tone |
| 00A | Dirt effect |
| 10x | Trickable road |
| 20x | Not drivable road |