ENG2-P2-07: Incremental static batching: no full re-bake on change; no CPU vertex pre-transform

[aram-devdocs]

Parent

• Program: ENG2 — GoudEngine v2 Rebuild (see the pinned master tracking issue)
• Phase / Milestone: Phase 2 — Render Core v2 (eng2-p2-render-core)
• Batch / Group: Batch 2.2 — Upload rearchitecture, Group B
• Runbook spec: docs/src/runbook/phases/phase-2.md (committed with the roadmap)

Summary

Replace full static-batch re-bakes on any scene change with incremental per-chunk static batching that adds/removes individual objects without rebuilding the whole batch, and moves vertex transforms onto the GPU instead of pre-transforming on the CPU.

Architecture Context

Layer: Layer 2 (Libs) — libs/graphics/renderer3d/ (see tools/lint_layers.rs — downward-only deps).
Modules/types touched:

• goud_engine/src/libs/graphics/renderer3d/core_static_batch.rs — rebuild_static_batch re-bakes the entire batch whenever static_batch_dirty is set.
• goud_engine/src/libs/graphics/renderer3d/core/mod.rs (around the static-batch bake path) — currently pre-bakes CPU-transformed vertices into one VBO.

Boundary constraints (only those that apply):

• Raw GPU calls stay in libs/graphics/backend/ — no wgpu:: outside it.

Pattern to follow: Chunked spatial partitioning (align with the chunking approach used by ENG2-P2-11's tilemap-grid primitive, since that issue depends on this one).

Scope

• Partition the static batch into per-chunk batches instead of one monolithic batch.
• Support incremental add/remove of individual objects within a chunk without rebuilding unaffected chunks.
• Move vertex transforms to the GPU (shader-applied) instead of CPU pre-transforming vertices into the baked VBO.
• Tests: spec test at goud_engine/tests/spec/ + unit/isolation coverage for the new code paths.
• Docs/rules updates if this invalidates .agents/rules/graphics-patterns.md or docs/src/*.

Acceptance Criteria

• Adding/removing one object triggers a rebuild of only its containing chunk, not the full static batch (bench-asserted).
• No CPU vertex pre-transform occurs in the static-batch bake path (verified by inspecting the bake function — transforms are shader-side).
• PERF: rebake cost scales with chunk size, not total static-object count, on a scene with 40k+ static objects.
• cargo check && cargo fmt --all -- --check && cargo clippy -- -D warnings clean; cargo test green; ./codegen.sh && git diff --exit-code (drift gate)

Breaking Change & Throne Follow-up

None — additive/internal. Static batch external behavior (what gets drawn) is unchanged; only the bake granularity and transform location change.

Blocked By

None.

Files Likely Touched

• New/Modified/Generated: goud_engine/src/libs/graphics/renderer3d/core_static_batch.rs, renderer3d/core/mod.rs (static-batch bake path)

Agent Notes

• core_static_batch.rs:27-35 rebuild_static_batch re-bakes everything whenever static_batch_dirty is set — one dirty object forces a full rebuild.
• core/mod.rs:159 (current bake path) pre-bakes CPU-transformed vertices into one VBO — this is extra CPU work per bake and prevents any incremental update, since the baked positions are already world-space.
• ENG2-P2-11 (chunked tilemap-grid primitive) is blocked on this issue landing first — that primitive needs per-chunk static batches that can scroll/rebind without destroy/recreate, which requires this issue's chunking model to exist.

Verification

cargo check && cargo fmt --all -- --check && cargo clippy -- -D warnings
cargo test
./codegen.sh && git diff --exit-code