What is CNA?

Background - the XNA programming model

Microsoft XNA Game Studio was a managed game development framework targeting Windows, Xbox 360, and Windows Phone. Released around 2006–2013, it offered developers a clean, well-structured API for 2D and 3D game development. The framework's game loop (Initialize, LoadContent, Update, Draw), its sprite batching system, content pipeline, and the Microsoft.Xna.Framework namespace hierarchy were widely praised for their clarity.

XNA was discontinued by Microsoft in 2014. The open-source community responded with notable projects:

• FNA - a fully managed C# reimplementation that is binary-compatible with XNA 4.0, built on SDL2.
• MonoGame - a cross-platform C# successor to XNA, used commercially to this day.

Both FNA and MonoGame are excellent projects. However, both remain in the managed C# ecosystem. There was no mature native C++ reimplementation of the XNA 4.0 API.

Why CNA?

CNA was created to fill a specific niche: native C++ implementation of the XNA 4.0 API. The reasons this is useful:

• No managed runtime: C++ avoids garbage collection pauses, managed heap overhead, and JIT warmup costs. Useful for performance-critical or embedded scenarios.
• Toolchain flexibility: C++ integrates directly with any C or C++ codebase, LLVM toolchains, and embedded/console targets that may not support .NET.
• API preservation: The XNA programming model is genuinely good design. Preserving it in C++ keeps the conceptual clarity that game developers appreciated while moving to a native runtime.
• Portability: host integration, audio, graphics rendering and target OS are separate axes. Alpha.1 contains Linux, Windows, macOS, Emscripten and Android paths, plus narrow experimental iOS SDL_RENDERER final-link and simulator-smoke evidence.

What problem does CNA solve?

If you are building a game or engine in C++ and you want:

• A familiar, well-structured game loop modelled after XNA
• A SpriteBatch API for 2D rendering and BasicEffect-powered 3D rendering
• A GraphicsDevice abstraction that hides renderer details — either one of 50 identities in the default compact build, or a compatible compiled set resolved at runtime, from the OpenGL ES family through Vulkan, Direct3D 1–12, Metal, SDL_GPU, SDL_Renderer, bgfx, FNA3D and WebGPU down to the GPU-free Software, PortableGL and Headless renderers for CI
• Complete input handling — Keyboard, Mouse, GamePad (a real SDL3 bridge with rumble, trigger rumble, LED and hot-plug), and a TouchPanel that genuinely detects all 10 XNA gesture types
• Audio via SoundEffect, SoundEffectInstance, and MediaPlayer — plus a real XACT implementation that parses the XGS/XWB/XSB binary formats and plays them back, rather than a facade
• Real SystemLink multiplayer via NetworkSession, backed by genuine ENet over UDP with real LAN discovery. (PlayerMatch and Ranked correctly no-op, as they require Xbox Live.)
• A real .xnb content pipeline, with loose-file loading as a fallback
• The ability to swap renderers without changing game code

…then CNA provides a substantial alpha foundation in native C++23 — with renderer-qualified effect and format behavior, platform-specific media boundaries, and pre-1.0 API stability caveats.

What CNA is not

• CNA is not a C# framework or a .NET library.
• CNA is not affiliated with or endorsed by Microsoft Corporation.
• CNA does not use any Microsoft, Xbox, or XNA branding assets. XNA is referenced only as the compatibility target and API inspiration.
• CNA is not a game - it is a framework and runtime abstraction layer.
• CNA's platform claims are scoped: macOS/Metal has automatic CI, while iOS is experimental and limited to SDL_RENDERER final-link plus a one-frame simulator smoke path; tvOS is unsupported.
• CNA is not yet recommended for shipping commercial games, though it is suitable for research, demos, and open-source development.

Relationship to FNA and MonoGame

In practical terms: where FNA provides a C# class implementing a particular XNA behaviour, CNA translates that behaviour into C++23 idioms - replacing managed types with RAII, delegates with virtual methods, and properties with getter/setter methods. The game-facing API shape follows FNA's C# surface as the authoritative XNA 4.0 reference, while the internal implementation is native C++ throughout.

Both FNA and MonoGame remain excellent choices for managed C# game development. CNA serves the C++ ecosystem specifically.

C++ API differences — the CNAEXT marker

Declarations marked with CNAEXT in CNA's source code are not part of the XNA 4.0 public API. A strict CMake mode turns use of marked declarations into diagnostics that can be promoted to errors, giving ports a mechanical XNA-purity check. When consuming CNA directly you can use these declarations freely; the marker means they have no XNA counterpart.

Some of it is plain C++ glue (iterator support, RTTI helpers, RAII wrappers), but a lot of it is substantial functionality XNA never had:

