sprat-lib

A small C99 library for loading sprite sheet metadata produced by sprat-cli into your game or engine.

It reads the file written by spratconvert --transform raw (sprat-cli v0.20.0 or later): atlases, sprites (trims, rotation, pivots, nine-slices, aliases), markers, animations and cutout puppets. It has no dependencies beyond the C standard library, and it validates everything at load time, so a loaded sheet needs no further checks. The header is C99 and includes cleanly from C++.

Quick start

spratlayout ./frames --trim-transparent > layout.txt
spratpack < layout.txt > atlas.png
spratconvert --transform raw -a atlas.png < layout.txt > atlas.sprat

#include <sprat/sprat.h>

sprat_sheet* sheet = NULL;
sprat_error error;
if (sprat_sheet_load_file("atlas.sprat", &sheet, &error) != SPRAT_OK) {
    fprintf(stderr, "%s\n", error.message);
    return 1;
}

const sprat_animation* run = sprat_sheet_find_animation(sheet, "run");
/* check run != NULL and run->frame_count > 0 in real code */
const sprat_sprite* frame = &sheet->sprites[run->frames[0]];
const sprat_atlas* atlas = &sheet->atlases[frame->atlas_index];
/* frame->rect is the region inside atlas->path to draw. */

sprat_sheet_free(sheet);

See Getting started for the full first integration, including drawing.

Documentation

I want to...	Read
Get a sheet loading and drawing	Getting started
Look up a function	API reference
Understand the data structures	The model
Draw sprites correctly	Drawing a sprite
Rig and animate a cutout character	Puppets
Resolve names to indexes	Binding names
Handle errors and untrusted files	Errors and validation
Use my own allocator or threads	Memory and threads
Read the file format	File format
Know what is not supported	Limitations

Building

cmake -S . -B build -DBUILD_TESTING=ON
cmake --build build --parallel
ctest --test-dir build --output-on-failure

Options:

Option	Default	Effect
BUILD_SHARED_LIBS	OFF	Build a shared library instead of a static one
SPRAT_BUILD_EXAMPLES	ON when top level	Build sprat-dump
SPRAT_SANITIZE	OFF	Build with AddressSanitizer and UBSan (GCC/Clang)

To use it from another CMake project, either call add_subdirectory(sprat-lib) or install it and call find_package(sprat). Both give you the sprat::sprat target. An install also writes sprat.pc, for pkg-config --cflags --libs sprat.

You can also skip CMake and compile src/*.c with include/ on the include path. When you link the shared library that way, define SPRAT_SHARED.

sprat-dump sheet.sprat prints what the library loaded.

License

MIT. See LICENSE.