ADR-005: glTF + KTX2/Basis for 3D Assets

Status: Accepted Date: 2026-01-15

Context

SiliconGhetto needs a 3D asset pipeline for importing models, scenes, and textures. The choice of asset formats affects file size, load time, GPU memory usage, and tooling compatibility. Browser-delivered games are particularly sensitive to download size and decompression speed.

Options Considered

1. glTF 2.0 + KTX2/Basis Universal (chosen)

  • glTF is the “JPEG of 3D” — industry-standard interchange format
  • KTX2 with Basis Universal provides GPU-compressed textures that transcode to any GPU format
  • Extensive tooling: Blender, glTF-Transform, KTX-Software
  • Binary glTF (.glb) supports single-file delivery

2. Custom binary format

  • Optimized for our specific needs
  • No existing tooling — requires custom exporters
  • Maintenance burden for format evolution

3. OBJ + PNG

  • Universally supported
  • No PBR material support
  • No animation support
  • Large file sizes (text-based geometry, uncompressed textures)

4. FBX

  • Wide industry adoption
  • Proprietary format, complex specification
  • No Rust parser with full support
  • Not designed for web delivery

Decision

Use glTF 2.0 as the primary 3D asset format, with KTX2/Basis Universal for texture compression. The sg_assets crate handles loading and parsing. Binary glTF (.glb) is preferred for distribution to minimize HTTP requests.

Consequences

Positive

  • Artists use standard tools (Blender, Substance, etc.) with direct glTF export
  • KTX2 transcodes to BC7 (desktop), ASTC (mobile), or ETC2 (fallback) at load time
  • 5-10x smaller texture sizes compared to PNG
  • PBR materials, skeletal animation, and morph targets supported by the format
  • Extensive validation tools (glTF-Validator)

Negative

  • KTX2 transcoding adds initialization time
  • Basis Universal compression is lossy (acceptable for most game textures)
  • glTF parsing adds dependency weight
  • Not all glTF extensions are relevant for browser games

Mitigations

  • Pre-transcode textures at build time when target platform is known
  • Provide quality presets for Basis compression
  • Parse only the glTF features we support, reject unsupported extensions gracefully
  • Document supported glTF extensions and limitations

Asset Pipeline

Blender/DCC → glTF 2.0 export → sg asset optimize → .glb + KTX2 → Bundle
                                      │
                                      ├─ Validate manifest
                                      ├─ Compress textures (Basis Universal)
                                      ├─ Optimize geometry (meshopt)
                                      └─ Generate LODs (future)

References