From 70c64867baa30c83334559d3023153dfe3f9ff79 Mon Sep 17 00:00:00 2001
From: skal <pascal.massimino@gmail.com>
Date: Mon, 9 Feb 2026 10:43:11 +0100
Subject: docs: Simplify all design docs (50% reduction, 1687 lines removed)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

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.
---
 doc/SCENE_FORMAT.md | 76 +++++++++++++++++++++++------------------------------
 1 file changed, 33 insertions(+), 43 deletions(-)

(limited to 'doc/SCENE_FORMAT.md')

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.
-
-## 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) |
+- **Structure:** Header + Object Blocks
 
-### Object Types
+## Format Specification
 
 ```cpp
-enum class ObjectType {
-  CUBE = 0,
-  SPHERE = 1,
-  PLANE = 2,
-  TORUS = 3,
-  BOX = 4,
-  SKYBOX = 5,
-  MESH = 6
+// Header (16 bytes)
+struct Header {
+  char magic[4];        // "SCN1"
+  uint32_t num_objects;
+  uint32_t num_cameras; // Reserved
+  uint32_t num_lights;  // Reserved
+};
+
+// 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
 };
 ```
 
-## Coordinate System
+### Object Types
 
-- **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).
+```cpp
+enum class ObjectType {
+  CUBE = 0, SPHERE = 1, PLANE = 2, TORUS = 3,
+  BOX = 4, SKYBOX = 5, MESH = 6
+};
+```
 
 ## 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`.
-- 
cgit v1.2.3