Bundles many assets into a single file with compression, string tables, and other game-related special handling functions.
A .pak file is written at build time and streamed in at runtime. Each asset package is "baked" from a configuration source file. Example:
Rust code
PakBuf::bake("game_art.toml", "game_art.pak")?;When generating bake inputs into a build/artifact directory, keep those generated files outside the source tree and pass the source asset root explicitly:
PakBuf::bake_with_dir(
out_dir.join("generated/game_art.toml"),
out_dir.join("game_art.pak"),
manifest_dir.join("assets"),
)?;The explicit directory is used for asset globs, project-rooted asset paths, and pak keys. The
existing PakBuf::bake(src, dst) API remains available and uses the content file's parent
directory as before.
game_art.toml:
[content]
compression = 'snap'
[[content.group]]
assets = [
'bitmap/**/*.png',
'font/**/*.toml',
'mesh/**/*.toml',
'sound/**/*.ogg',
'music/*.mp3',
'ui/*.png',
]All fields are optional.
| Item | Description |
|---|---|
| compression | 'snap', 'brotli', or unspecified (no compression). |
| buffer-size | (unsigned integer) Brotli buffer size. Used only when compression = 'brotli'. Defaults to 4096. |
| quality | (unsigned integer) Brotli compression quality. Used only when compression = 'brotli'. Defaults to 8. |
| window-size | (unsigned integer) Brotli window size. Used only when compression = 'brotli'. Defaults to 22. |
All fields are optional.
Note:
Additional [[content.group]] tables may be appended. All groups are added to the package and these
individual groups are not distinct entities in the runtime file.
| Item | Description |
|---|---|
| assets | (string array) File paths or glob patterns of assets to bake. Assets may be native file types (such as .png and .glb) or asset (.toml) files as detailed in the following sections. |
| exclude | (string array) File paths or glob patterns to exclude from the baking process when considering assets. |
| enabled | (boolean) Global flag which may be used to prevent baking of this group. |
Bone structures and per-channel frame sample data may be loaded from .gltf or .glb files.
Example, cool-walk.toml:
[animation]
src = 'some_file.gltf'Or to simply load some_file.gltf using some_file.toml:
[animation]All fields are optional.
| Item | Description |
|---|---|
src |
File path to a .gltf or .glb animation. May be relative to the [animation] TOML file or absolute where the root is the same folder as the [content] TOML file. When unspecified, attempts to load an animation with the same name as the [animation] TOML file. |
name |
Specific animation name (for use with files containing more than one animation). |
exclude |
Array of animation channel names to exclude from the import. |
Geometry may be loaded from .gltf or .glb files.
Example, large-goblet.toml:
[mesh]
src = 'some_file.gltf'
lod = true
max-index = 'u16'All fields are optional.
| Item | Description |
|---|---|
data |
File path to an optional unstructured byte blob associated with this mesh. |
src |
File path to a .gltf or .glb mesh. May be relative to the [mesh] TOML file or absolute where the root is the same folder as the [content] TOML file. When unspecified, attempts to load a mesh with the same name as the [mesh] TOML file. |
euler |
(string) Order of operations applied to 3-channel rotation values (example: xyz, zyx, etc). |
flip-x |
(boolean) When set, flips the X component of all position vertices. |
flip-y |
(boolean) When set, flips the Y component of all position vertices. |
flip-z |
(boolean) When set, flips the Z component of all position vertices. |
ignore-skin |
(boolean) When set, any embedded skin data is ignored. |
lod |
(boolean) When set, generates level of detail meshes using MeshOpt. |
lod-lock-border |
(boolean) When set, tells MeshOpt to generate level of detail meshes using only interior vertices. |
lod-target-error |
(float) When set, tells MeshOpt to attempt to hit a certain error threshold between level of detail meshes. |
max-index |
(string or unsigned integer) When set, reduces and compacts the baked mesh so no LOD references an index greater than this value. Accepts 'u8', 'u16', or an exact value such as 4095 or 65535. Uses MeshOpt simplification and may reduce the base mesh before generating LODs. |
min-lod-triangles |
(unsigned integer) When set, tells MeshOpt to stop generating level of detail meshes below this threshold. |
name |
(string) When set, imports this named mesh. Otherwise, imports the first mesh. |
normals |
(boolean) When set (default true), imports geometry normals. |
offset |
(array of float with a length of 3) When set, offsets geometry positions by the given amount. |
optimize |
(boolean) When set (default true), reorders geometry indices and vertices using MeshOpt. |
overdraw-threshold |
(float) When set (default 1.05), controls MeshOpt optimization. |
rotation |
(array of float with a length of 3 or 4) When set, the vector (XYZ) or quaternion (XYZW) rotation applied to geometry. |
scale |
(float or array of float with a length of 3) When set, the uniform or vector (XYZ) scale applied to geometry. |
scene-name |
(string) When set, controls which GLTF scene is imported from the source file. |
shadow |
(boolean) When set, imports position-only geometry optimized for use in shadow or other similar rendering techniques. |
tangents |
(boolean) When set (default true), imports geometry tangents. If missing, tangents are generated using the MikkTSpace algorithm |
max-index is a hard cap on the maximum index value, not just a triangle-count target. If a mesh initially needs indices above the cap, baking simplifies the mesh and compacts the vertex buffer so IndexBuffer can store the result as u8 or u16 where possible. Lower generated LODs are derived from the capped mesh.
Arbitrary files may be baked as raw byte blobs.
Example, nav-data.toml:
[blob]
src = 'nav-data.bin'All fields are optional.
| Item | Description |
|---|---|
src |
File path to the blob. May be relative to the [blob] TOML file or absolute where the root is the same folder as the [content] TOML file. When unspecified, attempts to load a blob with the same name as the [blob] TOML file. |
Material data for use in rendering.
All fields are optional.
Example, glowing-lava.toml:
[material]
color = 'my-texture.png'| Item | Description |
|---|---|
color |
Hex string, path string, inline bitmap asset, or sequence. |
height |
Hex string, path string, inline bitmap asset, or floating point value. |
double-sided |
(boolean_) When set, indicates the material is double-sided. |
emissive |
Hex string, path string, inline bitmap asset, or array of three floating point values. |
metal |
Hex string, path string, inline bitmap asset, or floating point value. |
normal |
Path string or inline bitmap asset. |
rough |
Hex string, path string, inline bitmap asset, or floating point value. |
transmission |
Hex string, path string, inline bitmap asset, or floating point value. |
When any material parameter is set, MaterialInfo::params stores the packed RGBA parameter map as R = metal, G = rough, B = height, and A = transmission. MaterialInfo::params_used indicates which channels were authored; missing channels are default-filled.
Variable-channel bitmap data (stored raw and compressed using the setting of the [content] compression).
Example, ui-skin-001.toml:
[bitmap]
src = 'my-texture.png'All fields are optional.
| Item | Description |
|---|---|
src |
File path to an image. May be relative to the [bitmap] TOML file or absolute where the root is the same folder as the [content] TOML file. When unspecified, attempts to load a bitmap with the same name as the [bitmap] TOML file. |
mip-levels |
(boolean or non-zero unsigned integer) When set (default 1), allows configuration of the desired count of mip levels to be stored with a bitmap for later use by a program. |
resize |
(unsigned integer) When set, the image is uniformly resized to have this maximum dimension. |
color |
(string) When set (default srgb), the image is imported as either linear or srgb color data. |
swizzle |
(string) When set (default rgba for four channel images), the specified image color channels are imported in the given order (example: r, rg or bgr). |
Special handling is given to [bitmap-font] asset files.
Example, font-h4.toml:
[bitmap-font]
src = 'blocky-letters.fon'The specified file is imported as a raw AngelCode bitmap font file, and any associated page images are loaded as bitmaps.
All fields are optional.
| Item | Description |
|---|---|
src |
File path to a bitmap font definition. May be relative to the [bitmap-font] TOML file or absolute where the root is the same folder as the [content] TOML file. When unspecified, attempts to load a bitmap font definition with the same name as the [bitmap-font] TOML file. |
Scene files may contain custom geometry and spatial reference data, each with the ability to store generic data as well.
Example, large-castle.toml:
[scene]
[[scene.ref]]
id = 'EnemySpawn'
rotation = [0.0, 0.0, 0.0, 1.0]
translation = [-1.0, 0.1, -6.0]
tags = [
'bot',
]
data.type = 'monster3'
[[scene.ref]]
id = 'red-door'
rotation = [0.0, 0.0, 0.0, 1.0]
translation = [-0.9, 0.0, -12.0]
tags = [
'door',
]
data.require = 'red-key'
data.joins = 'a,b'
[[scene.ref]]
mesh = '../kaykit/dungeon/floor_tile_large_grates.toml'
materials = [
'../kaykit/dungeon/texture.toml',
]
rotation = [0.0, 0.0, -0.0, 1.0]
translation = [0.0, 0.0, -0.0]
[[scene.ref]]
mesh = '../kaykit/dungeon/floor_tile_large.toml'
materials = [
'../kaykit/dungeon/texture.toml',
]
rotation = [0.0, 0.0, -0.0, 1.0]
translation = [6.0, 0.0, -2.0]
[[scene.geometry]]
id = 'a'
indices = [
2, 0, 1,
1, 3, 4,
9, 11, 8,
1, 4, 9,
5, 2, 1,
12, 10, 6,
6, 5, 1,
6, 1, 9,
13, 14, 12,
12, 6, 9,
8, 13, 12,
9, 8, 12,
]
vertices = [
-8.399999618530273, 0.0, 7.400000095367432,
6.400000095367432, 0.0, 7.400000095367432,
-8.399999618530273, 0.0, -7.400000095367432,
6.400000095367432, 0.0, -7.400000095367432,
1.0, 0.0, -7.400000095367432,
-3.0, 0.0, -7.400000095367432,
-2.4000000953674316, 0.0, -8.0,
1.0, 0.0, -7.400000095367432,
-0.09999996423721313, 0.0, -11.40000057220459,
0.3999999761581421, 0.0, -8.0,
-2.4000000953674316, 0.0, -11.40000057220459,
0.3999999761581421, 0.0, -11.40000057220459,
-1.9000000953674316, 0.0, -11.40000057220459,
-0.09999996423721313, 0.0, -12.0,
-1.9000000953674316, 0.0, -12.0,
]
rotation = [0.0, 0.0, -0.0, 1.0]
translation = [1.0, 0.10000000149011612, -0.0]
tags = [
'nav-mesh',
]
[[scene.ref]]
id = 'Camera'
rotation = [0.06613656878471375, -0.8706687092781067, 0.4718790054321289, 0.12203358113765717]
translation = [-19.0, 61.0, -53.0]
tags = [
'camera',
]
data.type = 'persp'
data.z-near = 1.0
data.z-far = 200.0
data.fov-y = 0.349344402551651All fields are optional.
| Item | Description |
|---|---|
[[scene.geometry]] |
Inline indexed triangle geometry tables. |
[[scene.ref]] |
Scene reference tables for meshes, materials, transforms, tags, and custom data. |
| Item | Description |
|---|---|
id |
(string) Optional identifier. It is not required to be unique. |
euler |
(string) Order of operations applied to 3-channel rotation values (example: xyz, zyx, etc). |
indices |
(array of unsigned integer) Triangle index list. Length must be a multiple of 3. |
rotation |
(array of float with a length of 3 or 4) Euler XYZ degrees or quaternion XYZW rotation. |
translation |
(array of float with a length of 3) Translation applied to the geometry. |
vertices |
(array of float) Packed XYZ position values. |
tags |
(array of string) Program-specific tags. Tags are trimmed, lowercased, and sorted during baking. |
data |
TOML table of program-specific values. Values may be booleans, strings, i32 integers, floats, or arrays of those values. |
| Item | Description |
|---|---|
id |
(string) Optional identifier. It is not required to be unique. |
euler |
(string) Order of operations applied to 3-channel rotation values (example: xyz, zyx, etc). |
materials |
(array) Material asset references. Each entry may be a material TOML path, image path, or inline material asset. |
mesh |
Mesh asset reference. May be a mesh TOML path, .gltf/.glb path, or inline mesh asset. |
rotation |
(array of float with a length of 3 or 4) Euler XYZ degrees or quaternion XYZW rotation. |
translation |
(array of float with a length of 3) Translation applied to the reference. |
tags |
(array of string) Program-specific tags. Tags are trimmed, lowercased, and sorted during baking. |
data |
TOML table of program-specific values. Values may be booleans, strings, i32 integers, floats, or arrays of those values. |
Run tests with all features in order to include the baking code:
cargo test --all-features