KCL (File Format)

From Custom Mario Kart
Revision as of 18:53, 16 July 2011 by HelloImYourMind (Talk | contribs)

Jump to: navigation, search

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.


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


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)
00A Sand with shadow effect
00B Ice Road
00D Snow Road
10x Trickable road
20x No drivable road
0xy Effect properties

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.
Effect properties: x: Intensity. y: road variant (ex. 045 is Road with a big Snow effect. 145 is Trickable road with a big snow effect).

Weak off road (0x01)

ID What is it?
005 Sand
00D Sand with shadow effect
0xy Variant Sound Properties

Variant Sound Properties
x: Sound effect intensity (ex. 005 is Sand with a very audible effect, 045 makes the sound almost inaudible).
y: Variant

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)
00D Sand with shadow effect
0xy Intensity properties

Intensity properties
x: can be either effect strenght or sound strenght
y: offroad variant

Example: Variant 050 is a strong dirt-effect offroad. Variant 0CD makes the sand sound almost inaudible.

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
009 Wall without being bumped
40x The "bump" depends on the angle you hit the wall.

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
005 Same as above, sound is like drifting on glass
00A Dirt effect
10x Trickable road
20x Not drivable road

Gravelroad (0x1D)

ID What is it?
000 Gravel
004 Gravel (different sound)
00A Normal Road (like 0x00)
00B Glass road with echo
00C Gravel with shadow effect