Reading a sprite sheet
Generated from engine/assets/sprite_sheet_loader.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/sprite_sheet_loader.h" · namespace labrador
read_sprite_sheet
Section titled “read_sprite_sheet”Reads the sheet definition at json_path and builds a SpriteSheet drawing from texture, whose positive dimensions in texels are texture_size. The frame and animation-strip tables are decoded here rather than by SpriteSheet itself, so that nothing on the draw path compiles a JSON parser to draw a sprite.
Throws std::runtime_error naming the path if the file cannot be read or parsed, and naming the path and the offending frame or strip if the document is the wrong shape, has an unknown key or repeats one (T6). This includes nested position, size, origin and first-frame objects; unsupported fields must be removed or corrected instead of being silently ignored. A negative animation-strip frame_count, one above max_texture_dimension (texture_data.h), or a positive one whose first frame has zero width or height throws std::runtime_error naming the path, strip and field. Zero frames define an empty strip. An unrepresentable cached strip x coordinate throws std::runtime_error naming the path, strip and frame coordinate. Signed rectangle endpoints must fit within [0, texture_size.x] and [0, texture_size.y], including every expanded strip frame. Out-of-atlas rectangles throw std::runtime_error naming the path and frame or strip. Individual zero-area frames remain valid when their endpoints fit; zero-count strips sample nothing and do not check unused geometry. Nonpositive texture dimensions throw std::invalid_argument.
AND FOR ONE THING THE DOCUMENT CAN SAY THAT IS WELL FORMED AND STILL NOT DRAWABLE: a frame with "rotated": true is refused here, by name, rather than loaded and then drawn upright. A sheet is authored content, so a key the engine reads and disagrees with is a worse failure than one it rejects - the .cpp carries the argument, and engine/render/sprite_frame.h is why there is no member to hold the answer.
origin goes the other way: it is honoured, because it costs one addition on a path that already carries an origin (engine/render/sprite_sheet.h).
Related types
Section titled “Related types”Named in the public declarations above: SpriteSheet, Vector2I.
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.
samples/components/animation_preview_content_tests.cpptests/assets/grid_sheet_loader_tests.cpp,sprite_sheet_loader_tests.cpp
Explained in
Section titled “Explained in”Documentation for Labrador v0.4.0. Built from Labrador f525bc6 of 2026-11-17.