igasset: C++23 Game asset bundle format + decoder optimized for the web

Important

This repository is still under active migration from a closed-source module - it is incomplete, and documentation in this README file is slightly wrong. See Roadmap / TODO section below.

Features:

• Flatbuffer schemas for igasset / igpack files.
  • Web-optimized game formats + appropriate metadata for unloading in game engines
  • Flatbuffers for low-complexity type-safe serialization/deserialization
• Compressed asset storage types:
  • 3D geometry - Draco (IN PROGRESS)
  • Images / textures
    • RGBA8 Uncompressed
    • Various supercompressed formats via Basis Universal
  • WGSL shader source code - plain text
• igasset-gen tool for creating assets from existing formats
  • 3D geometry - FBX, glTF (1/2, incl. .glb), and OBJ via Assimp
  • Images - anything supported by stbi_image
• igpack-bundle tool for bundling existing *.igasset files into *.igpack bundles
• extract-asset-metadata tool for inspecting one file and reporting what it is, how igasset-gen can consume it, and which other files it depends on (see tools/extract-asset-metadata/README.md)

Building

There are three main CMake targets built:

• igasset - static library, WebAssembly-compatible.
• igasset-gen - binary (no WASM)
• igpack-bundle - binary (no WASM)

alongside the inspection utilities (enumerate-igasset, enumerate-igpack, enumerate-assimp, extract-asset-metadata - binaries, no WASM).

To use the generation tools or the decoder library within a project, run a native build using a typical CMake workflow.

igasset-gen and igpack-bundle cannot be built for WebAssembly - if you plan on using igasset in a WebAssembly project, compile the igasset-gen and igpack-bundle tools separately.

For loading existing igpack bundle files, use the igasset static library. Example:

// TODO (kamaron): example.

CMake Flags

Flag Name	Type + Default	Description
IGASSET_BUILD_GEN_TOOLS	ON (default) / OFF	Disable to skip building generator binaries and tooling dependencies
IGASSET_BUILD_IGASSET_DECODER	ON (default) / OFF	Disable to skip building the igasset library target
IGASSET_ENABLE_BASISU_SUPPORT	ON (default) / OFF	Disable to remove basisu support. Reduces binary size significantly

igasset-gen usage:

igasset-gen requires one input plan file path as the final positional argument:

igasset-gen [options] <input_plan_file>

Example:

igasset-gen                        \
  -i ./test_assets                 \
  -o ./bin/igassets                \
  --single-threaded                \
  ./tools/igasset-gen/test-definitions/copy-wgsl-source.igasset-gen.json

CLI options:

• -i, --input_asset_path_root Root directory used to resolve input asset file paths.
• -o, --output_path_root Root directory for generated *.igasset files.
• -m, --manifest Staged asset manifest (JSON). Present = every input read resolves through the manifest (deny-by-default for untrusted uploads); absent = direct local-file access. Setting IGASSET_REQUIRE_MANIFEST (any value other than 0) makes an absent manifest a hard error.
• -c, --clean Re-generate all outputs without cache reuse.
• --single-threaded Run generation on the main thread (useful for debugging / deterministic troubleshooting).
• -l, --log_level Log verbosity: ERROR, WARN, DEBUG, INFO, or TRACE.

Igasset generation plan files are written in JSON - see schema/igasset-gen-plan.fbs for the schema. Example plan file:

{
  actions: [
    {
      "action_type": "CopyWgslSourceAction",
      "action": {
        "input_file_path": "some-shader.wgsl",
        "output_file_path": "simple-wgsl.igasset",
        "vertex_entry_point": "vertex-main"
      }
    },
  ]
}

See igasset-gen E2E test-definitions folder for some examples.

igpack-bundle usage:

igpack-bundle also takes a list of flags, along with a positional argument to execute a single igpack-bundle.json plan file.

igpack-bundle [options] <input_plan_file>

Example:

igpack-bundle                        \
  -i ./bin/igassets                  \
  -o ./build/out                     \
  ./tools/igpack-bundle/e2e/test-definitions/all-distinct-assets.igpack-bundle.json

CLI options:

• -i, --input_asset_path_root Root directory used to resolve input igasset file paths.
• -o, --output_path_root Root directory for generated *.igpack files.
• -c, --clean Re-generate all outputs without cache reuse.
• -l, --log_level Log verbosity: ERROR, WARN, DEBUG, INFO, or TRACE.

Igpack bundle generation plan files are written in JSON - see schema/igpack-bundle-plan.fbs for the schema. Example plan file:

{
  "igpack_gen_actions": [
    {
      "output_path": "single-wgsl.igpack",
      "igasset_sources": [
        {
          "file_path": "simple-wgsl.igasset",
          "source_type": "WgslSource",
          "igasset_name": "simple-wgsl"
        }
      ]
    }
  ]
}

See igpack-bundle E2E test-definitions folder for some examples.

extract-asset-metadata usage:

extract-asset-metadata inspects one file (by content - file names carry no meaning for uploaded assets) and reports what it is, how igasset-gen can consume it, and which other files it depends on. Stdout only; see tools/extract-asset-metadata/README.md for the full contract (modes, dependency statuses, exit codes).

extract-asset-metadata                \
  --json                              \
  --deep                              \
  --manifest ./staging/manifest.json  \
  --logical-name models/scene.gltf    \
  ./staging/uuid-scene-gltf

CLI options:

• --json Machine-readable JSON output (default: human-readable text).
• --deep Full Assimp import (models only). Exposes the entire Assimp parser attack surface - only run in a sandbox.
• --manifest Staged asset manifest (JSON). Present = staged policy (deny-by-default, manifest-only lookups); absent = direct policy.
• --logical-name Logical name of the input (staged mode: needed for manifest lookups and Assimp's extension-based importer selection).
• --max-file-size Refuse larger files before reading (default: 1 GiB).

Exit codes: 0 inspected (including kind: unknown), 1 bad args / unreadable input, 2 too large, 3 --deep parse failure.

igasset library usage:

TODO (kamaorn)

Roadmap / TODO / Unimplemented (but planned) features:

New asset types

• Draco 3D geometry so dang close to being ready... just need to migrate
• Ozz skeletons + animations
• Cubemap textures + luminosity textures
• Non-albedo optimized textures (roughness, normal maps)
• Spritesheets

Eventually I'd also like to get to:

• Sounds
• Recast / detour navmeshes

Helpful utilities / features

• Asset metadata sidecar files (compression ratio, etc.)
• Asset viewers
• Memory limits
• Runtime profiling

Contributing Guidelines

This library is primarily intended for use within Indigo Code projects, and is published as-is primarily as a resource and potential tool for indie game engine authors to use if they'd like a starting-off asset processing tool.

It is not intended to be general-purpose or robust to a wide variety of formats! Feel free to request additional formats, but please understand that most requests will be denied. I intend to keep the list of supported formats for each asset modality minimal, and scoped specifically to formats that excel at web delivery.

Please also be aware that this is a very opinionated format and library. I don't see myself prioritizing any efforts around extensibility / robustness - I use it for my own projects and welcome you to use the code (in part or in full!) as you please, but am not interested in making breaking changes to satisfy a wider audience.

Criteria of a web-friendly format:

• Small size over-the-wire
• Lossless or acceptably lossy compression (preferrably)
• Reasonable decoding time on the client
• Added code has a reasonable binary size when linked in a WebAssembly application