perf(wgpu): wire vsync config, add frame phase timing instrumentation

[aram-devdocs]

Overview

Type: perf

Summary:
Wire the existing vsync config flag to wgpu PresentMode (was hardcoded to AutoVsync), add per-phase frame timing instrumentation across the render pipeline, and upgrade the character_sandbox profiling to match Throne's pattern. Profiling confirms the vsync fix eliminates ~16ms of overhead per frame.

Related Issues: Fixes #660

---

Changes Made

Engine Core (goud_engine/src/)

• Added libs/graphics/frame_timing.rs — thread-local per-frame phase timing cache with 8 measured phases
• Modified libs/graphics/backend/wgpu_backend/init.rs — accept vsync: bool, use AutoNoVsync when disabled, reduce desired_maximum_frame_latency from 2 to 1
• Modified libs/graphics/backend/wgpu_backend/xbox_init.rs — same vsync parameter for Xbox GDK path
• Modified libs/graphics/backend/wgpu_backend/frame.rs — instrumented begin_frame (surface_acquire) and end_frame (uniform_upload, render_pass, gpu_submit, readback_stall, surface_present)
• Modified libs/graphics/renderer3d/render/mod.rs — instrumented shadow_build and render3d_scene phases
• Modified libs/platform/native_runtime.rs — pass window_config.vsync to WgpuBackend

FFI Layer (goud_engine/src/ffi/)

• Added FfiFramePhaseTimings struct to ffi/types.rs
• Added goud_renderer_get_frame_phase_timings() function to ffi/renderer/metrics.rs

C# SDK (sdks/csharp/)

• Generated FfiFramePhaseTimings struct and P/Invoke declaration

Python SDK (sdks/python/)

• Generated FfiFramePhaseTimings ctypes struct and FFI binding

TypeScript SDK (sdks/typescript/)

No changes

Codegen Pipeline (codegen/)

• Schema changes — added FramePhaseTimings type
• ffi_mapping changes — added type mappings and function entry

Proc Macros (goud_engine_macros/)

No changes

Tools (tools/)

No changes

WASM (goud_engine/src/wasm/)

No changes

Examples (examples/)

• Upgraded character_sandbox profiling: duration-based sampling, per-frame metrics, markdown/JSON reports, shadow config, VSync toggle
• Added Makefile with profile (200 NPCs + 80 animals) and profile-stress (400+ entities) targets

Documentation

No changes

---

Architectural Compliance

• Rust-first: All logic lives in Rust; SDKs are thin wrappers
• FFI boundary: New export uses #[no_mangle] extern "C" and #[repr(C)]
• Dependency flow: frame_timing.rs at libs/graphics level, accessible from both wgpu_backend and renderer3d
• SDK parity: FFI function exposed; typed GoudGame wrapper deferred (function has no context_id parameter)
• Unsafe discipline: // SAFETY: comment on FFI function

---

Testing

• cargo test passes (pre-existing native_main_thread test failure unrelated)
• cargo clippy -- -D warnings is clean
• cargo fmt --all -- --check passes
• 4 unit tests for frame_timing module (record, reset, unknown field, defaults)

---

Code Quality

• No todo!() or unimplemented!() in production code
• Error handling uses Result, not unwrap()/expect() in library code
• Public items have doc comments

---

Breaking Changes

None

---

Version Bump

Bump type: patch
Justification: Performance improvement, no API breaking changes

---

Security

• New unsafe block has a // SAFETY: comment (FFI metrics function)
• New FFI pointer parameter has null check

---

Performance

Profiling results with 280 entities (200 NPCs + 80 animals):

Config	FPS	Frame Time
Shadows + VSync ON (before fix)	13.2	71ms
Shadows + VSync OFF (after fix)	17.3	55ms
No shadows + VSync OFF	42.4	22ms
84 agents + VSync ON	55.5	17ms

VSync fix eliminates ~16ms overhead (one 60Hz vsync period).
Remaining render bottleneck is CPU shadow rasterization (out of scope).

---

Reviewer Notes

