CNA Documentation
Everything you need to understand, build, and develop with CNA. Documentation is growing alongside the project - contributions welcome.
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.
Doxygen API reference: CNA does not yet have a hosted Doxygen API reference. You can generate one locally: install Doxygen, then run doxygen Doxyfile from the CNA repository root. The generated HTML will be in docs/html/index.html. Alternatively, browse the source headers directly at include/Microsoft/Xna/Framework/ on GitHub.
Getting Started
Quick introduction to CNA - what it is, prerequisites, first build, and a minimal game skeleton.
Start hereBuilding
Full build instructions for Linux and Windows, renderer selection, cross-compilation with MinGW-w64, and optional system SDL.
Releases & Versioning
Current documented release 0.1.0-alpha.1, SemVer policy, generated C++ version API, tag naming and the separate C ABI version.
First tagged pre-releasePlatforms
Target support plus the independent SDL3/SDL2/Headless/Terminal host-platform and SDL3/SDL2/Null audio selections.
Graphics Renderers
Comparison and guide for all 50 selectable renderers - the OpenGL ES family, Vulkan, SDL_GPU, SDL_Renderer, bgfx, native Direct3D 1-12, Metal, FNA3D, browser Canvas/SVG/DOM, experimental WebGPU, and the GPU-free Headless/Software renderers - maturity tiers, test coverage, tradeoffs and when to use each.
Runtime Renderer Selection
Opt-in multi-renderer builds, precedence, latching, explicit fallback, combination rules and diagnostics.
Experimental Native C API
ABI 0.7.0 source surface, measured inventory, intended package design and alpha.1's 49-versus-50 renderer-map compile blocker.
XNA Compatibility
API coverage measured type-by-type against FNA - what exists, what's missing, 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, and custom ShaderEffect.
SpriteBatch
Complete SpriteBatch guide covering Begin overloads, Draw overloads, SpriteSortMode, and BlendState configuration.
Audio System
Audio API reference: SoundEffect, SoundEffectInstance, MediaPlayer, Song, and the now-functional XACT runtime.
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 - current sprint, upcoming milestones, and 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 alpha.1's renderer-qualified XNA Effect Framework bytecode path.
ContentManager
Asset loading with Load<T>(). Prefers a .xnb when one exists, falls back to loose files.
XNB Content Pipeline
Reading .xnb binaries: 50 type readers, a real LZX decompressor, and the honest gaps.
Model Loading
The gltf_to_cnj pipeline, 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. FFmpeg-backed, desktop only.
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.
External 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 platform foundation. The SDL3 wiki is the reference for the underlying platform APIs.
Open ↗