Wexos: Imported from avsys wiki

2024-05-01T17:37:23Z

Imported from avsys wiki

New page

'''KCL''' files are collision files, which is the model the game runs collision against. KCL files has been used since at least [[Mario Kart DS]], but this documentation is about the format used in [[Nintendo DS]], [[Wii]] and [[Nintendo 3DS]]. The only differences is that [[Nintendo DS]] uses a specific format which replaces all floats. For other formats, see [[KCL (File Format)]].

KCL stores triangle in a format which allow fast access and collision calculation, and has an octree which splits the world space into many cubes, to make the game test collision on less triangles, which allows for much faster collision detection.

= File Format =
== Header ==
The header is a 0x3C byte structure as follows:

{| class="wikitable"
! Offset !! Type !! Description
|-
| 0x00 || UInt32 || '''Offset to [[#Vertices|vertex positions]]''', relative to the start of the file.
|-
| 0x04 || UInt32 || '''Offset to [[#Directional Vectors|directional vectors]]''', relative to the start of the file.
|-
| 0x08 || UInt32 || '''Offset to [[#Triangles|triangles]]''' - 0x10, relative to the start of the file. To get the actual offset, add 0x10 to this value. It works like this because the [[#Octree|octree]] triangle indices are 1-based.
|-
| 0x0C || UInt32 || '''Offset to [[#Octree|octree]]''', relative to the start of the file.
|-
| 0x10 || Float|| {{Unknown-left|'''Unknown'''. Always 300.}}
|-
| 0x14 || Float[3] || '''[[#Octree|Octree]] origin'''.
|-
| 0x20 || UInt32 || '''X mask'''.
|-
| 0x24 || UInt32 || '''Y mask'''.
|-
| 0x28 || UInt32 || '''Z mask'''.
|-
| 0x2C || UInt32 || '''Coordinate shift'''.
|-
| 0x30 || UInt32 || '''Y shift'''.
|-
| 0x34 || UInt32 || '''Z shift'''.
|-
| 0x38 || Float|| {{Unknown-left|'''Unknown'''. Always 250.}}
|}

=== Vertices ===
Section 1 is simply a large array of vertices, 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 0x0C.

=== Directional Vectors ===
Section 2 is much the same as section 1, in that it is a large array of directional vectors. 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 and dividing by 0x0C.

=== Triangles ===
The third section is the section containing the actual model information. The structure of each entry in this section is a 0x10 byte structure given below.

{| class="wikitable"
! Offset !! Type !! Description
|-
| 0x00 || Float || '''Length''' of triangle.
|-
| 0x04 || UInt16 || The index of the '''first vertex position''' into the [[#Vertices|vertex array]].
|-
| 0x06 || UInt16 || The index of the '''normal''' into the [[#Directional Vectors|directional vector array]].
|-
| 0x08 || UInt16 || The index of the '''direction A''' into the [[#Directional Vectors|directional vector array]].
|-
| 0x0A || UInt16 || The index of the '''direction B''' into the [[#Directional Vectors|directional vector array]].
|-
| 0x0C || UInt16 || The index of the '''direction C''' into the [[#Directional Vectors|directional vector array]].
|-
| 0x0E || UInt16 || '''Collision attributes'''.
|}

All indices in this section are 0 indexed. The position index is an index for section 1, and the others are indices 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.
<pre>
CrossA = Cross(DirectionA, Normal)
CrossB = Cross(DirectionB, Normal)
Vertex1 = Position
Vertex2 = Position + CrossB * (Length / Dot(CrossB, DirectionC))
Vertex3 = Position + CrossA * (Length / Dot(CrossA, DirectionC))
</pre>
A method for converting three vertices into the KCL form is given below. This method assumes the vertices are arranged anti clockwise when viewed from the collidable side.
<pre>
Position = Vertex1
Direction = Normalize(Cross(Vertex2 - Vertex1, Vertex3 - Vertex1 ))
DirectionA = Normalize(Cross(Normal, Vertex3 - Vertex1 ))
DirectionB = Normalize(-Cross(Normal, Vertex2 - Vertex1 ))
DirectionC = Normalize(Cross(Normal, Vertex2 - Vertex3 ))
Length = Dot(Vertex2 - Vertex1, DirectionC )
</pre>

=== Octree ===
The octree subdivides the world space into cubes, to allow much faster triangle collision detection. The number of root [[#Node|nodes]] can be calculated by the following algorithm:
<pre>
NrRootNodes = (~MaskX >> CoordinateShift + 1) * (~MaskY >> CoordinateShift + 1) * (~MaskZ >> CoordinateShift + 1)
</pre>

Then the number of root nodes are written to the file. These nodes link to more nodes or triangle lists.

==== Node ====
Each node has the following structure:

{| class="wikitable"
! Offset !! Type !! Description
|-
| 0x00 || UInt32 || '''Flag''': '''ABBB BBBB BBBB BBBB BBBB BBBB BBBB BBBB'''
'''A''': 1 means it's a leaf. See below.<br>
'''B''': Offset to next structure, relative to the parent node, or start of octree data if the node is a root node.
|}

If the node is a leaf, then it means it isn't subdivided anymore and it contains triangle lists. This triangle list is terminated by 0, and contains 1-based indices of the [[#Triangles|triangles]] that are present in this subspace. If it's not a leaf, then this node is subdivided into 8 more nodes, which the offset into the structure links to.

= Tools =
The following tools can handle KCL files:
* [[Wexos's Toolbox]], by [[Wexos]] (Wii)
* [[Wiimms SZS Tools]], by [[Wiimm]] (Wii)

[[Category: 3DS File Formats]]
[[Category: DS File Formats]]
[[Category: Wii File Formats]]

KCL (File Format)/Wii - Revision history

Wexos: Imported from avsys wiki