Detailed Roadmap

What has shipped, what is genuinely incomplete, and what nobody has started · audited against CNA snapshot c1c316b9 (9 October 2026)

⚠

CNA is a long-term open-source project. There are no fixed release dates. Progress is incremental. This roadmap describes goals and current priorities, not commitments.

Current state

0.1.0-alpha.1 is CNA's first tagged pre-release, resolved here to 1bb2145d99ed572dd4eb15009c34e2e5f410fcf0. This roadmap is audited against the development snapshot c1c316b9 on the apple/m4-stabilization branch, 3,687 commits after that tag; the snapshot still reports 0.1.0-alpha.1 and is not a release (see Releases & Versioning). At this snapshot CNA represents all 331 public XNA 4.0 runtime types and 3,627 of 3,627 documented runtime members (representation, not behavior; Framework.Design converters are an opt-in module), exposes 14 renderer identities across 12 implementation families (alpha.1 had 50 across 46, later curated), and has 813 C++ test sources with 11,380 statically discoverable GoogleTest-family definitions (alpha.1: 568 and 8,263). Those are source-inventory facts, not a universal pass count; APIs may change before 1.0.

Remaining work is therefore depth, not breadth. The list below is drawn from an audit of the source tree, not from a wish list.

Shipped

Renderers — 14 identities, 12 families

The default mode selects one with CNA_GRAPHICS_RENDERER. An opt-in CNA_GRAPHICS_RENDERERS list links several compatible families and selects one before the first device through GraphicsRendererSelection; fallback is explicit and the choice latches. The table below is representative, not the full inventory — use the renderer reference for all 14. The state column follows CNA's own declared maturity classification (Production, Supported, Experimental), which is a classification, not a measurement.

Renderer	State	Notes
EasyGL	Production (`WEBGL2`: Supported)	One implementation behind `OPENGLES3`, `OPENGL33` and `WEBGL2`, with the stock effects, lighting, anisotropy, fog and context-loss recovery, MRT, occlusion queries, 3D textures, multi-stream input and instancing.
Vulkan	Production	SPIR-V pipeline with MRT handling, device-queried depth formats, stencil, MSAA resolve and mip blits, and the most complete modern surface: compute, indirect draw, base-instance drawing, GPU timers, float/half render targets, shadow sampling and image-based lighting (device-conditional).
DIRECTX9	Production	Windows-only SM2/SM3 path with device-lost recovery and capability-validated MRT; the renderer the 39-scene real-XNA oracle corpus is diffed against (recorded at tolerance 0 under Wine + DXVK on Linux; not a CI gate).
SDL_GPU	Supported	Renderer on SDL3's GPU API (SPIR-V; SDL selects the driver) with stock effects, stencil, MSAA resolve, MRT, instancing, compute, indirect draw, float targets, shadow sampling and IBL. Alpha.1 drove a Vulkan device only; Direct3D 12 and Metal drivers are now reachable through SDL_shadercross (on by default on Windows and Apple).
DIRECTX11	Production	Windows-only state-object caching, MRT with deferred resolve, instancing, 3D textures, float/half render targets and runtime shader compilation. `startIndex`/`baseVertex` draw offsets are honoured.
Software	Experimental	CPU rasterizer that owns its framebuffer; no window or GPU library. MSAA, MRT (up to four), occlusion, instancing, wireframe, 3D texture storage and float/half targets; opt-in compiled effects; a terminal presenter on `CNA_PLATFORM=TERMINAL`. No custom `ShaderEffect` execution.
SDL_Renderer	Production within its 2D scope	2D renderer with explicit capability boundaries; 3D calls throw by design. The default on Windows, macOS, iOS, Android and other non-Linux hosts.
Metal	Supported	Apple Metal directly, on macOS and iOS: MSAA, MRT, occlusion queries, instancing and multi-stream input, float, packed and DXT formats, cube and volume textures, full PBR and SpriteBatch-scoped MSL custom effects; compiled XNA effects behind `CNA_METAL_COMPILED_EFFECTS` (off by default). Its full test suite passes on a physical Mac mini M4; iOS evidence is Simulator-only. Not yet primary-production.
FNA3D	Experimental	Adapter over the FNA3D C library, which chooses SDL_GPU, Direct3D 11 or OpenGL at run time; executes compiled D3D9 Effect Framework binaries (always on) but no source `ShaderEffect`.
WebGPU	Experimental	No longer backbuffer-only: MRT, occlusion queries, wireframe, multi-stream input, instancing, probed MSAA and float render targets, and compute. Runs natively through `wgpu-native` and, new since alpha.1, in the browser through Emscripten.
Headless	Test harness	Deliberately renders nothing; reading the back buffer (`GraphicsDevice::GetBackBufferData`) throws `NotSupportedException` after argument validation instead of returning a made-up frame. Useful for fast game-logic CI.

