VoxelForge/CLAUDE.md

CLAUDE.md — VoxelForge

UE5 density-field voxel terrain plugin (strates / Marching Cubes / async streaming). Don't re-read the whole plugin — use the map.

⛔ #1 rule: NEVER build or compile

Jahni runs every build himself (he has the editor open; running it via Claude just burns cost). When code changes are done, stop and say "ready to build" + list likely compile-error spots, then wait for his results / pasted errors. Same for in-editor checks — ask for a screenshot, don't try to run anything.

Read first (in order, load only what the task needs)

• CODEMAP.md — ALWAYS. Navigation: what it is, data-flow (§2), symbol→file:line index (§3), "I want to change X → go here" (§5), conventions & gotchas (§6). Trust symbol names over line numbers (lines drift).
• ARCHITECTURE.md — when touching generation / strates / passages / biomes. The deep design (archetypes, (0,0) spine, disturbances, content/atmosphere, biomes) and the §8.10 performance invariants ("don't regress").
• fable-idea.md — before planning PERF or FEATURE work. Ranked perf+feature roadmap with verified hot spots; check it so you don't re-propose done/known work. (A perf pass already shipped: game thread solved ~3.94 ms, CullTiles spiral fixed, region-granular foliage.)
• REVIEW_FINDINGS.md — open quality/cleanup items (cross-check vs fable-idea before acting; some may already be addressed).

Hard rules (these prevent real bugs — verify against code, don't assume)

• Density sign: negative = solid, positive = air (MC convention at the mesher). FVoxelModification::Strength negative = carve. The #1 source of confusion.
• Density functions take VOXEL coords, not cm. The legacy plugin field uses 12.5 cm voxels; the opt-in Core field uses 25 cm voxels and its own 32³-voxel storage tile. The legacy 32³ chunk spans 4 m at 12.5 cm. Strate placement uses the separate world-level StrateLayoutChunkSizeMeters setting (8 m by default), resolved once and shared by every generator. At 25 cm that layout unit is 32 Core voxels; at 20 cm it is 40. Never infer the layout unit from CHUNK_SIZE or the Core tile. Conversions live in VoxelTypes.h, the director, and the Core bridge; do not mix scales in queries, anchors, edits, or surface lookups.
• Determinism: all randomness = hash of (coord, seed, strateIndex). No RNG state — same seed ⇒ same world. Player edits (diff layer) are the only non-deterministic overlay.
• Core world invariants: Core density keeps the same sign (negative solid, positive air), but Core voxel coordinates are 25 cm. Worker-count changes must preserve hashes; Core world edits are intentional world-version changes and must retain finite, walkable strate entrances and exits.
• Async safety: worker tasks only READ Generator/Mesher, must check bShuttingDown, and return via the result queues — ProcessQueue and its CriticalProcessQueue / EditedProcessQueue / NearProcessQueue siblings (all must stay EQueueMode::Mpsc). EndPlay blocks on ActiveTaskCount → 0.
• Carry the Epoch through any new async path (stale results are dropped on mismatch).
• Don't "optimize" the perf invariants in ARCHITECTURE §8.10 — the thread_local box-valid caches, two-pass MC loop, SSE noise, and clipmap streaming are intentional.
• Never edit Binaries/, Intermediate/, *.generated.h. Comments are French + English — match the surrounding file.

Discipline (keep the map alive)

• Add / rename / move a symbol → update its CODEMAP §3 row (symbol-first; line is a hint).
• Change generation/strate design → update ARCHITECTURE §8.
• Resolve a checklist item → tick it in REVIEW_FINDINGS.md.
• Don't duplicate content across these files — each has one job (map / design / findings / rules).