CNA Documentation
Everything you need to understand, build, and develop with CNA. Documentation is growing alongside the project - contributions welcome. This hub documents development snapshot c1c316b9 (9 October 2026, branch apple/m4-stabilization); pages say so where they describe something the alpha.1 tag does not contain.
CNA is a work in progress. Documentation reflects the current state of the codebase and is updated as features are implemented. For the most authoritative source, consult the source code and README on GitHub — and note that the repository's default branch shows the alpha.1 tag, while this site documents the next branch (snapshot c1c316b9).
Doxygen API reference: CNA does not yet have a hosted Doxygen API reference. You can generate one locally: install Doxygen and use the Doxyfile in the CNA repository root as a starting point — it is close to Doxygen's defaults, so point INPUT at the modules/*/include directories and set RECURSIVE = YES; the generated HTML lands in html/index.html under the directory you run it from. Alternatively, browse the source headers directly on GitHub. The public headers are split across modules since the module refactoring: the core framework types are under modules/core/include/Microsoft/Xna/Framework/, and the graphics, input, audio, content and other namespaces live in the sibling modules/<name>/include/ directories.
Getting Started
Quick introduction to CNA - what it is, prerequisites, first build (from the apple/m4-stabilization branch, with sharp-runtime's apple/m4-stabilization branch), and a minimal game skeleton.
Building
Full build instructions for Linux, Windows, macOS and Emscripten: renderer, platform and audio selection, CMake options and presets, SDL-free windowless builds, and cross-compilation with MinGW-w64.
Releases & Versioning
Release history and versioning: the alpha.1 tag, the development snapshot documented here (c1c316b9, version string still 0.1.0-alpha.1), SemVer policy, generated C++ version API, tag naming and the separate C ABI version (0.46.0).
Alpha.1 tag + snapshot c1c316b9Platforms
Target support plus the independent host-platform selections (SDL3, Headless, Terminal) and audio selections (SDL3, Null, ALSA), with what was run where — including a physical Mac mini M4 and the iOS Simulator.
Windows, X11 and Wayland
How CNA reaches Windows, X11 and Wayland through SDL3’s video drivers: the native handles renderers receive, SDL-free windowless builds, build recipes and what CI actually covers.
New in this snapshotGraphics Renderers
Comparison and guide for all 14 selectable renderers - the EasyGL OpenGL ES 3, OpenGL 3.3 and WebGL 2 family, Vulkan, SDL_GPU, SDL_Renderer, native Direct3D 9 and 11, Metal, FNA3D, experimental WebGPU, and the GPU-free Headless, Software and Stub renderers - maturity tiers, test coverage, tradeoffs and when to use each.
Runtime Renderer Selection
Opt-in multi-renderer builds, precedence, latching on the first successfully created renderer, explicit fallback, combination rules and diagnostics.
Experimental Native C API
ABI 0.46.0 (alpha.1: 0.7.0) source surface: 60 headers, 3,210 routes, measured inventory, intended package design and a release gate that still reads "Not ready". No CNA CI job builds the library; CNA.NET builds and uses it on Linux.
C# with CNA.NET
The C# binding: a Microsoft.Xna.Framework-compatible facade over CNA’s C ABI. Architecture, platform evidence (Linux, headless Chromium, Android emulator), the dotnet new template, and the original XNA C# samples that run on it unchanged.
Migrating C# Games to CNA.NET
Step by step: build the C ABI and CNA.NET, wrap an unchanged XNA 4.0, FNA or MonoGame C# game in an SDK-style project, use its original .xnb content, and run it on Linux, in the browser or on Android.
Gamer Services & Avatars
Local profiles, sign-in, the Guide, achievements, leaderboards, friends and presence, avatars and network sessions — offline by default, with an optional self-hosted server.
New in this snapshotXNA Compatibility
API coverage against the XNA 4.0 runtime - 331 of 331 documented types and 3,627 of 3,627 members are represented - what that does and does not prove, and where "present" does not mean "working".
Verification & Known Issues
How CNA is actually tested - and the complete, current list of what is broken. Read this before committing to a port.
Start here before portingEffects System
Built-in effects reference: BasicEffect, AlphaTestEffect, DualTextureEffect, EnvironmentMapEffect, SkinnedEffect, custom ShaderEffect, and compiled XNA effect bytecode (11 of the 14 renderer identities).
SpriteBatch
Complete SpriteBatch guide covering Begin overloads, Draw overloads, SpriteSortMode, and BlendState configuration.
Audio System
Audio API reference: SoundEffect, SoundEffectInstance, MediaPlayer, Song, the functional XACT runtime, and the SDL3, Null and ALSA audio implementations.
Input System
Input handling guide for Keyboard, Mouse, GamePad, and TouchPanel across all supported platforms.
Math Types
Math type reference: Vector2, Vector3, Vector4, Matrix, Quaternion, BoundingBox, Curve, and related utilities.
Roadmap
Detailed development roadmap - what shipped since alpha.1, what is partial, what remains open, and the long-term vision.
FAQ
Frequently asked questions about CNA, its goals, differences from FNA/MonoGame, and how to contribute.
Subsystem reference
Deeper reference for individual parts of the API.
3D Rendering
Vertex buffers, primitives, cameras, and the 3D pipeline.
Graphics State
BlendState, DepthStencilState, RasterizerState, SamplerState.
Render Targets
RenderTarget2D, RenderTargetCube, and multiple render targets.
Shader Effects
Writing renderer-native GLSL/SPIR-V shaders with ShaderEffect. This is separate from the renderer-qualified XNA Effect Framework bytecode (compiled effects) path.
ContentManager
Asset loading with Load<T>(). Prefers a .xnb when one exists, then a .cnb, and falls back to loose files.
XNB Loading & Interoperability
Reading and writing .xnb binaries: 61 type readers, a real LZX decompressor and encoder, and the honest gaps.
Model Loading
The gltf_to_cnj and .cnb pipelines, XNB models, and the CNAEXT skeletal animation layer.
Game Loop & Lifecycle
Game, GameTime, GameComponent, and fixed vs variable timestep.
PackedVector Types
All 17 packed vector types, with IEEE 754 half-float precision.
Storage
StorageDevice and StorageContainer for save games and user data.
Video Playback
VideoPlayer and Song. Optional FFmpeg backend (Linux and macOS); the Video types link everywhere and throw NotSupportedException without it.
Sensors
Accelerometer and Gyroscope over the real SDL3 sensor API, Compass and Motion over the Android NDK, plus VibrateController.
CNA vs Alternatives
Honest comparison against FNA, MonoGame, and original XNA.
Migration from MonoGame / XNA
Porting an existing C# game: asset conversion, property renaming, ownership patterns.
CNAEXT Extensions
The extension marker, the always-compiled extension surface (PBR, shadow and IBL inputs, morph targets, capability queries) and the opt-in CNA::Graphics module: CRT, colour-depth and ASCII effects, debug drawing and shader packages.
Framework.Design
The XNA Microsoft.Xna.Framework.Design type converters (13 types) in the opt-in CNA::Design module: what they do, how to register them and what is out of scope.
Content pipeline, tools and diagnostics
Build-time content authoring, command-line tools and the opt-in development instrumentation added since alpha.1.
Content Pipeline
The build-time pipeline: cna-content, importers and processors, the XNA-shaped Content.Pipeline API, cna_add_content, and how .cnb and .xnb outputs are produced.
CNB Format
CNA's own deterministic runtime container: header, table of contents, CRC-32C checksums, chunk and asset-type ids, schemas and read limits.
New in this snapshotCommand-Line Tools
Reference for cna-content, the .cnb and glTF converters, cna_tool_cnb_info, the XNB fixture generator and the Inspector bridge.
Diagnostics
The opt-in CNA_DIAGNOSTICS layer: counters, gauges, frame statistics, CPU profiler zones, bounded recording and Chrome-trace export, with its overhead and limits.
Inspector
The view-only Inspector: an in-process agent, the cna-inspector bridge and its offline browser UI, with the security model and how to enable it.
Development, internals and the maintainer handbook
For contributors and maintainers: how CNA is put together, which part owns which behaviour, how to change it safely, and what evidence a change needs. Everything in this area is source-pinned to snapshot c1c316b9.
Development
The maintainer layer of this site: four altitudes (guide, architecture, internals, maintainer workflow), the evidence policy and a map of what is covered in depth.
New: Development areaHuman Takeover
A practical route for a C++ engineer taking ownership of CNA after AI-heavy development: mental model, staged curriculum, investigation method, worked changes, ownership and threading maps.
New: Development areaMaintainer Handbook
Task recipes: fix a renderer bug, change public XNA behaviour, modify a platform backend, add a regression test, update the C API, make a release.
New: Development areaRepository map & source ownership
Which of the 23 modules and 12 renderer families owns a behaviour, where public and private headers live, and how build and tests are owned.
New: Development areaInternals
Source tours of the runtime, GraphicsDevice and renderer families, the three platform implementations, audio, content, input, the smaller modules and the C API bindings.
New: Development areaGenerated references
Module, CMake option, test-target, public-header and build-axis indexes generated from the pinned CNA source.
New: Development areaDeep dives and known issues
For readers who need the exact answer: long-form explanations of what each subsystem means, how it behaves at the edges and what evidence supports each claim, and an honest list of what is wrong with or missing from CNA at this snapshot. Both areas are pinned to snapshot c1c316b9.
Deep Dives
Fourteen subject areas — framework, graphics, renderers, content, 3D, services, platforms, verification and more — each page one concept with its exact semantics, invariants, evidence and limits.
New: Deep DivesKnown Issues
What exists at this snapshot: current bugs, functional gaps, platform limitations and verification gaps, each source-pinned with its evidence and a stable identifier. Fixed defects are not listed.
New: Known IssuesCurrent bugs
Behaviour that violates an intended or documented contract, with expected and actual behaviour, source locations, blast radius and the missing regression test.
New: Known IssuesGaps and limitations
Functionality that is intentionally or currently unsupported, host and platform limits, and implementations whose evidence is thin.
New: Known IssuesExternal references
CNA targets compatibility with the Microsoft XNA 4.0 API. These external resources are useful for understanding the target API surface:
Microsoft XNA 4.0 API Reference
Official Microsoft documentation for XNA Game Studio 4.0 on Microsoft Learn.
Open ↗FNA Documentation
FNA is a managed C# reimplementation of XNA 4.0. Its documentation is a useful cross-reference.
Open ↗MonoGame Documentation
MonoGame extends the XNA API. Good reference for API patterns and expected behaviour.
Open ↗SDL3 Documentation
SDL3 is CNA's default platform layer. The SDL3 wiki is the reference for the underlying platform APIs.
Open ↗