Content and rendering features

The read-side XNB loader. ContentManager has 61 built-in readers (60 without native 128-bit integers), LZX decompression, shared-resource resolution, video, typed external references and a real compiled-effect EffectReader. Loading tries .xnb, then .cnb, then loose files. Custom readers can be registered explicitly, and a reflective builder reads declared-field models; there is still no runtime reflection in C++.
A build-time content pipeline. cna-content compiles source content through Importer → Processor → Writer into CNA's own .cnb container or into XNB (including LZX compression), builds .contentproj projects, and compiles .fx source through an external fxc-compatible compiler. See Content Pipeline and Command-Line Tools. Alpha.1's read-side-only limitation no longer holds.
Five XNA stock effects and SpriteEffect — BasicEffect, AlphaTestEffect, DualTextureEffect, EnvironmentMapEffect, SkinnedEffect and SpriteEffect (XNA keeps its sprite effect internal) — implemented natively in C++ rather than translated from bytecode.
PBR effects and the CNAEXT extensions: PbrEffect and SkinnedPbrEffect with shadow and image-based-lighting inputs; the opt-in CNA::Graphics module (CNA_CNAEXT=ON) holds retro post-processing effects and debug drawing; and a RendererCapabilityProfile API reports what a renderer can do (32 features, 22 limits, per-format usage, a text report).
Skeletal animation (CNAEXT): SkinningData on Model::Tag with AnimationPlayer, AnimationClipEXT, BoneTrackEXT and KeyframeEXT (the Avatar path has its own SkinnedModelEXT), plus MorphTargetEXT blend shapes.
cna_tool_gltf_to_cnj, an offline glTF 2.0 → .cnj Model/AnimationClip converter, built unconditionally. It is now one route among several: cna_tool_gltf_to_cnb and cna-content compile glTF straight to .cnb, and a runtime glTF loader exists too.

Platforms, audio and tools

Three platform implementations (CNA_PLATFORM): SDL3 (the default and the one windowing platform, which reaches Windows, X11 and Wayland through SDL’s video drivers and still hands out the native window handles), HEADLESS and TERMINAL. See Platforms and Windows, X11 and Wayland.
Native ALSA audio (CNA_AUDIO_PLATFORM=ALSA) with CNA's own mixer, beside SDL3 and NULL.
Diagnostics and the Inspector: an opt-in, renderer-independent metrics and profiler layer (CNA_DIAGNOSTICS=OFF|STATS|FULL) and an optional authenticated agent with a local browser UI (CNA_BUILD_INSPECTOR). Neither exists in alpha.1.
The experimental C ABI at 0.46.0 (alpha.1: 0.7.0): 60 headers and 3,210 routes, with a host-driven frame loop and an opt-in queue for calls from other threads. No CNA CI workflow builds the C library and its release gate reads “Not ready”. See Experimental C API.
C# through CNA.NET: the C# binding over the C ABI exposes the Microsoft.Xna.Framework API and runs original XNA 4.0 C# source on CNA (beta; qualified on Linux, in headless Chromium and on the x86_64 Android emulator, with local osx-arm64 evidence from a physical Mac mini M4 and no macOS CI leg). See C# with CNA.NET.
Gamer Services: local offline profiles by default, plus an optional self-hosted server for accounts, social features, leaderboards and relayed online sessions. See Gamer Services & Avatars.
Web saves persist: StorageDevice and isolated storage are mounted on the browser’s IndexedDB.

Verification infrastructure

The XNA 4.0 oracle corpus — 39 scenes (256×256, HiDef) under tools/xna-oracle/ with reference images captured from a real XNA 4.0 runtime under Wine + DXVK on Linux. DIRECTX9 is recorded at zero difference at --tolerance 0 on all 39 (a manual run, not a CI gate; the last consolidated dated report in the repository covers 31 scenes; later per-scene notes record the rest). EasyGL and Software are gated on two line scenes (the EasyGL test fails on any pixel difference; the Software test only if a scene does not render); Software measured 18 of 39 byte-exact; FNA3D gates only that scenes render.
FNA differential testing against a real running FNA build, via tools/fna-reference/ and scripts/compare-fna-reference.py (a manual harness).
Cross-renderer parity fixtures — 32 fixtures on four renderer families (EasyGL, WebGPU, SDL_GPU and Direct3D 11); the oracle is each fixture's own assertions, not real XNA. A glTF conformance corpus of 148 assets (140 captured, 8 safely rejected) with renderer-owned goldens.
A CNAEXT purity check — non-XNA declarations are tagged CNAEXT, and a strict compile check turns them into [[deprecated]] warnings under -Werror. The check covers Microsoft::Devices and Sensors; it does not prove the whole XNA-only surface stands alone.

