pak 0.7.1

An easy-to-use data pak format for games.
Documentation

.pak Asset Crate

Crates.io Docs.rs

Bundles many assets into a single file with compression, string tables, and other game-related special handling functions.

A .pak file is baked at build time and streamed in at runtime.

.pak Configuration File

Each asset package is "baked" from a configuration source file. Example:

Rust code

PakBuf::bake("game_art.toml", "game_art.pak")?;

game_art.toml:

[content]
compression = 'snap'

[[content.group]]
assets = [
    'bitmap/**/*.png',
    'font/**/*.toml',
    'mesh/**/*.toml',
    'sound/**/*.ogg',
    'music/*.mp3',
    'ui/*.png',
]

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.

[content] Schema

Item Description
compression (Optional) 'snap' or 'brotli'

3D Animations

Bone structures and per-channel frame sample data may be loaded from .gltf or .glb files.

Example:

[animation]
src = 'some_file.gltf'

Or to simply load some_file.gltf using some_file.toml:

[animation]

[animation] Schema

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.

3D Meshes

Geometry may be loaded from .gltf or .glb files.

Example:

[mesh]
src = 'some_file.gltf'

[mesh] Schema

All fields are optional.

Item Description
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 boke structure 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.
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 (array of float with a length of 3) When set, the 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 similiar rendering techniques.
tangents (boolean) When set (default true), imports geometry tangents. If missing, tangents are generated using the MikkTSpace algorithm

PBR Materials

Material data for use in rendering.

Example:

[material]
color = 'my-texture.png'

[material] Schema

Item Description
color Hex string, path string, inline bitmap asset, or seqeunce.
displacement (Optional) Hex string, path string, inline bitmap asset, or floating point value.
double-sided (Optional, boolean) When set, indicates the material is double-sided.
emissive (Optional) Hex string, path string, inline bitmap asset, or array of three floating point values.
metal (Optional) Hex string, path string, inline bitmap asset, or floating point value.
normal (Optional) Path string or inline bitmap asset.
rough (Optional) Hex string, path string, inline bitmap asset, or floating point value.

Bitmaps

Variable-channel bitap data (stored raw and compressed using the setting of the [content] compression).

Example:

[bitmap]
src = 'my-texture.png'

[bitmap] Schema

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 uniformally 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).

Bitmap Fonts

Special handling is given to [bitmap-font] asset files.

Example:

[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.

[bitmap-font] Schema

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.

Scenes

Scene files may contain custom geometry and spatial reference data, each with the ability to store generic data as well.

Example:

[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.349344402551651

Tests

Run tests with all features in order to include the baking code:

cargo test --all-features