JSON
Generated from engine/assets/json.h at f525bc6. The text under each declaration is the header's own comment, word for word. About the reference says how these pages are made.
Audience: game code.
#include "engine/assets/json.h" · namespace labrador
read_json_file
Section titled “read_json_file”Reads the UTF-8 file path in full and parses it as JSON. Raw NUL bytes are rejected at their byte offset; JSON \u0000 string escapes are valid.
Throws std::invalid_argument for a null path, and std::runtime_error naming the path if the file cannot be opened, cannot be read, or does not parse. The returned document is therefore always valid - callers never have to test for a parse error. Nesting depth is bounded by memory, not by the stack: a deeply nested file parses or throws like any other.
parse_json
Section titled “parse_json”Parses the bytes in text as JSON; the view need not end at a NUL. Raw NUL bytes within the view are rejected at their byte offset; JSON \u0000 string escapes are valid. source_name names the source in every diagnostic in place of a path - a content filename, say. The document copies what it needs; neither argument is borrowed. The parse is the one read_json_file makes, so the same bytes give the same document either way.
Throws std::invalid_argument for an empty source_name, and std::runtime_error naming source_name if the text does not parse.
class JsonValue
Section titled “class JsonValue”A borrowed view of one node inside a JsonDocument.
Every accessor checks two things and throws naming the source, the position in it and the key when either fails: that this node is the kind the accessor needs, and that what it asks for is present and of the right type. rapidjson's own accessors assert instead, and NDEBUG disarms the assert - so a hand-edited content file that a debug build catches with a dialog box is a null dereference in a Release build. Content files are the one input a person types by hand, so every read of one is checked (T6).
This is a pointer, not a copy: it is valid only while the document it came from is alive.
object · array · string
Section titled “object · array · string”JsonValue array(const char* key) const;std::string string(const char* key) const;Required members of an object.
identifier · integer
Section titled “identifier · integer”std::string identifier(const char* key) const;int integer(const char* key) const;Identifier/path strings cannot contain NULs; errors name the field.
number · boolean
Section titled “number · boolean”float number(const char* key) const;bool boolean(const char* key) const;Any JSON number, whole or not. One beyond float's range - 1e40 - throws naming the source and key rather than becoming infinity.
bool has(const char* key) const;True if key is present, whatever its type, so callers can check a field a file is allowed to leave out. Throws unless this is an object.
std::vector<std::string> keys() const;Copies this object's member names in stored order, including duplicate names and the full decoded bytes of empty or NUL-containing names. Throws unless this is an object. The copies survive the document's destruction; this JsonValue remains a borrowed view.
size · at
Section titled “size · at”size_t size() const;Arrays. Both throw unless this node is one.
as_string · as_identifier
Section titled “as_string · as_identifier”std::string as_string() const;std::string as_identifier() const;This node read as a scalar, for array elements, which have no key.
std::string where() const;Where this node is, as './manifest.json': assets[1], for a caller with its own reason to reject what it read. An unknown colour name or object type is a content mistake exactly like a missing key, and it deserves the same sentence pointing at it (T6).
class JsonDocument
Section titled “class JsonDocument”A parsed JSON document, and the owner of every JsonValue taken out of it.
Move-only: a document is a parse of its text, and copying one would copy the arena it parsed into.
~JsonDocument · JsonDocument · operator=
Section titled “~JsonDocument · JsonDocument · operator=”JsonDocument(JsonDocument&&) noexcept;JsonDocument& operator=(JsonDocument&&) noexcept;The top of the document. Its own type is not checked here - the first accessor used on it is what says which type it needed and did not get.
source_path
Section titled “source_path”const std::string& source_path() const;The path given to read_json_file, or the name given to parse_json.
In the samples and tests
Section titled “In the samples and tests”The files that include this header directly. A file can also reach it through another header.
tests/assets/json_tests.cpp,string_table_text_tests.cpp
Explained in
Section titled “Explained in”Documentation for Labrador v0.4.0. Built from Labrador f525bc6 of 2026-11-17.