XNB Loading & Interoperability

CNA::Internal::Xnb — reading and writing 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 needs a custom reader, or has to go through CNA's other paths — raw images and audio, JSON descriptors, the CNB container, or the offline gltf_to_cnj converter for models. The opposite direction is new: CNA can produce .xnb from source files.

Registering the built-in readers

#include "CNA/Internal/Xnb/XnbBuiltInReaders.hpp"
#include "Microsoft/Xna/Framework/Content/ContentManager.hpp"

using Microsoft::Xna::Framework::Content::ContentManager;

// A tool or test with no Game: register once, then use a ContentManager directly.
int main() {
    CNA::Internal::Xnb::RegisterAllBuiltInXnbReaders();   // idempotent

    ContentManager content(nullptr, "Content");            // no Game, no GraphicsDevice
    // Types that need no GPU load fine: primitives, math, collections, ...
    auto names = content.Load<std::vector<std::string>>("data/names");
    return static_cast<int>(names.size());
}

The header is CNA/Internal/Xnb/XnbBuiltInReaders.hpp (it still lives under Internal, which is a known ergonomics gap). Registration is global and idempotent: a repeat registration of the same canonical name is silently ignored, so calling it twice, or calling it in a Game that has already done so, is harmless. Assets that create GPU resources (Texture2D, Model, …) additionally need a graphics device from setGraphicsDevice() or an IGraphicsDeviceService — which a Game provides.

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, then a .cnb, and otherwise falls back to the loose-file path (raw images and audio, or a JSON descriptor) documented on the ContentManager page. The .xnb is dispatched from the file’s own type-reader table — no reader for the requested T has to be registered on the manager.

// Content/textures/player.xnb exists -> loaded through the XNB reader.
// Content/textures/player.cnb exists (no .xnb) -> loaded through the CNB loader.
// Content/textures/player.png exists but neither -> decoded from the image file.
// Either way, the call site is identical, and the result is returned by value:
Texture2D tex = getContentProperty().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. On platforms with packaged assets (Android) the .xnb tier reads through the platform’s asset route; the .cnb tiers use the ordinary filesystem, and whether a .cnb loads from an APK has not been verified.

The 61 built-in type readers

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

Counts: 13 + 13 + 3 + 1 + 4 + 4 + 5 + 1 + 4 + 2 + 11 = 61 (60 without Decimal). Eleven of these readers are new since alpha.1’s 50: the legacy TextureReader alias, EffectMaterialReader, ExternalReferenceReader, and eight closed collection readers.

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 (FNA3D always provides it; eight other renderer families offer it through opt-in build options that default to off). See Effects System.

Container format support

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

• LZX and LZ4 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. The header’s LZX flag (0x80) and the LZ4 flag MonoGame uses (0x40, a raw single block decoded by an in-tree, bounds-checked decoder) are both honoured for an asset you load directly; a header with both bits set is refused, and an LZ4 file reached as an untyped external reference from another .xnb (the std::any-returning ReadExternalReference() path used by ExternalReferenceReader) is refused at this snapshot; the typed external references (Texture2D, TextureCube and compiled effects) load through ContentManager::Load<T>, whose loader does decode LZ4.
• The header. Magic XNB, a platform byte (sixteen accepted values, including the deprecated ones FNA still accepts), container version 4 or 5, the flags byte and the file’s declared total length, which is cross-checked against the bytes actually read before any pointer arithmetic uses it.
• 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.
• Hard limits and fuzz hardening. 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. By default the reader refuses a file of 2 GiB or more, a decompressed payload over 256 MiB, a string over 1 MiB, more than 4,096 type readers, more than 1,000,000 shared resources, a collection of more than 10,000,000 elements, or an object graph nested more than 256 deep; and it is exercised by fuzz-style tests over the container, the LZX decoder and the writer’s inputs.

Writing XNB from CNA

At alpha.1 this page said CNA does not author XNB files. That is no longer true. The build-time cna-content tool (see Content Pipeline) runs source files through importer → processor → writer, and the writer can be either CNA’s native .cnb or an XNA-compatible .xnb. Importers and processors are identical either way; only the writer differs, so every source route can reach both containers except where a container has no representation (for example, a compiled Effect has no CNB schema, but does have an XNB writer).

# Build a content folder into XNA-compatible .xnb files (XNA 4.0 container, LZX-compressed)
cna-content build ContentSource -o Content --format xnb \
    --xnb-platform windows --xnb-version 5 --xnb-profile reach --xnb-compress lzx