Remaining work

Every item below is a real, audited gap, ordered roughly by how much it costs a porting project.

Item	State	What it would take
Compiled effects beyond qualified builds	Partial	Compiled D3D9 Effect Framework binaries (`.fxb`) now execute on nine implementation families (eleven identities): FNA3D is always on, and eight opt-in build options cover the EasyGL family, Vulkan, WebGPU, Software, DirectX 9/11, SDL_GPU and Metal. A default configure still reports the capability false on 13 of the 14 identities. Open: the 2D-only `SDL_RENDERER` and the no-pixel `HEADLESS` and `STUB` do not run them. HLSL `.fx` source is not accepted at run time; at build time `cna-content` compiles it through an external fxc-compatible compiler, a route CNA's own notes say has not been checked against a genuine Microsoft `fxc`. MGFX and raw DXBC remain unsupported inputs.
Consistent surface-format coverage	Renderer-dependent	Vulkan maps all 27 `SurfaceFormat` members against device format properties; EasyGL, SDL_GPU, DirectX 11, WebGPU, Metal, Software and FNA3D cover subsets. Renderers without a texture-format classifier (DirectX 9, Headless, Stub and SDL_Renderer) accept `Color` only, and anything else throws. A truthful per-renderer contract and configuration tests remain.
`ReflectiveReader` for custom XNB types	Partial	C++ has no reflective discovery, but explicit custom-reader and type-creator registration works and a reflective reader builder (`ReflectiveTypeReaderBuilder`) reads types described by a declared-field model. User and closed-generic types must still be registered or described deliberately; the open item is XNA-style automatic discovery, which C++ cannot offer.
Direct3D verification (DIRECTX9, DIRECTX11)	Manual only	DIRECTX11 honours draw offsets, and its native MSVC workflow’s recorded dispatch on GitHub’s Windows image (2026-10-06) passed 300 of 300 tests. What is missing is evidence: that workflow runs only on manual dispatch (`workflow_dispatch`), so nothing gates Direct3D automatically, DIRECTX9 has no Windows lane at all, and the only physical-hardware validation recorded is one Windows 11 machine with an Intel GPU.
WebGPU maturity	In progress	No longer backbuffer-only, but still declared Experimental by CNA; half-float linear filtering is unavailable, and the only workflow that names `WEBGPU` builds and inspects an Emscripten browser bundle without running it. No workflow names `SDL_GPU`, `OPENGL33`, `FNA3D` or `DIRECTX9`.
Metal beyond the Mac mini M4 runs	Supported, not primary-production	Declared Supported, and since CNA's Mac mini M4 campaign measured on real hardware: MSAA, multiple render targets, occlusion queries, instancing, float, packed and DXT formats and SpriteBatch-scoped MSL custom effects are native, the full test suite and 261 Metal tests under the validation layers pass on that machine, and compiled XNA effects work behind `CNA_METAL_COMPILED_EFFECTS` (off by default). Open: on-screen presentation and `PresentInterval` pacing (the runs had a locked console), a physical iOS device, an Intel Mac, a soak run, compute and indirect draw, and a green hosted CI run.
Gamer Services beyond Linux	Linux; macOS recorded	Local profiles, the Guide, avatars and the optional CNA Gamer Services server (accounts, social features, leaderboards, relayed PlayerMatch and Ranked sessions) exist and are qualified on Linux; CNA’s Apple campaign records the client tests and the server suite on one physical Mac mini M4 (37 of 46 server tests passed, 9 skipped for prerequisites macOS lacks, none failed), where online play needs a WebSocket-capable libcurl such as Homebrew’s. Open: Windows, a real wide-area network, browser builds (where the service, relay and voice are absent), iOS (built without networking), avatar pixels on Direct3D and Metal, offline leaderboard stream columns and online guests; achievements and scores are client claims without anti-cheat, and no public server instance is operated. See Gamer Services & Avatars.
Media platform and codec coverage	Platform-dependent	The catalogue, playback and FFmpeg-backed video paths are implemented. The video types now exist on every target and throw `NotSupportedException` without a decoding backend; FFmpeg decoding is optional (`CNA_ENABLE_VIDEO=OFF\|AUTO\|ON`) and is never built for Windows, Emscripten, Android or iOS. On the SDL3 audio path SDL_mixer has no AAC decoder for `.m4a`/`.aac`.
Deeper tests for Media and Storage	Uneven	Storage has 14 statically discoverable GoogleTest-family definitions (alpha.1: five) and Media 304 (alpha.1: 286). Those counts still leave significant runtime and platform-specific behavior unverified.
Broader CI	In progress	This snapshot has 18 workflow files (24 jobs; 16 of the files trigger automatically on pushes and pull requests, and 21 of the jobs run that way), including Linux, Apple (macOS and iOS), Emscripten, a platform-implementation matrix (the SDL3 window suite on SDL’s `x11` and `wayland` drivers, an SDL-free Headless + ALSA build and the `CNA_ENABLE_SDL` matrix), multi-renderer and five build-free C API gates. No workflow builds the C API library, the Windows Direct3D and SDL3 lanes are manual, and there is no Android job. The inventory does not exhaust every renderer/driver/platform combination.
Truthful `SupportsCapability()`	In progress	The base returns false for multi-stream input, compiled effects and float/half-float render targets, delegates stencil and returns `true` for the remaining entries; the device derives several answers itself (compiled effects, float targets, compute, indirect draw) and bounds MRT by the profile limit. DIRECTX9 is now the only renderer that never overrides it (DIRECTX11 and SDL_GPU do). Several capability claims therefore remain permissive rather than verified; the new `RendererCapabilityProfile` reports each answer as classified or unknown.
The C ABI release gate	Not ready	631 in-scope public C++ declarations still lack C mappings in the generated inventory (443 more are recorded as having no C form); that is the one unmet criterion the committed report records. No CNA CI job builds the C library; the consumer test and package machinery are verified on Linux and, by CNA’s own run on a physical Mac mini M4, on macOS (a Mach-O `libcna_c_api.dylib` and a static archive, installed and consumed); ABI 1.0 is a separate future decision. The C# binding CNA.NET pairs with exactly ABI 0.46.0; the Common Lisp, Go, Java, Python, Ruby, Rust, Swift and TypeScript bindings are archived and will not follow new ABI versions. See Experimental C API.
Diagnostics and Inspector coverage	Early	The engine publishes frame, draw-call, texture-binding, sprite and audio-voice metrics and resource metadata. It publishes no GPU timings, input metrics or process-memory totals to Diagnostics, no renderer registers a diagnostics source or an Inspector preview provider, and no CI workflow configures either module. Native-Windows validation is CNA's own claim; macOS runtime validation is pending.
Window-system and content-pipeline verification	In progress	The SDL3 window-system suites run on virtual displays (a private Xvfb and a private headless Weston) and on GitHub’s Windows image, so they establish the platform contract and the native handles a renderer receives rather than behaviour on a physical desktop with real input devices, keyboard layouts and IMEs; on the Mac mini M4 the console was locked, so on-screen presentation was not observed (see SDL3 platform internals). The content pipeline’s only Windows lane runs on one branch plus manual dispatch, and CNA ships no XMA audio encoder (asking for one reports it externally unavailable, and you can attach your own).

