Content and the manifest
A Labrador game’s content lives in files beside the executable, listed in a manifest the game loads at startup. Names, handles and resources explains the model; this guide is the practical side: adding a file, getting it beside the executable, and loading content the engine has never heard of. If a build fails after a change, Read a build error shows how to find the line that matters.
Adding a texture or a font
Section titled “Adding a texture or a font”-
Put the file in your content folder, under the directory its group names. A starter project’s content folder is
game\content, withgame\content\fontsin it; addgame\content\texturesfor textures. Put a picture in your game does every step of this section for one picture, with the whole manifest and the exact lines to add. -
List it in
content/manifest.jsonby name, without its extension, in a group of the right kind. A new kind of file needs a new group:samples/linesweeper/content/manifest.json {"assets": [{"kind": "font","directory": "./fonts/","names": ["jetbrains_mono_bold_16"]},{"kind": "texture","directory": "./textures/","names": ["white"]}]}samples/linesweeper/content/manifest.json at
aceb130 -
Make sure the build copies it beside the executable (next section).
-
In code, refer to it by that name once, where you build the thing that draws it. The Sprites and text guide covers the drawing.
If the name in code does not match the manifest, the game stops with an error naming the asset when it resolves the name. If the file is missing, it stops at load, naming the file.
The manifest document accepts only assets. Each group accepts kind,
directory, names and optional, which defaults to false. Unknown fields
are refused with the file, group index and unexpected spelling, so optionl
cannot silently make a bank required. Correct a typo or remove an unsupported
field. Kinds and resource names are values your game chooses, including kinds
you register yourself.
Getting content beside the executable
Section titled “Getting content beside the executable”The game reads its manifest from the folder the executable is in, wherever it was started from, so the build copies the content there. The minimal sample does it with a custom target that runs on every build, so an edited file arrives even when no code changed:
add_custom_target(sample_content ALL)add_custom_command(TARGET sample_content POST_BUILD COMMAND "${CMAKE_COMMAND}" -E copy_if_different "${CMAKE_CURRENT_SOURCE_DIR}/content/manifest.json" "$<TARGET_FILE_DIR:MinimalSample>/manifest.json" VERBATIM)add_custom_command(TARGET sample_content POST_BUILD COMMAND "${CMAKE_COMMAND}" -E copy_directory_if_different "${CMAKE_CURRENT_SOURCE_DIR}/content/fonts" "$<TARGET_FILE_DIR:MinimalSample>/fonts" VERBATIM)add_dependencies(MinimalSample sample_content)When you add a folder of content, add a copy_directory_if_different line for it beside the
fonts one. LineSweeper copies fonts and textures this way.
Optional content and stale copies
Section titled “Optional content and stale copies”copy_directory_if_different adds and updates files, and never removes one. A file you delete
from content/ stays in the build folder until that folder is cleaned, so the game goes on
loading it. A required file the manifest still names keeps working on your machine and is
missing only from a clean build or a release, and a sound bank the manifest marks optional is
never replaced by the silent one, because its stale copy is still there.
A game with content it may delete names its files instead, as two lists: the ones that must be
there and the ones that may be absent. The check has to run on every build rather than once at
configure time, so the always-run target calls a script with cmake -P; an if(EXISTS) in the
CMakeLists.txt itself would be evaluated only when the project is configured:
# stage_content.cmake, run as:# cmake -DSOURCE=... -DDEST=... "-DREQUIRED=a;b" "-DOPTIONAL=c" -P stage_content.cmakecmake_minimum_required(VERSION 3.26) # a script sets no policies; IN_LIST needs CMP0057foreach(file IN LISTS REQUIRED OPTIONAL) if(EXISTS "${SOURCE}/${file}") get_filename_component(parent "${DEST}/${file}" DIRECTORY) file(MAKE_DIRECTORY "${parent}") file(COPY_FILE "${SOURCE}/${file}" "${DEST}/${file}" ONLY_IF_DIFFERENT) elseif(file IN_LIST REQUIRED) message(FATAL_ERROR "required content '${file}' is missing from ${SOURCE}") else() file(REMOVE "${DEST}/${file}") endif()endforeach()A missing required file then fails the build, naming it, and a missing optional one is removed
from the build folder so the game sees it absent. Removal is limited to the files the lists
name: anything else left in the build folder stays. file(COPY_FILE ... ONLY_IF_DIFFERENT)
needs CMake 3.21, and the engine already requires 3.26.
The browser build has no copy to go stale. Its --embed-file is the web equivalent of the copy:
it packs the content directory into the module each time the module links, from the directory as
it stands, so a deleted file is gone from the next link.
A content file is not a source, so changing one does not by itself make the module link again.
The template’s browser target lists the files that should, in its LINK_DEPENDS property: the
manifest and the font. Each content file a game adds needs a line there, such as
"${CMAKE_CURRENT_SOURCE_DIR}/content/textures/hero.dds" or, for a sound bank, both
"${CMAKE_CURRENT_SOURCE_DIR}/content/sounds/tones.json" and its .xwb. Without one, the page
keeps the old file after the new one is made, until something else makes it link.
Put a picture in your game and
Play a sound in your game add the lines for their files.
Reading JSON
Section titled “Reading JSON”Content is the one input a person types by hand, so the engine reads JSON through a checked
wrapper, engine/assets/json.h. Its accessors check the node’s type and any
requested key or element before reading it. Failures name the source and
position, plus the key when one was requested:
JsonDocument read_json_file(const char* path); // throws naming the path if it cannot be read or parsedJsonDocument parse_json(std::string_view text, std::string source_name); // the same parse, from memory; errors name source_name
// On a JsonValue:JsonValue array(const char* key) const;std::string string(const char* key) const;int integer(const char* key) const;float number(const char* key) const;bool boolean(const char* key) const;bool has(const char* key) const; // presence, including a false valuestd::vector<std::string> keys() const; // copied object names in stored ordersize_t size() const; // for an arrayJsonValue at(size_t index) const; // for an arraystd::string where() const; // e.g. 'levels/forest.json': spawns[2]A JsonValue is a view into its JsonDocument, valid only while the document is alive, so read
what you need into your own types before the document goes out of scope. Use where() in your
own errors when a value is the right type but not an acceptable one, such as an unknown enemy
name.
keys() requires an object and copies its member names, including duplicate,
empty, Unicode and NUL-containing names. The copies outlive the document; the
JsonValue still borrows it. Your own readers can compare those names with
their own schema and use where() to report an unknown field. The general JSON
reader permits arbitrary dictionaries and metadata. Strict field lists belong
to the engine’s manifest, sprite-sheet and sound-bank loaders, not to every JSON
document.
A kind of asset of your own
Section titled “A kind of asset of your own”The engine knows texture, font, sprite_sheet, sound_bank and wave. A game teaches it
more (levels, dialogue, enemy definitions) by registering a loader for each kind before it
loads the manifest:
struct AssetKind{ LoadAsset load; // void(const std::string& directory, const std::string& name, bool optional) LoadAsset reload_device; // the same, after a graphics device is restored; nullptr if not on the GPU};load is called once for each name in each group of that kind, with the group’s directory
already resolved relative to the manifest. Content that does not live on the graphics card leaves
reload_device empty. This is a level kind that reads one JSON file per level into a
Registry the game owns:
#include "engine/assets/json.h"#include "engine/assets/resource_loader.h"#include "engine/core/registry.h"
#include <memory>#include <string>
struct Level{ std::string title; int width = 0; int height = 0;};
{ loader.register_kind("level", { [&levels](const std::string& directory, const std::string& name, bool /*optional*/) {
std::unique_ptr<Level> level = std::make_unique<Level>(); level->title = root.string("title"); level->width = root.integer("width"); level->height = root.integer("height"); levels.add(name, std::move(level)); }, nullptr });}The game creates the registry before the Application, so that it outlives the loader, and
calls register_levels(*app.resource_loader(), levels) before app.load_manifest. The manifest
then lists levels like any other content:
{ "kind": "level", "directory": "./levels/", "names": [ "forest", "caves" ] }and a state that is handed the registry resolves a level once and reads it by handle:
const Level& level = *levels->get(forest);A misspelt kind in the manifest stops the game naming the kind; a misspelt level name throws naming the level, on the line that resolves it.
Development documentation (unreleased). Built from Labrador aceb130 of 2026-11-20.