summaryrefslogtreecommitdiff
path: root/doc/SCENE_FORMAT.md
diff options
context:
space:
mode:
authorskal <pascal.massimino@gmail.com>2026-02-09 10:43:11 +0100
committerskal <pascal.massimino@gmail.com>2026-02-09 10:43:11 +0100
commit70c64867baa30c83334559d3023153dfe3f9ff79 (patch)
treefa1353eca8f32334286aa4a9fc9c9461a5e56d8b /doc/SCENE_FORMAT.md
parente952a9d0866a5a2a5f9da72ccbb40e2184da8a6f (diff)
docs: Simplify all design docs (50% reduction, 1687 lines removed)
Consolidated and streamlined all documentation: **Merged:** - PROCEDURAL.md → deleted (content in ASSET_SYSTEM.md) - FETCH_DEPS.md → BUILD.md (dependencies section) **Simplified (line reductions):** - HOWTO.md: 468→219 (53%) - CONTRIBUTING.md: 453→173 (62%) - SPECTRAL_BRUSH_EDITOR.md: 497→195 (61%) - SEQUENCE.md: 355→197 (45%) - CONTEXT_MAINTENANCE.md: 332→200 (40%) - test_demo_README.md: 273→122 (55%) - ASSET_SYSTEM.md: 271→108 (60%) - MASKING_SYSTEM.md: 240→125 (48%) - 3D.md: 196→118 (40%) - TRACKER.md: 124→76 (39%) - SCENE_FORMAT.md: 59→49 (17%) - BUILD.md: 83→69 (17%) **Total:** 3344→1657 lines (50.4% reduction) **Changes:** - Removed verbose examples, redundant explanations, unimplemented features - Moved detailed task plans to TODO.md (single source of truth) - Consolidated coding style rules - Kept essential APIs, syntax references, technical details **PROJECT_CONTEXT.md:** - Added "Design Docs Quick Reference" with 2-3 line summaries - Removed duplicate task entries - All design docs now loaded on-demand via Read tool Result: Context memory files reduced from 31.6k to ~15k tokens.
Diffstat (limited to 'doc/SCENE_FORMAT.md')
-rw-r--r--doc/SCENE_FORMAT.md70
1 files changed, 30 insertions, 40 deletions
diff --git a/doc/SCENE_FORMAT.md b/doc/SCENE_FORMAT.md
index 679ab5e..fcf5e16 100644
--- a/doc/SCENE_FORMAT.md
+++ b/doc/SCENE_FORMAT.md
@@ -1,59 +1,49 @@
# Scene Binary Format (SCN1)
-This document describes the binary format used for 3D scenes exported from Blender.
+Binary format for 3D scenes exported from Blender.
-## Overview
+## File Layout
- **Extension:** `.bin` or `.scene`
- **Endianness:** Little Endian
-- **Layout:** Header followed by sequential blocks.
+- **Structure:** Header + Object Blocks
-## Header (16 bytes)
+## Format Specification
-| Offset | Type | Description |
-|--------|----------|-------------|
-| 0 | char[4] | Magic bytes "SCN1" |
-| 4 | uint32_t | Number of objects |
-| 8 | uint32_t | Number of cameras (reserved) |
-| 12 | uint32_t | Number of lights (reserved) |
-
-## Object Block
-
-Repeated `num_objects` times.
+```cpp
+// Header (16 bytes)
+struct Header {
+ char magic[4]; // "SCN1"
+ uint32_t num_objects;
+ uint32_t num_cameras; // Reserved
+ uint32_t num_lights; // Reserved
+};
-| Offset | Type | Description |
-|--------|----------|-------------|
-| 0 | char[64] | Object Name (UTF-8, null-padded) |
-| 64 | uint32_t | Object Type (Enum) |
-| 68 | vec3 | Position (x, y, z) - 12 bytes |
-| 80 | quat | Rotation (x, y, z, w) - 16 bytes |
-| 96 | vec3 | Scale (x, y, z) - 12 bytes |
-| 108 | vec4 | Color (r, g, b, a) - 16 bytes |
-| 124 | uint32_t | Mesh Name Length (N) |
-| 128 | char[N] | Mesh Asset Name (if N > 0) |
-| 128+N | float | Mass |
-| 132+N | float | Restitution |
-| 136+N | uint32_t | Is Static (0=Dynamic, 1=Static) |
+// Object Block (repeated num_objects times)
+struct ObjectBlock {
+ char name[64]; // UTF-8, null-padded
+ uint32_t type; // ObjectType enum
+ vec3 position; // 12 bytes
+ quat rotation; // 16 bytes (x, y, z, w)
+ vec3 scale; // 12 bytes
+ vec4 color; // 16 bytes (r, g, b, a)
+ uint32_t mesh_len; // Mesh name length (N)
+ char mesh_name[N]; // If N > 0
+ float mass;
+ float restitution;
+ uint32_t is_static; // 0=Dynamic, 1=Static
+};
+```
### Object Types
```cpp
enum class ObjectType {
- CUBE = 0,
- SPHERE = 1,
- PLANE = 2,
- TORUS = 3,
- BOX = 4,
- SKYBOX = 5,
- MESH = 6
+ CUBE = 0, SPHERE = 1, PLANE = 2, TORUS = 3,
+ BOX = 4, SKYBOX = 5, MESH = 6
};
```
-## Coordinate System
-
-- **Position**: Blender coordinates (Z-up) should be converted to engine coordinates (Y-up) by the exporter or loader. Currently raw export.
-- **Rotation**: Blender quaternions are (w, x, y, z). Exporter writes (x, y, z, w). Engine uses (x, y, z, w).
-
## Asset Resolution
-Mesh assets are referenced by name string (e.g., "MESH_CUBE"). The loader uses `GetAssetIdByName` to resolve this to a runtime `AssetId`.
+Mesh names (e.g., "MESH_CUBE") resolve to runtime `AssetId` via `GetAssetIdByName`.