Toward a public stable release

The project is now versioned, but alpha.1 deliberately makes no 1.0 stability promise, and the development snapshot has not been given a new version. Reaching 1.0 plausibly requires:

A stable public API and explicit compatibility policy.
Clear renderer-qualified contracts for effects, formats and capabilities.
Reproducible test results for supported configurations rather than tree-wide counts alone.
Production evidence on the platforms CNA intends to support.
A build-verified, CI-gated C ABI with its release gate green — itself only the precondition for a separate ABI 1.0 decision.

Contributing to the roadmap

The highest-value contributions right now are the unglamorous ones:

Deepening Media and Storage runtime coverage.
Closing the named renderer gaps — Metal’s on-screen presentation, soak and physical-iOS evidence, automatic coverage for the Direct3D, WebGPU and SDL_GPU renderers, and per-renderer surface-format contracts.
Making SupportsCapability() truthful, renderer by renderer.
Expanding automatic Windows and platform-combination coverage.
Building the C ABI in CI and mapping the 631 planned public C++ declarations that have no C route yet.
Wiring GPU timers and input metrics into Diagnostics, and shipping a renderer-side Inspector preview provider.
Porting games to CNA to expose API gaps that an audit cannot find.

Open issues and TODO markers in the source are the best starting points. See the GitHub repository (branch apple/m4-stabilization holds the documented snapshot).

Deep dives on this topic

Long-form pages that explain the exact semantics, invariants and evidence behind this subject.

Project records as evidence: plans, ledgers, versions, handoffs and re-audits — How to use and write CNA's plans, handoffs, audits and gates as evidence: roles, stable task IDs, executable ledgers, version coordinates, defect-ledger rules and documentation re-audits.