Chapter 33 ContentManager and Asset Resolution

On a cache miss, let base = BuildAssetPath(assetName). The generic Load<T> path and the Texture2D, SoundEffect, and TextureCube specializations follow this order:

The XNB probe appends .xnb to the complete name. Therefore Load<Texture2D>("art/logo.png") first tests art/logo.png.xnb, then the literal PNG. To parse art/logo.xnb as XNB, pass "art/logo". Passing the suffix itself tests logo.xnb.xnb; if absent, the loose reader receives the original XNB file. Dots in logical names have no special meaning.

A literal path wins over its sidecar. With hero.png and hero.cnj present:

The first call selects the literal PNG after the extra XNB probe. The second selects hero.cnj before the native-extension list. A CNJ sourceFile then starts a checked nested load; it is not a direct decoder bypass.

RootDirectory is a base path, not a sandbox. BuildAssetPath joins it with the logical name but does not reject absolute paths, canonicalize dot segments, or check symlinks:

Top-level names must therefore be trusted or validated by the application. Internal references have narrower rules:

• •

  CNJ sourceFile rejects absolute paths, traversal and symlink escape, another CNJ, and implicit sidecar cycles.

• •

  ContentReader::ReadExternalReference<T> rejects absolute, drive, UNC, and normalized above-root paths.

• •

  XNB Song and Video readers contain companion files within the content root. For an explicitly loaded external XNB, the XNB’s own directory becomes the authorized bundle root.

These checks compare canonicalized paths before the eventual open; they are not a race-proof open-by-handle policy. Chapter 37 records the TOCTOU boundary.

A direct texture constructor with a concrete path remains useful for a small program:

Game instead exposes its configured manager in LoadContent:

RegisterTypeReader<T> installs one loose reader for a C++ type. RegisterCnjLoader<T> installs named CNJ factories that produce a type without a pre-existing reader. Both are CNAEXT surfaces; complete registration before loading begins.

Successful generic loads enter a strong cache keyed by requested type and normalized logical name. The write occurs only after a reader returns, so a failed top-level load can be retried. Specializations differ:

Unload clears only the generic and texture caches. It does not dispose caller-held values, clear readers, reset the root/device/provider, or refresh the manifest. Dispose calls Unload once and marks the manager; later loads throw std::runtime_error. The default C++ destructor does not call that public method.

Nested reader activity is not transactional. A reader can cache dependencies and then fail, leaving those successful nested entries. There is no provisional key or cycle detector, so a recursive load of the same uncached type/name can recurse until stack exhaustion.

ContentLoadException covers many validated content errors, including malformed XNB/CNJ data, absent reader registration, bad reader indices, and unsupported reader versions. It is not a universal wrapper. Depending on the selected path, callers can also see std::runtime_error, FileNotFoundException, EndOfStreamException, std::bad_any_cast, or an exception from custom reader code. Empty names are not rejected up front.

The manager’s maps, manifest vector, strings, pointers, and disposed flag are unsynchronized. Concurrent load/unload/registration/root/manifest operations can form C++ data races. Single-threaded reentrancy also has hazards: self-loading cycles have no sentinel, and a reader that replaces its own registration can destroy the active object. Register and configure first, serialize manager mutation through one owner, and publish completed assets to workers.

The IServiceProvider* constructors retain a raw pointer, but the pinned ContentManager never calls GetService. A GPU-backed standalone manager needs an explicit device:

Game performs that association for its own manager. Both pointers remain borrowed.

ResourceContentManager is a surface stub. Its protected OpenStream ignores the asset name and throws std::runtime_error; inherited Load<T> does not call that virtual method. The class therefore loads ordinary files only through its base behavior and does not provide embedded resources.

GetContentManifest lazily scans the root and returns a reference to manager-owned rows. RefreshContentManifest rebuilds them. A row records a logical path, XNB/CNJ presence, native extensions, and—for readable uncompressed XNBs—reader names. GetXnbReaderUsageSummary aggregates those names and reports whether the global registry currently contains each key.

The manifest is diagnostic only:

• •

  Load performs fresh filesystem probes and never consults it.

• •

  Presence does not establish a valid file, compatible reader, device, or loadable graph.

• •

  Compressed or malformed XNBs can appear with an empty reader-name list.

• •

  Directory and hash-map iteration make row and summary order unstable.

• •

  Missing or inaccessible trees can yield an empty or partial snapshot without a public scan-status result.

• •

  Refresh can invalidate held element references and iterators; copy before sorting or retaining the data.

Unload, disposal, and root changes do not automatically refresh this separate snapshot.

Loose readers and XNB readers solve different problems. Loose Song and Video simply wrap the selected media path (Video also requires the manager device). XNB readers decode the XNA-specific body and resolve an external companion.

Use an extensionless logical name when XNB/CNJ precedence is desired; use a concrete literal filename when the native file itself must win. Treat the root and TitleContainer as trusted-path conveniences, not sandboxes. Register readers and attach a graphics device before loading, keep manager mutation serialized, and call Unload when deliberately changing the cache namespace.

Existing XNA/FNA games can reuse compiled assets only for reader families supported at this pin. Arbitrary Effect bytecode remains a separate unsupported contract (Chapter 17); CNJ or a native conversion is appropriate where the XNB reader or runtime capability is absent.

ContentManager’s contract is a deterministic existence-priority resolver with type-specific caching. XNB, literal, CNJ, and native-extension paths are not fallback attempts after decode failure. The distinction explains most surprising content behavior: explicit filename choice, root changes hidden by cache, sidecars shadowing native media, and a manifest that inventories candidates without certifying them.