• Graphics: ShaderEffect for renderer-native custom shaders, PbrEffect/SkinnedPbrEffect for physically based rendering, SkinnedModelEXT with animation types, MorphTargetEXT blend shapes, tangent/skinned vertex types, and extended surface formats. XNA Effect Framework bytecode is a separate compatibility path on qualified renderer builds.
• Input: around 17 GamePad extension methods (GUID, light bar, trigger vibration, gyro/accelerometer, power info, touchpad fingers, Steam handle), paddle and touchpad buttons, scancode-based Keyboard methods, MouseCursor and TextInputEXT.
• The whole CNA:: namespace — roughly 58 public headers that are not XNA at all: Camera, FileDialog, MessageBox, SystemTray, Clipboard, UrlLauncher, Locale, PowerInfo, DisplayInfo, SystemInfo, full Joystick/Haptics APIs, Logger, and render-pipeline settings including PbrMaterial, TonemappingMode and ShadowQuality.

The CMake options gating the extended layers (CNA_CNAEXT and CNA_DEVICES) both default to OFF. Their compiled and registered tests therefore depend on the configured build; the tag includes focused Devices CI, while CNAEXT coverage is not universal across the workflow matrix.

Technology stack

• Language: C++23 — requires GCC 12+, Clang 15+, or MSVC 2022 v17.8+
• Platform implementations: SDL3 by default, real SDL 2.30, Headless, or POSIX Terminal through CNA_PLATFORM
• Image loading: SDL3_image (vendored submodule) — PNG, JPG, BMP, and more
• Audio-device selection: SDL3 by default, SDL2 or Null through the independent CNA_AUDIO_PLATFORM axis; only SDL3 enables alpha.1's high-level XNA playback/decoding engine
• OpenGL renderer: easy-gl plus meta-gl — sibling repositories used by the five EasyGL identities: OPENGLES2, OPENGLES3, OPENGL33, WEBGL1 and WEBGL2
• DirectDraw renderer: free-direct — a sibling repo reimplementing a DirectX 3 / DirectDraw 2D subset over SDL3; required only for the FREEDIRECT renderer
• Runtime support: sharp-runtime — a required C++23 sibling implementing the practical System::* surface CNA uses, including primitives, collections, IO, text/JSON/regex, networking, threading, XML, globalization and numerics. This is where bytecs, intcs and Single come from
• Video playback: FFmpeg — real libavcodec/libavformat decoding for VideoPlayer, with PTS-driven pacing. The video translation units are present for Linux and macOS and excluded on Emscripten, Android and Windows in alpha.1
• Networking: in-tree enet for reliable UDP; also in-tree are cgltf, stb and a pinned wgpu-native
• Build system: CMake 3.20+ with a compact single-renderer default through CNA_GRAPHICS_RENDERER, or an opt-in compatible set through CNA_GRAPHICS_RENDERERS and pre-device runtime selection
• Test source inventory: 568 C++ test files and 8,263 static GoogleTest-family definitions at the tag; the instantiated/run inventory varies by configuration
• Model tooling: a runtime glTF 2.0 loader plus the offline gltf_to_cnj converter for deployment-oriented .cnj Model/AnimationClip assets

Real-world validation

Unit tests only prove that the code does what its author expected. CNA is checked against several things it does not control:

• A real XNA reference renderer. The oracle corpus under tools/xna-oracle/ holds 39 scenes rendered by a genuine C#/XNA reference renderer, diffed pixel-exactly (--tolerance 0) against CNA's DIRECTX9 output. DIRECTX9 is the renderer that uniquely targets pixel-exact XNA 4.0 authenticity.
• A running FNA build. A C# harness links the real FNA build, dumps reference values to JSON, and a script diffs them against CNA's own output. Ground truth comes from executing the reference implementation, not from reading its source.
• The official XNA sample collection. cna-samples ports Microsoft's XNA Game Studio 4.0 samples to C++ on CNA: 86 samples, of which 63 currently build.
• GPU and integration verification. Renderer-specific programs and CTest entries are registered for the selected build; use ctest -N in that build instead of quoting a tree-wide universal count.

Beyond that, CNA Craft and the browser demos exercise real game-code paths. They remain independent evidence: repository CI does not continuously launch every hosted demo. Media has 29 test sources with 286 static definitions at the tag; Storage has one source with five, so the latter is still deliberately described as thin. See Verification & Known Issues.

Licence Ms-PL License

CNA is licensed under the Microsoft Public License (Ms-PL). See the tag's LICENSE file for full terms. Portions of CNA are derived from or based on FNA, which is also licensed under the Ms-PL.