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 SDL3 (an SDL2 platform layer remains selectable in FNA).
• 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. This snapshot contains Linux, Windows, macOS, Emscripten and Android build paths, all served by the SDL3 platform layer, with full test runs on a physical Mac mini M4, plus experimental iOS with iOS Simulator execution and pixel evidence (no physical device). See Platforms and Windows, X11 and Wayland for what is tested where.

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 14 identities in the default compact build, or a compatible compiled set resolved at runtime, from the OpenGL ES 3, OpenGL 3.3 and WebGL 2 family through Vulkan, Direct3D 9 and 11, Metal, SDL_GPU, SDL_Renderer, FNA3D and WebGPU, down to the GPU-free Software 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 sessions and JoinInvited go through CNA’s own self-hosted Gamer Services server, not Xbox LIVE; without a configured server they are refused with GamerServicesNotAvailableException.)
• A real .xnb reader and a build-time content pipeline (cna-content) that writes .xnb and CNA's own .cnb; ContentManager prefers .xnb, then .cnb, then loose files
• 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 this snapshot adds since alpha.1

The alpha.1 tag shipped the framework described above. The development line documented on this site has moved on in these areas (each links to its reference page; all of it is pre-1.0):

• A curated renderer set: 14 identities over 12 implementation families. A renderer name outside the 14 is a configure-time error, never a silent fallback. See Graphics Renderers and Runtime Renderer Selection.
• Modern graphics capabilities: VULKAN, SDL_GPU, WEBGPU, the EasyGL family, DIRECTX11 and METAL report float and half render targets, shadow and image-based-lighting sampling, and (on capable devices) compute and indirect draws, where the code and a test both exist. GraphicsCapability grew from 14 to 19 members and a RendererCapabilityProfile API reports 32 features, 22 limits and per-format usage.
• Native platform layers: CNA_PLATFORM offers three implementations (SDL3, HEADLESS, TERMINAL; SDL3 reaches Windows, X11 and Wayland through SDL’s video drivers) and CNA_AUDIO_PLATFORM three (SDL3, NULL, ALSA); FFmpeg video is optional. See Windows, X11 and Wayland.
• Content authoring: the Content Pipeline and the CNB format, an XNB writer and 61 built-in XNB readers, and the command-line tools.
• XNA API representation: every one of the 331 documented XNA 4.0 runtime types and 3,627 documented members is represented (a census of representation, not of behaviour), including the Framework.Design converters; the Content Pipeline API is separately represented (128 of 128 types, 705 of 705 members).
• Development tools: opt-in Diagnostics (counters, profiler zones, traces) and a view-only Inspector.
• CNAEXT extensions: the opt-in CNA::Graphics module with retro post-processing effects (CRT, colour depth, ASCII) and debug drawing — see CNAEXT Extensions.
• C# through CNA.NET: a Microsoft.Xna.Framework-compatible C# facade over the C ABI that runs original XNA 4.0 C# game source on CNA’s native runtime — see C# with CNA.NET.
• Gamer Services and avatars: local profiles, the Guide, achievements, leaderboards, avatars and NetworkSession, with an optional self-hosted server for accounts and online sessions — see Gamer Services & Avatars.
• An experimental C ABI: version 0.46.0 (alpha.1: 0.7.0), 60 headers and 3,210 routes; its own release gate reads "Not ready" and the library is not built by CNA’s CI; CNA.NET builds and uses it on Linux. See Experimental Native C API.
• Stricter XNA behaviour: the default GraphicsProfile is Reach and is now enforced on every renderer, so features such as multiple render targets, occlusion queries and 32-bit indices need HiDef to be requested.

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 was tested on a physical Mac mini M4 (seven renderer trees, full suites, no failures; presentation not observed on screen) and has build-and-test CI on hosted runners; iOS is experimental, with iOS Simulator execution and pixel evidence but no physical device; tvOS is unsupported. Android has no CI lane in this snapshot, and the Windows lanes are manual.
• 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 (names, overloads, enum values) is checked against Microsoft's own XNA 4.0 documentation and DLL metadata, FNA remains the day-to-day readable reference, and where a measured XNA 4.0 behaviour and FNA disagree the project rule is that XNA 4.0 wins. 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. Defining CNA_STRICT_XNA_API for a translation unit turns use of marked declarations into [[deprecated]] diagnostics that can be promoted to errors, giving ports a mechanical XNA-purity check for the XNA-shaped namespaces (the repository's own strict-mode harness covers only Microsoft::Devices and its sensors). 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, SkinningData and AnimationPlayer for skeletal animation (the Avatar path has its own SkinnedModelEXT), MorphTargetEXT blend shapes, tangent/skinned vertex types, extended surface formats, shadow-receiver and image-based-light interfaces, and the RendererCapabilityProfile queries on GraphicsDevice. XNA Effect Framework bytecode is a separate compatibility path on qualified renderer builds (11 of the 14 identities: FNA3D always, the other ten only with their default-OFF build option).
• Input: about 19 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, TextInputEXT, opt-in mouse-to-touch emulation and MIME-typed clipboard data.
• The whole CNA:: namespace — more than 250 public headers that are not XNA at all (99 at alpha.1): Camera, FileDialog, MessageBox, SystemTray, Clipboard, UrlLauncher, Locale, PowerInfo, DisplayInfo, SystemInfo, full Joystick/Haptics APIs, Logger, the CNA::Content container and pipeline layer, CNA::Diagnostics, CNA::Inspector, and the opt-in CNA::Graphics extensions (retro effects, debug drawing and shader packages). Those headers are not individually tagged: they are identified by their CNA:: namespace, by CNA_CNAEXT gating or by the ...EXT naming convention.

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 snapshot has a focused Devices CI workflow, but no workflow builds with CNA_CNAEXT=ON. The CNA::Graphics extensions are deliberately small — three retro post-processing effects, a debug-drawing helper and portable shader packages; see CNAEXT Extensions.

