Skip to content

KN5 file format⚓︎

KN5 is the binary 3D model format used by Assetto Corsa for cars and tracks. One file contains every texture, every material and a tree of nodes holding the meshes.

  • Byte order


    Little-endian

  • Offsets


    None. Everything is read sequentially, because almost all data is variable-length.

  • Strings


    ACString: a 4-byte length followed by UTF-8 bytes

  • Structure


    Header, textures, materials, then one recursive node tree

At a glance⚓︎

flowchart LR
    H[Header] --> T[Textures] --> M[Materials] --> N[Root node]
    N --> C1[NODE] --> C2[MESH]
    N --> C3[NODE]
    N --> C4[NODE] --> C5[NODE] --> C6[MESH]
    N --> C7[SKINNED_MESH]

KsEditor flattens all nodes & meshes for tracks, which yields better performance. With cars, nodes can have any amount of sub-nodes before the mesh. This is also possible (and valid) for tracks but not advised. If you need more sub-nodes (for example to move them around), you can wrap meshes instead.

Type notation used on this page
Name Meaning Size
byte unsigned 8-bit integer 1
ushort unsigned 16-bit integer 2
uint unsigned 32-bit integer 4
int signed 32-bit integer 4
float IEEE 754 single 4
float[16] 4×4 matrix 64

In the Size columns, var means the size depends on the data and n is the element count read just before.


ACString⚓︎

Every name in the file uses this string type.

Size Type Name Description
4 int size Number of bytes in value
size char[size] value UTF-8 text, not null-terminated

Note

size counts bytes, not characters. Names may contain UTF-8 symbols.


Size Type Name Description
6 char[6] prefix Always sc6969
4 uint version Format version
4 uint key Only present if version > 5

Which version should I write?

Use version = 5 for new files. Versions above 5 add the key field, which is used by cars from paid DLCs for integrity verification.

Seen in the wild

A track-object file with version = 6 had key = 0, so a version above 5 does not necessarily carry a real key.


Textures⚓︎

Size Type Name Description
4 uint texturesSize Number of textures
var Texture[texturesSize] textures Textures, one after another

Texture⚓︎

Size Type Name Description
4 uint state Always 1
var ACString name Texture file name, for example lights.dds
4 uint size Size of the texture data in bytes
size byte[size] data The complete texture file, embedded as is

Textures are whole files

In the sample, data starts with DDS, the magic of a DDS file. You can write it out unchanged to get the original texture back.


Materials⚓︎

Size Type Name Description
4 uint materialsSize Number of materials
var Material[materialsSize] materials Materials, one after another

Material⚓︎

Size Type Name Description
var ACString name Material name
var ACString shader Shader name, for example ksPerPixel
1 byte blend Blend mode
1 byte alpha_tested Alpha test enabled
4 uint depth_mode Depth mode
4 uint propertiesSize Number of properties
var MaterialProperty[propertiesSize] properties Shader properties
4 uint resourcesSize Number of resources
var MaterialResource[resourcesSize] resources Texture bindings

Every property stores the same 10 floats, whichever one the shader actually uses.

Size Type Name Description
var ACString name Property name
4 float v1 Scalar value
8 float[2] v2 Vector2 value
12 float[3] v3 Vector3 value
16 float[4] v4 Vector4 value
Size Type Name Description
var ACString name Resource name, for example txDiffuse
4 uint slot Texture slot
var ACString texture Name of the texture (matches Texture.name)

Shader ksPerPixel, blend = 0, alpha_tested = 0, depth_mode = 0.

Property v1 v2, v3, v4
ksAmbient 0.588 all 0
ksDiffuse 0.588 all 0
ksSpecular 0.9 all 0
ksSpecularEXP 10 all 0
ksEmissive 0 all 0
ksAlphaRef 0 all 0

One resource: txDiffuse, slot 0, texture lights.dds.

Scalar properties use only v1, the other floats are zero.


Nodes⚓︎

The file ends with a single root node. Nodes form a tree, and only NODE entries have children.

Value Name Meaning
1 NODE Parent node with a transformation
2 MESH Regular mesh, no transformation
3 SKINNED_MESH Skinned mesh

Reading order

The tree is read depth-first. A NODE is followed immediately by its children, so there is no child table or offset to jump to.

What a real tree looks like

NODE  "FBX: finish200.FBX"      identity transform, 2 children
├── NODE  "AC_OPEN_FINISH_L"    1 child
│   └── MESH  "AC_OPEN_FINISH_L"
└── NODE  "AC_OPEN_FINISH_R"    1 child
    └── MESH  "AC_OPEN_FINISH_R"