• The goud_renderer_get_frame_phase_timings FFI function does not take a context_id parameter (reads from thread-local cache). A typed GoudGame.GetFramePhaseTimings() SDK wrapper is deferred until the function signature is finalized with context support.
• GC pressure investigation (issue req Set FPS on engine init #4) is a .NET runtime concern best addressed in the Throne game layer, not the Rust engine.
• The native_main_thread integration test failure is pre-existing on main.

[claude]

Claude finished @aram-devdocs's task in 2m 18s —— View job

---

PR #662 Review: perf(wgpu): wire vsync config, add frame phase timing instrumentation

Verdict: APPROVED with warnings

---

Phase 1–3: Architecture & Anti-Pattern Scan

Check	Result
Dependency flow (downward-only)	✅ frame_timing.rs at libs layer; ffi imports libs correctly
#[no_mangle] extern "C" on FFI export	✅ goud_renderer_get_frame_phase_timings
#[repr(C)] on FFI struct	✅ FfiFramePhaseTimings
Null check on pointer param	✅ present in metrics.rs:88
// SAFETY: comment	✅ present in metrics.rs:96
No raw GPU calls outside backend/	✅
No todo!()/unimplemented!() in prod	✅
No unwrap()/expect() in library code	✅
SDK parity (C#, Python, Go, Kotlin, Swift)	✅ all updated

---

BLOCKERS

None.

---

WARNINGS (non-blocking)

1. String-key dispatch in record_timing is silently lossy — frame_timing.rs:38–49

match field {
    "surface_acquire" => t.surface_acquire_us = value,
    // ...
    _ => {}  // silent drop
}

A typo at any call site (e.g. "surface_acuire") produces zero for that phase with no error or warning. The unknown_field_is_ignored unit test even documents this silent-failure behavior. At a minimum the call sites should be validated (all 8 callers use literal strings, so this is low risk today, but it's a maintenance trap as new phases are added). Consider an enum-based setter in a follow-up. Fix this →

2. Thread-local without a context guard — metrics.rs:85, frame_timing.rs:30

goud_renderer_get_frame_phase_timings takes no context_id and reads a bare thread_local!. If the engine is ever extended with multiple contexts on separate threads, the wrong context's timings are returned without any error. The PR notes mention this as deferred work — a // TODO: comment in both the FFI function and FRAME_TIMINGS declaration would make this visible to future contributors before they add multi-context support.

3. Missing GoudGame wrapper for C# — sdks/csharp/

NativeMethods.g.cs:2477 exposes the raw P/Invoke, but there's no GoudGame.GetFramePhaseTimings() method. Consumers must call NativeMethods.goud_renderer_get_frame_phase_timings(ref timings) directly, leaking FFI details. The PR description acknowledges this is deferred — please track it as an issue so it doesn't get lost.

4. desired_maximum_frame_latency change is undocumented — init.rs:80

The value was silently reduced from 2 → 1. This is a meaningful behavioral change: lower frame latency but higher risk of GPU pipeline stalls on slower hardware. The PR description doesn't mention it. Worth a brief comment at the call site explaining the trade-off (e.g. "reduced to 1 to cut acquisition latency at the cost of one pipeline slot; revisit if stutter appears on integrated GPUs").

5. Xbox vsync path has no coverage — xbox_init.rs:31

The new_from_raw_handle now accepts vsync: bool and wires it to the surface config — good. But the existing TODO(xbox-gdk) comment on the file notes it already duplicates significant init logic. With two init paths that must stay in sync, the vsync logic is now duplicated across init.rs:73–77 and xbox_init.rs (assumed same pattern). If only one path is tested, a divergence could go unnoticed.

---

Positive Callouts

• Clean module design: frame_timing.rs is a minimal, focused thread-local cache with clear public API and no external dependencies.
• Good test coverage: 4 unit tests cover record, reset, unknown-field, and defaults — exactly the right surface for this module.
• Full SDK sweep: Go, Kotlin, Swift, C#, Python all updated in the same commit. The generated headers are consistent across all SDK include/ copies.
• vsync wiring is correct: AutoNoVsync for the disabled path is the right wgpu enum; AutoVsync retains backward-compatible behavior.
• Profiling structure in character_sandbox: duration-based sampling with markdown/JSON output is production-quality tooling.
• FFI discipline: null check, SAFETY: comment, #[repr(C)], #[no_mangle] — all present and correct.

---