Technology stack

• Language: C++23 with CMake 3.20+. CI workflows use GCC 14, current AppleClang, MSVC (the manual Windows lanes), mingw-w64 GCC and Emscripten 6.0.3; CNA performs no compiler-version check and uses <format>, so very old toolchains will not work
• Platform implementations: SDL3 by default (the one windowing implementation), Headless, or POSIX Terminal through CNA_PLATFORM; CNA_ENABLE_SDL=AUTO|ON|OFF decides whether SDL is configured at all
• Image loading: an in-tree stb-based decoder for loose image files — PNG, JPG, BMP, and more; SDL3_image remains a vendored submodule of the SDL3 build
• Audio-device selection: SDL3 by default, Null or ALSA through the independent CNA_AUDIO_PLATFORM axis; SDL3 and ALSA enable the high-level XNA playback/decoding engine (ALSA with CNA's own mixer and vendored WAV, Ogg Vorbis, MP3 and FLAC decoders); OPENAL and WASAPI are reserved and refused
• OpenGL renderer: easy-gl plus meta-gl — sibling repositories used by the three EasyGL identities: OPENGLES3, OPENGL33 and WEBGL2
• 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. This snapshot needs sharp-runtime's apple/m4-stabilization branch: its default branch lacks the Resources and Xml.Serialization components CNA now requires
• Video playback: FFmpeg, now optional (CNA_ENABLE_VIDEO=AUTO|ON|OFF) — real libavcodec/libavformat decoding for VideoPlayer, with PTS-driven pacing, where it is found on Linux and macOS. The Video types exist in every build and throw NotSupportedException without a backend; FFmpeg is never built for Windows, Emscripten, Android or iOS
• Networking and vendored libraries: in-tree enet for reliable UDP; also in-tree are cgltf, stb and dr_libs. Other pinned dependencies (FNA3D with MojoShader, wgpu-native, SDL_shadercross) are fetched at configure time only when the matching renderer or option is selected
• 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; 17 visible configure presets; on native ELF Linux with GNU or Clang and CMake 3.27+ the framework builds as one shared libcna.so by default
• Test source inventory: 813 C++ test files and 11,380 static GoogleTest-family definitions at this snapshot (781 of the files contain a counted macro); the instantiated/run inventory varies by configuration, and no CTest total is published
• Model and content tooling: a runtime glTF 2.0 loader, the offline gltf_to_cnj converter for .cnj Model/AnimationClip assets, and the cna-content build tool, which also writes .cnb and .xnb and imports .fbx and .x models at build time (with cna_tool_gltf_to_cnb for glTF); see Command-Line Tools

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 (256×256) rendered by the genuine Microsoft XNA 4.0 runtime — run under Wine and DXVK on Linux, not on Windows — and diffed pixel-exactly (--tolerance 0) against CNA's DIRECTX9 output. DIRECTX9 is the renderer that uniquely targets pixel-exact XNA 4.0 authenticity: it is recorded in the repository as matching all 39 scenes (the last consolidated dated report covers 31 scenes; later per-scene notes record the rest), but the check is manual and no CI job runs it. EasyGL and Software have a CTest on two line scenes only (the EasyGL test fails on any pixel difference; the Software test only if a scene does not render), Software has been measured at 18 of 39 byte-exact, and FNA3D gates only that the scenes render.
• 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 harness is run manually and is not part of CI.
• An API representation census. tools/audit_xna_runtime_surface.py compares CNA's public headers with Microsoft's own XML documentation and DLL metadata for the ten XNA 4.0 runtime assemblies: all 331 documented types and all 3,627 documented members are represented. That measures representation, not behaviour; behaviour is verified only for the subsets described on the Verification & Known Issues page.
• The official XNA sample collection. cna-samples ports Microsoft's XNA Game Studio 4.0 samples to C++ on CNA. As of cna-samples 5db32e6 (3 October 2026) its plan audits 153 entries (SAMPLE-001 to SAMPLE-153), not 153 games: 91 are complete C++ ports, 8 relevant XNA 4.0 C# programs remain, and 54 entries are not port targets (XNA 3.x or older, Silverlight, WinForms tools, VB.NET, C++, asset packs). 90 C++ builds are playable at samples.libcna.com. The Racing Game Kit is ported in its own plan and is not hosted, because its original content is not treated as redistributable by the sample gallery. The original C# samples also run unchanged through CNA.NET. Those results are for CNA's apple/m4-stabilization branch at that date, not a claim about any other revision.
• 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. 32 cross-renderer parity fixtures are registered for four renderer families (EasyGL, WebGPU, SDL_GPU and Direct3D 11) against the fixtures' own assertions — not against real XNA — and a 148-asset glTF conformance corpus (140 captured, 8 rejected safely) has renderer-owned goldens.

Beyond that, CNA Craft (its source lives in the cna-lab repository) and the browser demos exercise real game-code paths. They remain independent evidence for the CNA revision each was built with: repository CI does not continuously launch every hosted demo. Media has 30 test sources with 304 static definitions at this snapshot; Storage has one source with 14, 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 alpha.1 tag's LICENSE file (unchanged at snapshot c1c316b9) for full terms. Portions of CNA are derived from or based on FNA, which is also licensed under the Ms-PL.