The root is a NODE named after the source FBX file. Each mesh sits below its own NODE, which positions it, and the mesh itself has childrenSize = 0.

Common fields⚓︎

Every node starts with these, and the class value decides which fields follow.

Size Type Name Description
4 uint class NodeClass, see table above
var ACString name Node name
4 uint childrenSize Number of children (used by NODE)
1 byte active Node is active

Fields by node class⚓︎

Size Type Name Description
64 float[16] transform 4×4 transformation matrix
var Node[childrenSize] children Child nodes, read recursively

Matrix layout

The 16 floats are stored row by row, and the translation is in the last row (floats 12 to 14). The identity matrix therefore looks like this:

1 0 0 0
0 1 0 0
0 0 1 0
0 0 0 1   ← translation x, y, z in the first three

In the sample, a node at position (227.006, -1.101, -21.687) stores exactly those three values as floats 12, 13 and 14.

Size Type Name Description
1 byte castShadows
1 byte isVisible
1 byte isTransparent Transparent meshes are rendered last, without depth testing
4 uint verticesSize Number of vertices
44 × n MeshVertex[verticesSize] vertices See vertex layouts
4 uint indicesSize Number of indices
2 × n ushort[indicesSize] indices Triangle indices, three per triangle
4 uint materialID Index into the material list
4 uint layer 0: always rendered. 1 and higher: depends on the world detail setting. Use 0 for cars.
4 float lodIn Not really relevant for cars
4 float lodOut Not really relevant for cars
12 float[3] bsCenter Bounding sphere center
4 float bsRadius Bounding sphere radius
1 byte isRenderable 1 normally, 0 for physics-only meshes on tracks

Sample mesh

A unit box, 1 × 1 × 1 with its base on the XY plane: 24 vertices (4 per face) and 36 indices (2 triangles per face), castShadows = 1, isVisible = 1, isTransparent = 0, layer = 0, lodIn = lodOut = 0.

The bounding sphere has center (0, 0, 0.5) and radius 0.866, which is the distance from the box center to a corner. So the sphere encloses the whole mesh.

Size Type Name Description
1 byte castShadows
1 byte isVisible
1 byte isTransparent Rendered last, without depth testing
4 uint bonesSize Number of bones
var Bone[bonesSize] bones See Bone
4 uint verticesSize Number of vertices
76 × n SkinnedMeshVertex[verticesSize] vertices See vertex layouts
4 uint indicesSize Number of indices
2 × n ushort[indicesSize] indices Triangle indices
4 uint materialID Index into the material list
4 uint layer Same as for MESH
4 float lodIn
4 float lodOut

Differences from MESH

Skinned meshes have no bounding sphere and no isRenderable field.

Not verified

The sample file has no skinned meshes, so this layout comes from an existing parser template only.

Bone⚓︎

Size Type Name Description
var ACString name Bone name
64 float[16] transform 4×4 matrix

Vertex layouts⚓︎

Offset Type Name
0x00 float[3] pos
0x0C float[3] normal
0x18 float[2] uv
0x20 float[3] tangent

In the sample, normal and tangent are unit length, and the uv V values run from 0 to -1, so V appears to be flipped.

Offset Type Name Description
0x00 float[3] pos
0x0C float[3] normal
0x18 float[2] uv
0x20 float[3] tangent
0x2C float[4] weights Bone weights
0x3C float[4] indices Bone indices

Warning

indices are stored as floats, not integers.


Worked example⚓︎

The first bytes of a real file, up to the start of the texture data.

Bytes Field Value
73 63 36 39 36 39 prefix sc6969
06 00 00 00 version 6
00 00 00 00 key 0 (present because version > 5)
01 00 00 00 texturesSize 1
01 00 00 00 Texture.state 1
0A 00 00 00 name.size 10
6C 69 67 68 74 73 2E 64 64 73 name.value lights.dds
80 54 05 00 Texture.size 349312
44 44 53 20 ... data DDS and the rest of the DDS file

And the root node, which starts right after the last material:

Bytes Field Value
01 00 00 00 class 1 (NODE)
12 00 00 00 name.size 18
46 42 58 3A 20 66 69 6E 69 73 68 32 30 30 2E 46 42 58 name.value FBX: finish200.FBX
02 00 00 00 childrenSize 2
01 active 1
00 00 80 3F 00 00 00 00 ... transform identity matrix, 64 bytes