Skip to content

citsy

A headless C++ reimplementation of the Bitsy game engine — the little engine for little games, worlds, and stories.

citsy is engine only. It parses .bitsy data, simulates the world, and writes logical framebuffers and audio parameters. A separate Host backend turns those buffers into pixels and sound.

Get started Host API GitHub

  • Headless core

    Zero window, GPU, or audio libraries. The citsy target is portable C++20.

  • Pluggable Host

    Implement citsy::Host and embed the engine in a jam game, handheld, or test harness.

  • Bitsy files

    Load games exported from the Bitsy editor. Rooms, dialog, items, and scripts stay compatible.

  • Testable

    MockHost records every frame. Core tests run in CI with no display.

How it fits together

flowchart TB
  App["Your application"] --> Host["Host backend<br/>raylib · 32blit · MockHost"]
  Host -->|"time, input"| Core["citsy core"]
  Core -->|"present(buffers, palette, sound)"| Host
  Core --> Data[".bitsy game data"]

Each frame:

  1. The host reports elapsed time and button state.
  2. The engine steps simulation — movement, dialog, transitions, sound.
  3. The engine writes memory blocks (128×128 video, 16×16 maps, textbox, two square-wave channels).
  4. The host blits those blocks and plays audio. The engine never calls platform APIs.

Quick start

git clone https://github.com/TeriyakiGod/citsy.git
cd citsy
cmake -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build
ctest --test-dir build

Then embed the engine by implementing citsy::Host. See Getting started for a full sketch.

Guides

Guide Contents
Getting started Clone, build, and embed the engine
Architecture Layers, modules, memory blocks, data flow
Host API Buttons, buffers, present(), MockHost
Building CMake options, compilers, backends
Testing Catch2, fixtures, writing tests
Bitsy data model PAL, TIL, SPR, ROOM, …
Dialog scripting Variables, lists, {end} / {exit}
Roadmap Phases and compatibility

Not affiliated

This is a clean-room engine inspired by Bitsy. It is not affiliated with Adam Le Doux or the official Bitsy project. Game data produced by the Bitsy editor (.bitsy files) is the intended interchange format.