feat(3d): Implement Blender export and binary scene loading pipeline

2 files changed, 99 insertions, 0 deletions

diff --git a/doc/HANDOFF_SCENE_LOADER.md b/doc/HANDOFF_SCENE_LOADER.md
new file mode 100644
index 0000000..b218d0b
--- /dev/null
+++ b/doc/HANDOFF_SCENE_LOADER.md
@@ -0,0 +1,40 @@
+# Handoff: 3D Scene Pipeline (February 8, 2026)
+
+## Summary
+Implemented a complete pipeline for exporting 3D scenes from Blender and loading them at runtime.
+
+## Accomplishments
+
+### Task #18: 3D System Enhancements
+- **Blender Exporter**: Created `tools/blender_export.py` to export scenes to a binary format (`SCN1`).
+  - Exports objects, transforms, types, and mesh references.
+  - Handles string-based asset resolution.
+- **Asset System Update**: Updated `asset_packer` to generate `GetAssetIdByName` for runtime string lookup.
+- **Runtime Loader**: Implemented `SceneLoader` (`src/3d/scene_loader.h/cc`) to parse the binary scene format.
+- **Verification**: Added `test_scene_loader` to verify the pipeline.
+
+## Key Components
+
+### Binary Format (`doc/SCENE_FORMAT.md`)
+- Magic: `SCN1`
+- Supports Objects (Mesh, Primitives), Cameras, Lights.
+- Compact binary representation.
+
+### Runtime Integration
+- `SceneLoader::LoadScene(scene, data, size)` populates a `Scene` object.
+- Uses `GetAssetIdByName` to resolve mesh references (e.g. "MESH_CUBE" -> `ASSET_MESH_CUBE`).
+
+## Next Steps
+- Use the exporter in a real workflow (requires Blender).
+- Update `Renderer3D` or `MainSequence` to actually use `SceneLoader` for a level (e.g. `assets/final/level1.bin`).
+- Implement `Task #5: Spectral Brush Editor` (In Progress).
+
+## Files Modified
+- `tools/blender_export.py` (New)
+- `src/3d/scene_loader.h` (New)
+- `src/3d/scene_loader.cc` (New)
+- `src/tests/test_scene_loader.cc` (New)
+- `tools/asset_packer.cc` (Updated)
+- `src/util/asset_manager.h` (Updated)
+- `CMakeLists.txt` (Updated)
+- `doc/SCENE_FORMAT.md` (New)
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`.