ALPHA-002: GoudEngine Alpha v2

[aram-devdocs]

GoudEngine Alpha v2

Master tracking issue for the Alpha v2 release. This covers engine capabilities needed after Alpha v1 ships to support large-scale games (city builders, colony sims, strategy games targeting 100k+ entities).

Draft: This issue is a living backlog. Feature IDs and phases will be refined as Alpha v1 stabilizes.
Scope change: Debugger, observability, replay, profiling, visual capture, and AI-agent runtime tooling moved into Alpha v1 Phase 2.5 under #114 and #136.

---

Alpha v2 Definition

A developer can build a city builder / colony sim with 100k+ entities at 60fps, 1M-tile worlds, multiplayer, and mod support — all using GoudEngine's SDK with no external workarounds.

---

Phase 0: Core Performance (START HERE)

No dependencies beyond Alpha v1 complete. Start immediately after v1 ships.
Priority: This is the single biggest blocker for Throne and any game targeting scale.
Milestone: alpha-v2-phase-0

Target Legend: GoudEngine = engine repo only | THRONE = Throne repo only | HYBRID = both repos

Current Throne Profiling Data (373 entities, 200x200 map)

Metric	Value
Avg frame	16.69ms (P95: 21.63ms, P99: 29.48ms, ~60fps)
Avg render	13.51ms (80% of frame budget)
Avg sim	3.45ms (already optimized)
Draw calls/frame	155-345 individual GL calls
At 0.5x zoom + 5x speed	Drops to 20-30fps

Target after Phase 0: Throne locked at 60fps at ALL speeds and zoom levels.

Already Delivered (Reference)

