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 50 built-in type readers

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

Stock-effect readers restore native CNA effect state. The general EffectReader instead reads the already-compiled Direct3D 9 Effect Framework payload and builds a reflected runtime effect. That succeeds only when the active renderer reports GraphicsCapability::CompiledEffects; it is not a universal renderer feature. See Effects System.

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 alpha.1 Content module contains 112 C++ test sources with 978 statically discoverable GoogleTest-family definitions, including XNB container, reader-registration, real fixture, effect, audio, texture and model cases. The executable subset remains configuration-dependent. Tests against real pipeline output are especially valuable because they check compatibility beyond hand-authored byte arrays.

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.