| … | … | @@ -0,0 +1,75 @@ |
| 1 | # Blender Bridge |
| 2 | |
| 3 | Real-time Blender-to-Godot scene synchronization via shared memory. |
| 4 | |
| 5 | ## Features |
| 6 | |
| 7 | - **Live mesh sync** — vertex positions, normals, UVs, indices update in real-time |
| 8 | - **Material graph transfer** — Blender node trees serialize to Godot VisualShaders |
| 9 | - **Skeleton pose sync** — armature pose retargeting via armature-space diff |
| 10 | - **Geometry node serialization** — Blender Geometry Nodes → proc-nodes ProcNodeGraph |
| 11 | - **Texture streaming** — whole-image, virtual texture tiles, and procedural baking |
| 12 | - **Change detection** — hash-based deduplication prevents redundant transfers |
| 13 | - **Auto-resize** — SHM grows automatically for large scenes |
| 14 | |
| 15 | ## Architecture |
| 16 | |
| 17 | ``` |
| 18 | Blender (Python addon) Godot (GDExtension) |
| 19 | ┌─────────────────────┐ ┌─────────────────────┐ |
| 20 | │ ChangeDetector │ │ BlenderBridge │ |
| 21 | │ ├─ depsgraph hook │ │ ├─ import_changes()│ |
| 22 | │ ├─ flush() → SHM │ SHM │ ├─ export_scene() │ |
| 23 | │ └─ hash caches │◄──────►│ └─ _process() │ |
| 24 | │ │ │ │ |
| 25 | │ SceneImporter │ UDS │ UdsServer │ |
| 26 | │ └─ reads region 0 │◄──────►│ └─ control channel │ |
| 27 | │ │ │ │ |
| 28 | │ MaterialSerializer │ │ VisualShader │ |
| 29 | │ GeometrySerializer │ │ GraphImporter │ |
| 30 | └─────────────────────┘ └─────────────────────┘ |
| 31 | ``` |
| 32 | |
| 33 | **Shared Memory Layout:** |
| 34 | - Region 0 (Godot→Blender): scene export + live Godot changes |
| 35 | - Region 1 (Blender→Godot): live Blender changes |
| 36 | - Tile Ring (8MB): virtual texture tile streaming |
| 37 | |
| 38 | **Coordinate Conversion:** |
| 39 | Self-inverse matrix M: `(x,y,z) → (-x, z, y)` converts between Blender Z-up and Godot Y-up. |
| 40 | |
| 41 | ## Build |
| 42 | |
| 43 | ```bash |
| 44 | cd /storage/projects/code/godot/blender-bridge |
| 45 | scons -j$(nproc) |
| 46 | # Output: bin/linux/libblender_bridge.linux.template_debug.x86_64.so |
| 47 | ``` |
| 48 | |
| 49 | ## Blender Addon |
| 50 | |
| 51 | Copy `blender_addon/` to Blender's addon directory and enable "Blender Bridge" in preferences. |
| 52 | |
| 53 | ## Usage |
| 54 | |
| 55 | ```gdscript |
| 56 | # Add BlenderBridge node to scene |
| 57 | var bridge = BlenderBridge.new() |
| 58 | bridge.shm_name = "/blender_bridge" |
| 59 | bridge.auto_sync = true |
| 60 | add_child(bridge) |
| 61 | |
| 62 | # Export current scene to Blender |
| 63 | bridge.export_scene(get_tree().current_scene) |
| 64 | |
| 65 | # Live changes imported automatically when auto_sync = true |
| 66 | ``` |
| 67 | |
| 68 | ## SHM Protocol |
| 69 | |
| 70 | Each region contains: |
| 71 | - **Header** (64 bytes): magic "BGOD", version, direction, sequence, object_count |
| 72 | - **Object Table** (32 bytes × max_objects): object_id, type, update_type, data_offset/size |
| 73 | - **Data Blob**: per-object name + transform + mesh/material/skeleton data |
| 74 | |
| 75 | See `docs/SPEC.md` for the full protocol specification. |