XNB Content Pipeline

CNA::Internal::Xnb — reading Microsoft XNA Content Pipeline .xnb binaries

Overview

The XNA Content Pipeline compiled every asset — textures, fonts, sounds, models, effects — into a binary .xnb container. An .xnb file carries a header, an optional compressed body, a table of the type readers needed to deserialise its contents, and then the object graph itself, written by the reader for the asset's root type.

CNA implements that format in the CNA::Internal::Xnb namespace. The reader is not a shim or a converter: it decompresses the body, walks the type-reader table, and deserialises the object graph into live CNA objects — Texture2D, SpriteFont, SoundEffect, Model and so on — using the same ContentReader API surface FNA exposes, so reader code written against FNA's shape ports across directly.

The practical consequence: content already built by the original Microsoft tooling (or by MonoGame's mgcb) can be loaded as-is, without an offline conversion step, for every type in the registered reader set. Content that falls outside that set still has to go through CNA's loose-file path — raw images and audio, JSON descriptors, or the offline gltf_to_cnj converter for models.

Registering the built-in readers

#include <CNA/Internal/Xnb/XnbReaderRegistry.hpp>

// Call once at startup — e.g. at the top of main(), or in your
// Game subclass's Initialize(), before any content is loaded.
int main() {
    CNA::Internal::Xnb::RegisterAllBuiltInXnbReaders();

    MyGame game;
    game.Run();
    return 0;
}

Registration is global and idempotent in intent: do it once for the lifetime of the process. After that, ContentManager needs no further configuration — the XNB path is transparent from the caller's point of view.

How ContentManager resolves an asset

ContentManager does not require you to choose between pipelines. For a given asset name it prefers a .xnb when one exists, and otherwise falls back to the loose-file path (raw images and audio, or a JSON descriptor) documented on the ContentManager page.

// Content/textures/player.xnb exists → loaded through the XNB reader.
// Content/textures/player.png exists but no .xnb → loaded via SDL3_image.
// Either way, the call site is identical:
auto& tex = Content.Load<Texture2D>("textures/player");

This makes incremental migration practical in both directions. You can drop a folder of pipeline-built .xnb assets into an existing loose-file project and they will take precedence, or delete an .xnb and let the loose file take over, without touching any calling code.

The 49 registered type readers

RegisterAllBuiltInXnbReaders() installs 49 readers. They cover the asset categories a real XNA game actually ships:

Note the distinction in the last two effect rows. The stock effects (BasicEffect and friends) load because CNA implements them natively in C++ and the reader only has to restore their parameter state. A compiled .fx shader is a different matter entirely: CNA has no bytecode translator, so its reader is a registered placeholder that throws. See Effects System for the full picture.

Container format support

Three parts of the container format are worth calling out because they are where naive XNB readers usually stop short:

• LZX decompression. XNA compressed most shipped .xnb bodies with LZX. CNA carries a genuine 31 KB LZX decompressor, so compressed assets from real games load directly rather than requiring a decompression pass through external tooling.
• Two-pass shared-resource resolution. XNB object graphs can contain shared resources referenced from multiple points — a material referenced by several mesh parts, for instance. CNA reads the graph in two passes so those references resolve to the same object instead of being duplicated or left dangling.
• Fuzz hardening. The reader has been fuzzed against malformed and adversarial input. Content files are attacker-controlled data in any game that loads mods or user downloads, and a binary deserialiser is exactly the wrong place to trust your input.

Known gaps

These are real limitations, not roadmap language. If your content depends on any of them, the XNB path will not load it today.

Two adjacent Content namespace caveats belong here as well: ResourceContentManager is a pure stub — the only one of its kind in the repository — and ContentManager::Unload() clears its internal maps without disposing the assets they held.

Testing

The XNB reader is covered by 24 test files containing 134 test cases, run against binary MonoGame fixtures checked in under tests/assets/xnb/. Testing against real pipeline output rather than hand-authored byte arrays is the point: it is what makes the container-format handling credible rather than merely self-consistent.

Those fixtures sit inside CNA's broader Content test area. For how the project verifies itself overall — including the pixel-exact XNA oracle corpus and differential testing against a real FNA build — see Verification & Known Issues.