1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
|
# ============================================
# TIER 1: CRITICAL CONTEXT (Always Loaded)
# ============================================
@PROJECT_CONTEXT.md
@TODO.md
@README.md
# ============================================
# TIER 2: TECHNICAL REFERENCE (Always Loaded)
# ============================================
@doc/HOWTO.md
@doc/CONTRIBUTING.md
@doc/AI_RULES.md
# ============================================
# TIER 3: DESIGN DOCS (Load On-Demand)
# ============================================
# Load these only when working on specific subsystems:
#
# Audio & Tracker:
# @doc/SPEC_EDITOR.md - Spectral editor design
# @doc/TRACKER.md - Audio tracker system
# @doc/ANALYSIS_VARIABLE_TEMPO_V2.md - Variable tempo analysis
#
# 3D & Graphics:
# @doc/3D.md - 3D rendering architecture
# @doc/PROCEDURAL.md - Procedural generation
#
# Build & Assets:
# @doc/ASSET_SYSTEM.md - Asset pipeline details
# @doc/BUILD.md - Build system details
# @doc/FETCH_DEPS.md - Dependency management
#
# Testing & Tools:
# @doc/test_demo_README.md - test_demo tool documentation
# ============================================
# TIER 4: HISTORICAL ARCHIVE (Load Rarely)
# ============================================
# Load these only for historical context or debugging:
#
# Completion History:
# @doc/COMPLETED.md - Detailed milestone history
#
# Technical Investigations:
# @doc/GPU_EFFECTS_TEST_ANALYSIS.md
# @doc/PLATFORM_ANALYSIS.md
# @doc/PLATFORM_SIDE_QUEST_SUMMARY.md
# @doc/PEAK_FIX_SUMMARY.md
#
# Agent Handoffs:
# @doc/HANDOFF_CLAUDE.md
# @doc/HANDOFF.md
# @doc/HANDOFF_2026-02-04.md
#
# Task Tracking:
# @doc/TASKS_SUMMARY.md
# ============================================
# PROJECT RULES (IMPORTANT)
# ============================================
IMPORTANT:
- Follow all rules in doc/AI_RULES.md
- This repository is shared with Claude-Code
- You are working in turns with another AI agent
- Work only on tasks explicitly requested by the user
- Do NOT modify files outside the current scope
- Do NOT perform refactors or cleanups unless explicitly asked
# Context Maintenance:
- See @doc/CONTEXT_MAINTENANCE.md for keeping context clean
- Archive completed work to doc/COMPLETED.md regularly
- Keep PROJECT_CONTEXT.md focused on current status
- Keep TODO.md focused on active/next tasks only
# ============================================
# CURRENT STATE SNAPSHOT (Gemini-Specific)
# ============================================
<state_snapshot>
<overall_goal>
Evolve the demo into a robust 3D engine with dynamic physics, BVH acceleration, and a modular shader architecture, targeting a 64k binary limit.
</overall_goal>
<active_constraints>
- **Skybox Pipeline**: Requires `depthWriteEnabled = WGPUOptionalBool_False` and `depthCompare = WGPUCompareFunction_Always` for Pass 1.
- **Asset Safety**: All assets must use `alignas(16)` and a null-terminator for safe C-string/float casting.
- **BVH Alignment**: `BVHNode` must be 32-byte aligned for GPU efficiency.
- **WGSL Traversal**: BVH traversal in shaders must be stack-based (no recursion allowed).
- **SDF Scale Safety**: `map_scene` must use conservative minimum scale (`min(scale_x, min(scale_y, scale_z))`) to prevent distance field overstepping.
- **WGPU String Safety**: On macOS/Darwin, dynamically composed shader strings MUST use the `str_view()` helper to ensure `WGPUStringView` compatibility (passing pointer AND length) to prevent validation errors.
- **Shader Modularization**: Use `#include "snippet_name"` in WGSL. Snippet names must match keys registered in `InitShaderComposer` (case-sensitive, usually folder/name without extension).
- **Platform Defines**: `CMakeLists.txt` MUST include platform-specific defines (e.g., `-DGLFW_EXPOSE_NATIVE_COCOA`) for `glfw3webgpu` to function.
- **Render Pass Config**: `WGPUSurfaceConfiguration` must have `usage = WGPUTextureUsage_RenderAttachment` to avoid validation errors.
- **Render Pass Init**: `WGPURenderPassColorAttachment` structs must have unused fields (like `resolveTarget`) explicitly set to `nullptr` to avoid validation errors.
</active_constraints>
<key_knowledge>
- **ShaderComposer**: Singleton using `std::map<std::string, std::string>` for snippets; `Compose` supports recursive resolution and cycle detection via `std::set`.
- **BVH Construction**: Rebuilt every frame on CPU via recursive midpoint split along the axis of largest variance; linearized into a `std::vector<BVHNode>`.
- **Mac-Specific WGPU**: `WGPUShaderSourceWGSL` in the current header version expects a `WGPUStringView` struct for the `code` field, not a raw pointer.
- **Physics Strategy**: "Proxy Point Probing" uses object corners/center as probes tested against neighbor analytical SDFs for narrow-phase resolution and normal calculation.
</key_knowledge>
<artifact_trail>
- `src/gpu/effects/shader_composer.cc`: Implemented `ResolveRecursive` for `#include` support and added unit tests.
- `assets/final/shaders/math/`: Created `sdf_shapes.wgsl` (shapes) and `sdf_utils.wgsl` (normals).
- `assets/final/shaders/render/`: Created `shadows.wgsl`, `scene_query.wgsl` (`map_scene`), and `lighting_utils.wgsl` (lighting logic).
- `assets/final/demo_assets.txt`: Registered 5 new modular shader assets.
- `src/gpu/effects/shaders.cc`: Updated `InitShaderComposer` to register the new granular snippet library.
- `src/3d/renderer.cc`: Refactored `create_pipeline` and `create_skybox_pipeline` to use internal `#include` instead of C++ side dependency injection.
- `src/gpu/gpu.cc`: Fixed `g_surface` assertion and render pass validation errors by correcting initialization.
- `CMakeLists.txt`: Added platform-specific defines for `glfw3webgpu`.
</artifact_trail>
<recent_actions>
- Implemented CPU-side SDF library and BVH construction for physics acceleration.
- Implemented PhysicsSystem with semi-implicit Euler integration and SDF-based collision resolution.
- Integrated physics and BVH visualization into test_3d_render.
- Verified physics stability with new test_physics unit test suite.
</recent_actions>
<task_state>
1. [DONE] Task #50: WGSL Modularization (Infrastructure and initial refactor).
2. [DONE] Task #49: Physics & Collision (CPU SDF Lib, BVH Builder, Euler Solver).
3. [NEXT] Task #18: 3D System Enhancements (Blender Export, Binary Format). <-- CURRENT FOCUS
4. [TODO] Task #36: Blender Exporter (Binary scene export).
5. [TODO] Task #39: Visual Debugging System (BVH and Physics visualization).
</task_state>
</state_snapshot>
|