• Z-Layer System (PR feat: finish rendering batch 3.2 sprite pipeline #565) — explicit z_layer, removed Y-sort
• Sprite pipeline refactor (PR feat: finish rendering batch 3.2 sprite pipeline #565) — Rust-side batching infra
• Text rendering API (PRs feat: add text rendering API, layout engine, and bitmap font support #472, feat: expose text rendering via FFI with SDK and unicode support #479) — glyph atlas caching
• Sprite batch culling stats (PR feat: add F09 rendering batch 3.3 features #568) — renderer-owned instancing
• Material system + PBR (PR feat: material system, PBR lighting, skeletal mesh, post-processing pipeline #574) — post-processing pipeline

---

PR Batch 0.0 — Instrumentation (DO FIRST, parallel)

Measure before optimizing. No optimization without data.

Ticket	Feature	Target	Priority	Notes
#585	V2-P06: Render Metrics & Draw Call Counter	GoudEngine	CRITICAL	Per-frame draw call counting, per-category timing, culling stats. Expose in C# SDK.
#586	V2-P12: Render Benchmarks Suite	GoudEngine	HIGH	Benchmark suite: empty/100/1k/10k entities. Baseline before optimization.

GATE 0.0: Draw call counter visible in metrics overlay. Benchmark baseline recorded. Per-category render timing available.

---

PR Batch 0.1 — Rendering Critical Path (sequential gate, after 0.0)

Fix blockers, then ship batch API.

Ticket	Feature	Target	Priority	Notes
#473	V2-P04: Fix DrawSpriteRect	GoudEngine	CRITICAL	UV vs pixel coord bug. Blocks atlas and sprite sheet usage.
#587	V2-P01: Sprite Batch C# SDK API	GoudEngine	CRITICAL	DrawSpriteBatch(ReadOnlySpan<SpriteCmd>). Rust impl exists (PR #565). Need FFI + C# P/Invoke + SDK codegen. Expected: 60-75% render time reduction.

GATE 0.1: DrawSpriteRect works with pixel coords. DrawSpriteBatch available in C# SDK. Benchmark: 1000 same-texture sprites <0.5ms.

---

PR Batch 0.2 — Rendering Polish + Throne Adoption (parallel, after GATE 0.1)

Ship atlas packing + text batching. Simultaneously refactor Throne adapter to USE new batch APIs.

Ticket	Feature	Target	Priority	Notes
#588	V2-P02: Texture Atlas Packing	GoudEngine	HIGH	Runtime atlas packing. Pack related textures at load time. Combined with V2-P01, reduces GL state changes to per-atlas (1-3 calls for entire scene).
#589	V2-P03: Text Batch API	GoudEngine	MEDIUM	DrawTextBatch(ReadOnlySpan<TextCmd>). Batch HUD labels + entity names. Eliminates 20-50 individual text calls per frame.
#590	V2-P09: DrawSpriteRect Migration (Throne)	THRONE	HIGH	Throne migrates from individual textures to sprite sheets now that DrawSpriteRect works. Prerequisite for atlas gains.
#591	V2-P07: Throne Adapter Batch Adoption	THRONE	CRITICAL	Refactor GoudRenderPort to accumulate render commands into command buffer, sort by texture, flush via DrawSpriteBatch. Currently 139+ immediate-mode calls to ~30-50 batched calls.

GATE 0.2: Throne render time drops from 13ms to <3ms. Atlas-based rendering end-to-end. Throne adapter uses batch API for all scene rendering. Draw calls reduced by 60%+.

---

PR Batch 0.3 — Simulation Performance (parallel with 0.2, after GATE 0.1)

Engine-level systems that Throne currently implements locally.

Ticket	Feature	Target	Priority	Notes
#549	V2-F01: Spatial Query System	HYBRID	HIGH	Engine grid/quadtree API. Throne has SpatialGrid<T> + FlatSpatialGrid locally. C# SDK exposure.
#545	V2-F03: ECS Generic Component C# SDK	HYBRID	CRITICAL	Throne has ComponentStore<T> + ComponentRegistry locally. Engine should own this.
#551	V2-P05: Fixed Timestep Accumulator	HYBRID	MEDIUM	Throne has FixedTimestep.cs locally. Engine game loop support.

GATE 0.3: Spatial queries O(1) from C# SDK. ECS generic components in C# SDK. Fixed timestep in engine loop. Throne can remove local implementations.

---

PR Batch 0.4 — Throne-Side Tuning (parallel with 0.3, after GATE 0.2)

Config-driven optimizations. No engine changes — pure Throne work.

Ticket	Feature	Target	Priority	Notes
#592	V2-P10: Viewport Culling Config	THRONE	MEDIUM	Hardcoded 5-tile culling margin to JSON-configurable, adaptive per zoom level.
#593	V2-P11: LOD Threshold Hardening	THRONE	MEDIUM	More aggressive LOD defaults: extend LOD 2 radius to 35-40 tiles, skip shadows at LOD 2, add adaptive budgeting (if frame > 16ms, increase LOD thresholds).

GATE 0.4: Culling margin configurable via JSON. LOD adapts to frame budget. Profiling shows <1ms decorations + distant entities.

---

PR Batch 0.5 — Memory & Allocation (after GATE 0.3)

Ticket	Feature	Target	Priority	Notes
#594	V2-F02: Object Pooling Framework	GoudEngine	MEDIUM	Engine-level entity/component pools. Pre-allocated queues, reset-on-return. Zero GC for spawn/despawn.
#595	V2-F04: Memory Management & Arena Allocators	GoudEngine	MEDIUM	Arena allocators for per-frame scratch. SOA component storage. Cache-line alignment.

GATE 0.5: Zero GC allocations in hot path. 10k entity iteration <1ms. Pool stats queryable.

---

PR Batch 0.6 — Integration & Version Bump (after ALL previous gates)

Ticket	Feature	Target	Priority	Notes
#596	V2-P08: Throne GoudEngine Version Bump	HYBRID	CRITICAL	Upgrade from 0.0.832 to Phase 0 release version. Wire all new APIs. Run full benchmark suite. Verify all gates.

GATE 0.6 (PHASE 0 EXIT):

• 10k entities at 60fps
• Zero GC in hot path
• Throne render <3ms (down from 13ms)
• Draw calls reduced 60%+ (from 155-345 to <100)
• Throne locked at 60fps at ALL speeds (1x-5x) and zoom levels (0.5x-2x)
• All benchmarks recorded and baselined

Dependency Graph

GATE 0.0 (#585, #586)                              [GoudEngine]
    |
GATE 0.1 (#473, #587)                              [GoudEngine]
    |
    +---> GATE 0.2 (#588, #589,                     [GoudEngine]
    |               #590, #591)                     [THRONE]
    |         |
    |         +---> GATE 0.4 (#592, #593)           [THRONE]
    |
    +---> GATE 0.3 (#549, #545, #551)               [HYBRID]
                |
          GATE 0.5 (#594, #595)                     [GoudEngine]
                |
          GATE 0.6 (#596)                           [HYBRID]

Phase 0 Target Summary

Target	Tickets	Count
GoudEngine	#585, #586, #473, #587, #588, #589, #594, #595	8
THRONE	#590, #591, #592, #593	4
HYBRID	#549, #545, #551, #596	4

---

Phase 1: World & Simulation Scale

Depends on: Phase 0 complete

Feature	Status	Dependency	Notes
V2-F05: Tilemap Chunks	planned	V2-F01	Chunked tilemap with streaming load/unload for 1M+ tiles
V2-F06: Pathfinding	planned	V2-F01, V2-F05	A* / hierarchical pathfinding with flow fields for groups
V2-F07: LOD & Simulation Tiers	planned	V2-F01	Near=full sim, mid=simplified, far=statistical
V2-F08: Job/Threading System	planned	V2-F03	Work-stealing job graph for parallel system execution
V2-F17: Fixed Timestep Simulation (Server-Authority)	planned	V2-P05 (#551)	Extends Phase 0 fixed timestep with deterministic execution for multiplayer. Moved from Phase 4.

GATE: 100k entities at 60fps. 1M-tile world loads in <2s. Pathfinding handles 1k concurrent agents.

---

Phase 2: Rendering & Assets v2

Depends on: Phase 1 world systems functional

Feature	Status	Dependency	Notes
V2-F09: GPU-Driven Rendering	planned	Phase 1	Instanced rendering, GPU culling, indirect draw
V2-F10: Asset Bundling & Streaming	planned	V2-F05	Async asset loading, bundle packaging, hot reload

GATE: 100k sprites rendered at 60fps. Assets stream without frame drops.

---

Phase 3: Game Infrastructure

Depends on: Phase 2 rendering stable

Feature	Status	Dependency	Notes
V2-F12: Save/Load System	planned	Phase 2	Versioned save format, incremental saves, compression
V2-F13: Scripting & Modding	planned	Phase 2	Lua/Wasm mod API, sandboxed execution, mod manager
V2-F15: SDK API Stability Contracts	planned	Phase 2	Semantic versioning, deprecation policy, migration tooling

GATE: Save/load round-trips 100k entities in <1s. Mods load without engine recompile. API breaking changes detected by CI.

---

Phase 4: Game SDK Features (Throne Requirements)

Depends on: Phase 3 complete. Features requested by Throne game project.

Feature	Status	Dependency	Notes
V2-F16: C# ECS SDK	planned	V2-F03	Archetype storage, component queries, entity iteration from C# SDK
V2-F18: Large World Coordinate System	planned	V2-F05	Double-precision or chunked coords for 1M+ tile worlds without float jitter
V2-F20: Headless Server Mode	planned	Phase 1	Run simulation without GPU/window for dedicated multiplayer servers
V2-F21: Binary Serialization SDK	planned	Phase 1	Efficient binary serialization framework for network messages and save files

Retired: V2-F19 (Sprite Batching & Instancing) — duplicate of V2-P01 (#587), delivered in Phase 0.
Moved: V2-F17 (Fixed Timestep Simulation) — moved to Phase 1, extends V2-P05 (#551) with server-authority.

GATE: C# ECS iterates 100k entities at 60fps. Headless server runs without GPU. Binary serialization round-trips in <1ms for 10k entities.

---

Quality Gates Summary

Phase	Gate Criteria
0.0 (instrumentation)	Draw call counter + benchmarks baselined
0.1 (render critical)	DrawSpriteRect fixed. Sprite batch API in SDK. 1000 sprites <0.5ms
0.2 (render polish)	Throne render <3ms. Atlas rendering. Draw calls -60%
0.3 (sim perf)	Spatial queries O(1). ECS components in SDK. Fixed timestep in engine
0.4 (tuning)	Culling configurable. LOD adaptive. Decorations <1ms
0.5 (memory)	Zero GC hot path. 10k entities <1ms iteration
0.6 (integration)	Throne 60fps all speeds/zooms. All benchmarks recorded
0 -> 1	10k entities at 60fps. Zero GC. Spatial queries working
1 -> 2	100k entities at 60fps. 1M-tile worlds. Pathfinding for 1k agents
2 -> 3	100k sprites rendered. Asset streaming
3 -> v2	Save/load working. Mod API functional. SDK versioning enforced

---

Success Criteria

• 100k entities at 60fps on mid-range hardware
• 1M-tile worlds with seamless chunk streaming
• Pathfinding handles 1k concurrent agents with flow fields
• GPU-driven rendering for 100k+ sprites
• Save/load round-trips in <1s for 100k entities
• Mod API supports Lua and Wasm sandboxed scripts
• Zero GC allocations in simulation hot path
• SDK API stability contracts enforced by CI
• C# ECS SDK with archetype queries from managed code
• Fixed timestep simulation with deterministic execution
• Large world coordinates without float precision jitter
• Sprite batching for 1000+ sprites per draw call
• Headless server mode for dedicated multiplayer servers
• Binary serialization SDK for network and save efficiency
• Throne locked at 60fps at all speeds (1x-5x) and zoom levels (0.5x-2x)

[aram-devdocs]

Closing as superseded by the ENG2 v2 rebuild master tracking issue #810. The v2 program (109 issues, 10 phases) replaces this tracker; its runbook lives at docs/src/runbook/phase-index.md. Historical context preserved here.