Engine Decoupling — Phase 1: Interface development

[JohnLudlow]

Summary

Define stable adapter contracts, DTO shapes, and example APIs used by all engine adapters (rendering, input, audio, asset lifecycle).

Current Implementation Status (repo)

Implemented under src\GameEngineAdapter.Core\:

• Core contracts: IEngineAdapter, provider interfaces (IRenderProvider, IInputProvider, IUserInterfaceProvider, IAssetProvider), and IAudioPlayer/IAssetLoader.
• DTOs: EngineCapabilities (includes ContractVersion), plus draw/material/transform DTOs.
• Unit tests exist for DTOs and headless implementations under src\GameEngineAdapter.UnitTests\.
• Translator tests: src\GameEngineAdapter.UnitTests\Translator\TranslatingRenderProviderTests.cs covers SubmitSprite, SubmitText, SubmitMesh, and frame boundary calls using RecordingFakeRenderBackend.
• Benchmark suite: src\GameEngineAdapter.Benchmarks\RenderTranslationBenchmarks.cs (BenchmarkDotNet, [MemoryDiagnoser]) measures single-sprite and 1000-sprite render translation hot paths. Formal validation of the single-digit microsecond target has not yet been run.

Notes / gaps:

• Contract mismatch detection/diagnostics is not implemented in this repository (the contract is versioned via EngineCapabilities.ContractVersion, but there is no central validator/fail-fast helper yet).

Objective

Produce small, well-documented C# interfaces and compact DTOs that minimize allocation and provide a stable surface for engine adapters.

Technical Details (updated)

• Define IEngineAdapter (lifecycle, capability descriptor, provider properties: RenderProvider, InputProvider, UserInterfaceProvider, AssetProvider, AudioPlayer).
• Define provider interfaces: IRenderProvider, IInputProvider, IUserInterfaceProvider, IAssetProvider.
• Define IAudioPlayer (play/stop/volume, audio asset references) and IAssetProvider/IAssetLoader for asset lifecycle.
• Define EngineCapabilities capability descriptor model (includes ContractVersion) with engine-specific variants (e.g. HeadlessEngineCapabilities).
• DTOs are readonly record struct for compact value semantics; include Transform and Layer for deterministic ordering.

Requirements

• (Complete) API definitions committed with XML docs and examples.

  • GIVEN interface PR is opened
  • WHEN team reviews and approves
  • THEN interfaces are versioned and published for adapter implementations.

• (Partially complete) Adapter lifecycle & capability negotiation

  • GIVEN adapters are present at startup
  • WHEN the game queries capabilities
  • THEN IEngineAdapter returns EngineCapabilities and exposes Initialize/Shutdown semantics.
  • NOTE: mismatch diagnostics are not implemented yet.

Acceptance Criteria (updated)

• All interfaces defined with XML documentation.
• DTO guidelines documented (struct-based, allocation budgets).
• ContractVersion in EngineCapabilities for versioning/compat shims.
• Unit tests: translator tests that map DTOs to engine calls using fakes.
• Performance target: single-digit microseconds per DTO translation on hot paths (benchmark suite exists; formal target validation not yet run).

Docs

• docs/plans/phase-1-interface-development.md

Dependencies

Parent: #2

[JohnLudlow]

Updated issue description/checklist to match current implementation status (Core contracts + DTOs in place; mismatch diagnostics + translator tests + perf benchmarks still pending). See docs/plans/phase-1-interface-development.md.