CNB Format

CNA snapshot 009d40f5 — the .cnb compiled content container, byte by byte

Overview: what CNB is and is not

CNB is CNA's own compiled runtime content container. One .cnb file holds one asset — a texture, a model, a sound effect, a font, or a game-defined type — as a small header, a table of contents, and a set of checksummed chunks. It is the default output of the cna-content build tool (see Content Pipeline) and the second tier in ContentManager's load ladder, directly below .xnb.

CNB, XNB and CNJ side by side

Where to read more: ContentManager for the load ladder, XNB Loading & Interoperability for the XNB side, Content Pipeline for producing .cnb, and Tutorial 146 for a hands-on walkthrough.

The 64-byte header

Every integer in a .cnb file is little-endian, assembled byte by byte, so the file does not depend on host byte order. f32 and f64 are IEEE-754 binary32 and binary64; CNA refuses to compile on a platform whose float and double are not (four static_asserts per type in CnbFormat.hpp). A string is a u32 byte length followed by that many UTF-8 bytes, with no terminator; the reader validates the UTF-8 (no overlong forms, no surrogates, nothing above U+10FFFF).

The reader checks the header checksum before it trusts any offset or size in the header, and the file size against the configured limit before it reads the file, so an oversized file is refused without being allocated.

Table of contents: 48 bytes per chunk

The table of contents starts at tocOffset and holds chunkCount fixed-size entries.

Layout invariants

Before any chunk byte reaches a schema decoder, CnbDocument::Parse() enforces all of the following, so a CnbDocument that exists is a structurally sound container:

• Entries are ordered by ascending offset.
• The header, the table of contents and every non-empty chunk tile the file exactly: nothing overlaps, nothing runs past the end, and every byte in an alignment gap or after the last chunk is zero. No stowaway bytes.
• A zero-length chunk is legal (an empty index buffer, a clip without tracks). It occupies no bytes and takes no part in the partition.
• All offset arithmetic is overflow-checked; the sum of every chunk's logical size is bounded (see Limits) before anything is allocated.
• Every chunk's CRC-32C matches its stored bytes.
• A compressed chunk expands to exactly its declared uncompressedSize.

Chunk multiplicity is a schema rule, checked by the schema decoder after Parse() rather than by it: a chunk type that a schema allows only once (for example TEXH or CRVH) but that appears twice is refused (“has N ‘XXXX’ chunks, but this schema allows at most one”), and so is a required one that is missing (“is missing its required ‘XXXX’ chunk”). A custom schema gets the same checks from CnbDocument::FindSingle() and RequireSingle().

Chunks, container chunks and CRC-32C

Chunk identifiers and flags

A chunk identifier is four printable ASCII bytes (0x20–0x7E). By convention an identifier whose first byte is an uppercase letter belongs to CNA's own schemas and a game-defined schema uses a lowercase first letter; the writer does not enforce that convention. The single defined flag is Mandatory:

• An unknown chunk without the flag is skipped silently. That is what lets a newer writer add data an older reader can ignore.
• An unknown chunk with the flag makes the schema decoder refuse the whole file, naming the chunk: “is marked mandatory but is not understood by this build of CNA; the file requires a newer reader.” A decoder opts in with CnbDocument::RequireMandatoryChunksUnderstood().

The two container-defined chunks

CnbWriter always emits these first, ahead of the schema's own chunks, each at most once, and refuses to let a schema add a chunk with either identifier. Schemas therefore address their own chunks by ordinal within a chunk type (CnbDocument::FindAll), never by table-of-contents index.

Every XREF name is validated by one function, CnbLogicalNameProblem(), on both the write side and the read side: it must be non-empty, well-formed UTF-8, contain no backslash, not start with /, not be drive-qualified (C:), and contain no .. segment. A file can therefore never hand a path-traversal name to ContentManager's path resolution.

CRC-32C

