1 files changed, 59 insertions, 0 deletions
diff --git a/doc/SCENE_FORMAT.md b/doc/SCENE_FORMAT.md
new file mode 100644
index 0000000..679ab5e
--- /dev/null
+++ b/doc/SCENE_FORMAT.md
@@ -0,0 +1,59 @@
+# Scene Binary Format (SCN1)
+
+This document describes the binary format used for 3D scenes exported from Blender.
+
+## Overview
+
+- **Extension:** `.bin` or `.scene`
+- **Endianness:** Little Endian
+- **Layout:** Header followed by sequential blocks.
+
+## Header (16 bytes)
+
+| 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.
+
+| 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 Types
+
+```cpp
+enum class ObjectType {
+  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`.