ENG2-P2-11: Chunked/scrollable 3D tilemap-grid primitive (windowless terrain)

[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.4 — Scene-scale primitives & gate validation, Group A
• Runbook spec: docs/src/runbook/phases/phase-2.md (committed with the roadmap)

Summary

Add a chunked/scrollable 3D tilemap-grid primitive — one handle represents an N×M tile grid with per-tile material/UV, backed by chunked static batches that can scroll/rebind without destroy/recreate — eliminating the need for consumers to destroy and recreate thousands of plane objects on camera movement.

Architecture Context

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

• New renderer3d/core_tilemap_grid.rs (or similar) — one handle owning an N×M grid of tiles, each with independently settable material/UV, backed by the chunked static-batch mechanism from ENG2-P2-07.
• goud_engine/src/ffi/renderer3d/ — new FFI surface for grid creation, per-tile material/UV set, and scroll/rebind operations.

Boundary constraints (only those that apply):

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

Pattern to follow: ENG2-P2-07's chunked static batches — this primitive is built on top of that chunking mechanism, not a separate implementation.

Scope

• Implement a tile-grid primitive: one handle = one N×M grid, per-tile material/UV settable.
• Back the grid with chunked static batches (from ENG2-P2-07) so only chunks near the camera are resident/drawn.
• Support scroll/rebind: moving the visible window over a larger logical grid without destroying/recreating tile objects.
• Expose FFI surface for grid creation and per-tile updates.
• 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

• A 200×200 tile grid (40k tiles) renders via the primitive with zero per-tile destroy/create calls during scroll.
• Draw-call bench: the grid renders in ≤ 64 draw calls at 40k tiles (Phase 2 gate number).
• Scrolling the grid window measurably avoids object churn (bench/test asserting zero allocation of new tile objects on scroll).
• 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. This is a new primitive; existing CreatePlane-based terrain construction remains available (though consumers should migrate — see Throne follow-up).

Blocked By

ENG2-P2-07 (incremental static batching), ENG2-P2-08 (auto-instancing).

Files Likely Touched

• New/Modified/Generated: new renderer3d/core_tilemap_grid.rs, ffi/renderer3d/ (new tilemap-grid FFI surface)

Agent Notes

• Consumer evidence: Throne destroys/recreates thousands of plane objects on every 12-tile recenter (throne_ge Terrain.cs:45-78) because no grid primitive exists today — this issue is the direct fix.
• Design intent: one handle = one tile grid (N×M, per-tile material/UV), chunked static batches (reusing ENG2-P2-07), scroll/rebind without destroy/create.
• Throne follow-up: THR-A-03 (replace the 80×80 terrain window with this primitive, full 200×200 map).

Verification

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