The checksum is CRC-32C (the Castagnoli polynomial, reflected constant 0x82F63B78) over the header prefix, the table of contents, and each chunk's stored bytes. On x86 the SSE4.2 instruction is selected at run time by CPUID (no build flag, so one binary still runs on a CPU without it); on 64-bit ARM the CRC32 extension is used where the OS reports it (on Linux via HWCAP_CRC32; always on Apple silicon); everything else falls back to a table-driven implementation. All paths produce bit-identical results, and Crc32cUsesHardwareEXT() (C ABI: cna_cnb_crc32c_uses_hardware) reports which one is in use.

An annotated minimal file

The smallest instructive file is a Curve (asset type 7, schema 1) with no keys, no CMET and no XREF: 172 bytes, two chunks. The checksum values below were computed by following the writer's algorithm by hand (standard CRC-32C, checked against the well-known value 0xE3069283 for the ASCII string 123456789) and were validated by an independent re-implementation of the parse rules above; they are illustrative, not the output of a CNA run. CNA's own specification contains the same layout with the checksums elided.

offset  bytes                       meaning
------  --------------------------  ----------------------------------------------
000000  43 4E 42 1A                 magic "CNB\x1A"
000004  01 00                       containerMajor = 1
000006  00 00                       containerMinor = 0
000008  00 00 00 00                 headerFlags = 0
00000C  07 00 00 00                 assetTypeId = 7 (Curve)
000010  01 00 00 00                 assetSchemaVersion = 1
000014  02 00 00 00                 chunkCount = 2
000018  AC 00 00 00 00 00 00 00     fileSize = 172
000020  40 00 00 00 00 00 00 00     tocOffset = 64
000028  6A 3D C5 25                 tocChecksum = 0x25C53D6A (CRC-32C of [64,160))
00002C  45 60 52 D6                 headerChecksum = 0xD6526045 (CRC-32C of [0,44))
000030  00 * 16                     reserved

000040  43 52 56 48                 chunk 0 type = "CRVH"
000044  01 00 00 00                 flags = Mandatory
000048  A0 00 00 00 00 00 00 00     offset = 160
000050  0C 00 00 00 00 00 00 00     storedSize = 12
000058  0C 00 00 00 00 00 00 00     uncompressedSize = 12
000060  5D B5 60 2B                 checksum = 0x2B60B55D (CRC-32C of 12 zero bytes)
000064  00 00 00 00                 compression = 0 (none)
000068  04 00 00 00                 alignment = 4
00006C  00 00 00 00                 reserved

000070  43 52 56 4B                 chunk 1 type = "CRVK"
000074  01 00 00 00                 flags = Mandatory
000078  AC 00 00 00 00 00 00 00     offset = 172 (zero-length chunk at end of file)
000080  00 00 00 00 00 00 00 00     storedSize = 0
000088  00 00 00 00 00 00 00 00     uncompressedSize = 0
000090  00 00 00 00                 checksum = 0 (CRC-32C of nothing)
000094  00 00 00 00                 compression = 0
000098  04 00 00 00                 alignment = 4
00009C  00 00 00 00                 reserved

0000A0  00 00 00 00                 CRVH: preLoop  = 0 (Constant)
0000A4  00 00 00 00                 CRVH: postLoop = 0 (Constant)
0000A8  00 00 00 00                 CRVH: keyCount = 0
0000AC                              end of file

A Curve written by EncodeCurveToCnb() additionally carries a CMET chunk (the canonical name Microsoft.Xna.Framework.Curve plus the content name), so a real file is a little larger than this minimal one.

Asset types

The header's assetTypeId selects the schema and the loader. The numeric values of the built-in types are frozen. They are explicit constants, not the position of an enumerator in a runtime type, and the same holds for the other identifiers a file stores: chunk identifiers are four ASCII bytes, and texture format ids are their own CnbTextureFormat values, mapped to and from SurfaceFormat by the explicit functions CnbTextureFormatToSurfaceFormat() and SurfaceFormatToCnbTextureFormat(), because SurfaceFormat is numbered by position and inserting an enumerator would otherwise renumber every file already written. Changing a runtime enum therefore never changes the format; changing that mapping is a deliberate edit.