The XNB writers cover the same families as the readers: textures (2D, 3D, cube), SpriteFont, SoundEffect, Song, Video, models together with their vertex and index buffers and the five stock effects, compiled Effect bytecode, effect materials and external references, plus the primitive, math and Curve value types and a closed set of collections. The LZX compressor is a real encoder (one verbatim block per 32 KiB frame with Huffman-coded literals and matches), not a pass-through. Two build-time details matter to porters:

• glTF to XNB drops data, with named warnings. An XNB Model built from glTF has no place for the skeleton, animation clips, lights or morph targets, so they are dropped with a warning; PBR materials are downgraded to the corresponding stock effect; generated child assets and external-effect parts are refused. The .cnb route keeps skeleton, animation, morph targets and lights. Choose .cnb for animated glTF.
• The XNA-shaped API is here too. cna-content also builds a real XNA .contentproj, and CNA carries an implementation of the Microsoft::Xna::Framework::Content::Pipeline namespace (importers, processors, ContentCompiler, IntermediateSerializer); the Content Pipeline page states exactly what that claim covers.

An .xnb is also a valid source for cna-content: a supported built-in root type is transcoded to a native .cnb (an .xnb is not written back as .xnb from this route). For a step-by-step walk-through see Tutorial 147.

Custom XNB readers

XNA deserialised user-defined types by .NET reflection. CNA has no reflection, so every reader is registered explicitly, keyed by the canonical reader name that appears in the .xnb file’s reader table. Three mechanisms are available:

None of these is part of the 61 built-ins; they are yours to register before the first load that needs them. Tutorial 148 takes one game type through all three routes, including the CNB equivalent.

Diagnosing XNB problems

A failed load throws ContentLoadException, with the underlying cause attached when there is one. The common causes are a bad magic or platform byte, a version other than 4 or 5, a declared length that disagrees with the file, a decompression failure, or a reader-table entry with no registered reader. Before you load anything, ask the manager which reader names your content root needs:

for (const auto& usage : getContentProperty().GetXnbReaderUsageSummary()) {
    if (!usage.isRegistered) {
        // usage.readerName is the canonical name, usage.fileCount how many .xnb files need it
        std::printf("no reader for %s (%d file(s))\n",
                    usage.readerName.c_str(), usage.fileCount);
    }
}

The manifest behind that call (GetContentManifest(), rebuilt with RefreshContentManifest()) is a point-in-time scan of the content root: one entry per logical asset name, recording whether an .xnb or .cnj exists, any other extensions found, and the reader names read from an .xnb’s type-reader table. The table is read only from uncompressed, well-formed files, so a compressed file appears with an empty reader list rather than as a scan failure.

What CNA reports about XNA 4.0 compatibility

Whether CNA’s output loads in a genuine XNA runtime is a claim that this site cannot check for itself, so it is stated as CNA reports it, with dates and hosts:

• CNA’s own interoperability notes report a harness that loads CNA-written files through a genuine Microsoft XNA 4.0 ContentManager on a Debian host under Wine with DXVK: six of six uncompressed fixtures (a Texture2D with mip levels, a SoundEffect, a SpriteFont, a Curve, a List<string> and a Model with a BasicEffect) and, after CNA added a five-byte trailer that genuine XNA requires after the final LZX block, the same six LZX-compressed, dated 6 September 2026. CNA’s older interoperability document (3 September 2026) still says nothing had been run against a real XNA runtime; the later dated harness notes and the tool’s own help text say it was, so treat the older text as stale. No committed machine-readable result log was found, and the run is not part of any CI workflow.
• CNA reports byte-identical output to genuine XNA 4.0 for a List<string> and to MonoGame for a Texture2D and a SoundEffect, pinned by golden tests in its own suite.
• An independent conformance parser, tools/xnb/xnb_conformance.py, shares no code with CNA’s reader, and cna_tool_xnb_interop_fixtures regenerates the committed CNA-written corpus.

None of this measures MonoGame or FNA loading CNA’s output beyond what CNA reports, and none of it says every asset type has been checked: it is evidence for those six fixture roots, not a general guarantee. Xbox 360 output is refused by default for that reason.

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 notes belong here as well. ResourceContentManager, which was a stub at alpha.1, is implemented in this snapshot: it reads binary resources from a System::Resources::ResourceManager through the protected OpenStream() seam (the public Load<T>() ladder still searches files). And ContentManager::Unload() clears the manager’s cache of loaded assets; a copy you already hold stays valid.

Testing

At this snapshot the Content module’s test tree holds 170 C++ test sources with 1,872 statically discoverable GoogleTest-family definitions (alpha.1: 112 sources and 978), including XNB container, reader-registration, writer, LZX encoder/decoder, real fixture, effect, audio, texture and model cases; the new content-pipeline module adds 47 sources with 487 definitions. These are counts of test definitions found by scanning the source, not of tests executed: 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.