Minting a custom type id

CnbAssetTypeIdFromName(name) returns FNV-1a-32(name) | 0x80000000 over the UTF-8 bytes of name (offset basis 2166136261, prime 16777619), so the same name mints the same identifier in the compiler, the runtime and any third-party tool. For example, "MyGame.Level" mints 0xF439D945 and "MyGame.LevelInfo" mints 0xA07759A5 (computed from the definition above). An empty name throws std::invalid_argument.

Only 31 bits are usable, so two unrelated names can collide. CNB defends against that by name, not by number: the CMET chunk of a custom-typed file must carry the canonical name, and the loader is resolved only when that name equals the one the loader was registered under. CnbWriter::Build() refuses to write a custom-typed file whose CMET name is missing or does not hash to the declared id, so a file that could never load cannot be produced. See Extending CNB.

Schemas: what each asset type stores

Container version and asset schema version evolve independently. Each schema defines its own chunks (all listed chunk ids are CNA-reserved uppercase-first identifiers).

Compression

Compression is a per-chunk field, off by default, and the codec ids are frozen wire format.

• How to turn it on. Only through CnbWriter::SetCompression(CnbCompression::Zstd, level) in C++ (or cna_cnb_writer_set_compression in the C ABI). A non-test search of the source finds no other caller: cna-content, cna_tool_source_to_cnb, cna_tool_cnj_to_cnb and cna_tool_gltf_to_cnb expose no compression option, and the Encode*ToCnb() helpers build their own writer without one. Ask IsCnbCompressionSupported(CnbCompression::Zstd) rather than assuming.
• Only when it helps. A chunk is stored compressed only if that made it smaller; the container chunks CMET and XREF are never compressed. The Zstandard level is clamped to 1…the library maximum; 3 is the default.
• Safe to read. The chunk checksum covers the stored bytes, so corruption is caught before a decompressor sees them. The declared uncompressedSize is checked against the limits before any allocation, and the stream must expand to exactly that size.
• A compressed file needs a codec. A CNA built without libzstd refuses the file while reading the table of contents (“uses compression codec 2 (Zstandard), which this build does not implement”) — which also means cna_tool_cnb_info cannot inspect it. An older CNA that predates the codec refuses any non-zero codec. Turning compression on raises that file's minimum runtime.

Memory mapping: measured and rejected

CnbDocument::ParseFile() reads the whole file into memory with an ifstream and verifies every chunk checksum before returning. There is no memory-mapped or lazily verified access, and CNA's own notes record that as a rejected option, not a pending one. CNA's mmap measurements (same developer machine and date, warm cache, a 32 MiB file of eight 4 MiB textures) report that reading the file took about 7 ms, table-driven CRC verification about 63 ms and SSE4.2 verification about 3 ms; memory mapping would have saved about 4.7 ms where hardware CRC saved about 59 ms. That is why CNA implemented run-time-detected hardware CRC-32C instead (reported end-to-end through cna_tool_cnb_info: 127 ms to 20 ms). The notes record what would change the answer: a target without a CRC instruction, loading only part of a file (which would trade away the every-chunk corruption check), or sharing one asset between processes. The alignment field keeps its meaning regardless.

Limits

Every count-driven read is bounded, so a corrupt or hostile count fails fast instead of triggering an enormous allocation. CnbReadLimits defaults:

Schemas add their own ceilings (16 mip levels and 8 representations per texture, 65 536 glyphs per font, 65 536-pixel video dimensions). The writer applies the same limits as the reader (CnbWriter::SetLimits(), defaulting to the reader defaults), so a file Build() returns is a file Parse() opens; a highly compressible document that would exceed the aggregate expansion budget is refused when you write it, not when a player loads it.

Determinism

Given identical inputs, CnbWriter produces byte-identical output: it reads no clock, no random source, no pointer value and no environment; chunks are emitted in the order the schema adds them; the table of contents is laid out in that same order; alignment gaps are zero-filled; and CMET holds only input-derived strings. CNA's specification records this as asserted in-process and across two separate OS processes, and against golden byte vectors produced by a separate Python implementation of the specification. Those tests exist in the repository; we did not run them.

The loading path

ContentManager::Load<T>(name) resolves in this order (the header comment names it xnb > cnb > literal > cnj > loose):

1. The manager's cache, keyed by the type and the lower-case-normalised name.
2. <root>/<name>.xnb. An authentic compiled XNA asset always wins.
3. <root>/<name>.cnb. The file is self-describing, so this tier needs no reader registered for T.
4. If name itself ends in .cnb, that literal file.
5. Otherwise the per-type loose-file reader: the literal path, then <name>.cnj, then the reader's own extensions (.png, .wav, .gltf…).

Inside the .cnb tier:

1. CnbDocument::ParseFile() reads the entire file and applies every invariant listed above.
2. CnbLoaderRegistry::ResolveForDocument() picks the loader for the header's asset type. For a built-in type the number is authoritative; for a custom type it additionally proves identity by name.
3. The loader decodes the chunks into a CPU-side description and builds the runtime object (creating GPU resources through the manager's GraphicsDevice); references named in XREF are loaded through the same manager, so shared textures are cached once.
4. The result must be exactly the T you asked for.

The built-in loaders are registered by every ContentManager constructor (the eight that need a device or the manager itself — Model, Texture2D, TextureCube, Texture3D, SpriteFont, SoundEffect, Song, Video — from ContentManager::RegisterBuiltinLoaders(), and Curve and AnimationClip from CnbLoaderRegistry::RegisterBuiltIns()), so a game never registers them. Load<SoundEffect> has its own specialisation with the same tier order; it does not cache, because SoundEffect is move-only.

What a failed load says

All of these are ContentLoadExceptions whose message names the file:

Extending CNB with your own asset type

CNB's extension model is deliberately much smaller than XNB's: a header carries one u32 asset type id, and the loader registered for that id decodes the file. There is no reflection, no assembly-qualified name and no per-file reader table.

1. Mint the id once: const uint32_t id = CnbAssetTypeIdFromName("MyGame.Level");
2. Write files with CnbWriter(id, schemaVersion), calling SetMetadata("MyGame.Level", contentName) (mandatory for a custom type) and AddChunk() for your data with an identifier that starts with a lowercase letter. The writer refuses a custom-typed file without the canonical name, or with a name that does not hash to the id.
3. Register a loader: ContentManager::RegisterCnbLoaderEXT<T>(id, "MyGame.Level", factory), where factory is a std::function<T(const CnbDocument&, ContentManager&)> and T is exactly the type you will pass to Load<T>().
4. Load it like any asset: getContentProperty().Load<LevelInfo>("Levels/level01").

The rules the registry enforces, all verified in CnbLoaderRegistry.hpp: the id must be in the custom range (a built-in or reserved id is refused with std::invalid_argument, and there is deliberately no route at all by which a game can register one); the canonical name must not be empty and must hash to the id; registering the same id under a different name throws std::logic_error, while repeating the same registration is accepted and does nothing; registration is process-wide, guarded by a shared mutex, and outlives any ContentManager; and lookups hand back a copy of the loader, so loading from several threads is safe with respect to the registry. A working end-to-end example is in Tutorial 146; Tutorial 148 covers custom types in depth.

Tooling

All of the following are built by default with CNA (no option gates them). This section covers the CNB-specific tools; the complete command-line catalogue is on Command-Line Tools.

Every producer is headless: it creates no GraphicsDevice and opens no audio device, so it runs on a build machine with no display, GPU or sound card. The standalone tools publish their output through a temporary file and an atomic rename, so a failing run leaves the previous .cnb intact. Numeric options are parsed strictly (the whole token, a range check, no NaN or infinity), and an option that does not apply to the asset kind being produced — --mipmaps on a WAV, say — is an error rather than something silently ignored.

cna_tool_cnb_info prints the container fields, the metadata and a chunk table with the stored and logical size of each chunk and the codec, so a compressed chunk shows how much it saved:

Content/Textures/checker.cnb
  container       1.0
  asset type      Texture2D (0x00000001)
  schema version  1
  chunks          10
  type name       Microsoft.Xna.Framework.Graphics.Texture2D
  content name    Textures/checker

  chunk flags          offset      stored     logical align  codec     checksum
  CMET  optional          544          70          70     4  none      0x…
  TEXH  required          616          24          24     4  none      0x…
  TEXR  required          640          24          24     4  none      0x…
  TEXD  required          672       16384       16384    16  none      0x…
  …                                                            (six smaller mip levels)

  external references: 0

That listing shows the shape of the output for a 64×64 Rgba8 texture with a seven-level mip chain (Tutorial 146 builds it). The offsets and sizes were derived from the writer's layout rules rather than copied from a run; the checksum values depend on your pixels and are elided.

The C ABI surface

The experimental C ABI (version 0.29.0 at this snapshot; v0.1.0-alpha.1 was 0.7.0) exports the container and every asset schema. modules/c-api/include/CNA/C/cnb.h declares 272 cna_cnb_* routes (counted from the header); none carries an _ext suffix because the header itself marks CNA-namespace surface. The family is pure functions over caller-owned bytes, plus handles for documents, cursors, writers and decoded descriptions.

The family counts group routes by name prefix (approximate); the total, 272, is the count of distinct cna_cnb_* routes in cnb.h. One gap, per CNA's own C-ABI notes: ContentManager::RegisterCnbLoaderEXT is not bound, so a C-registered loader is invoked directly (cna_cnb_loader_registry_resolve_for_document and cna_cnb_loader_invoke) rather than through a by-name Load. Separately, content.h declares 32 routes and content_readers.h 62 (a content manager, typed loads such as cna_content_manager_load_texture2d, which call ContentManager::Load<T> and therefore follow the same tier order, the XNB reader machinery, and the reflective reader builder). The Content Pipeline has no C ABI export. Experimental C API covers the ABI's status: it is source-level surface, and we did not build the C API library or run its tests, so treat this as the declared contract rather than a verified binary.

What is not implemented

Recorded so each boundary is a decision rather than a surprise:

• An Effect schema. The id is reserved and frozen; the layout is deliberately undesigned (see Asset types). Effects travel as .xnb (compiled Effect Framework bytecode) or through the loose .cnj descriptor, and cna-content writes an Effect only to XNB.
• Embedded audio or video streams. Song and Video store a reference by design.
• Block-compressed texture payloads. Format ids and the multi-representation layout exist, but no writer produces a Bc* payload and the loader uploads Rgba8 only. Asking cna-content for a DXT texture format while writing .cnb keeps the uncompressed pixels and prints a warning; use --format xnb to get the compressed texture.
• Memory-mapped or lazily verified access. Measured and rejected (see above).
• LZ4 and Deflate chunk codecs. Ids only.
• Compression through any CLI. Library and C ABI only.
• A package format bundling many assets. A different format and a different project.
• Authenticity. CRC-32C is not a signature.

Sources

Everything on this page was read from CNA at commit 009d40f5dd085c4e674d3479675fac84b12b3e0a: the container constants and identifiers in CnbFormat.hpp, the parse rules in CnbDocument.cpp, the writer in CnbWriter.cpp, the registry in CnbLoaderRegistry.hpp, the tools under tools/cnb_info, tools/source_to_cnb, tools/cnj_to_cnb and tools/gltf_to_cnb, and the C header cnb.h. Measurements and design rationale are CNA's own prose and are attributed as such above. Nothing here was built or run: CNA was not compiled for this page.