Custom Companion

Author your own companion species with the same folder layout as the built-ins.

Current status

Built-in companions (Ember, Soul, Moss, Flint, Bubble, Rime, Jab, Volt, Drake, Nyx) already demonstrate the full folder layout, companion.json, pixel clips, and runtime interactions. Browse them on the Companions page or open a Know more sheet for Bond and type notes. Project-level registration for custom companions (CLI install + host discovery) is not shipped yet — this page documents the layout the runtime expects when that lands.

Folder workflow

  1. Create a companion folder (for example companion/my-buddy/).
  2. Add a companion.json with identity, personality, capabilities, and interactions.
  3. Add a static idle sprite under assets/.
  4. Add animation frames under animations/ — at minimum idle, happy, sleep, fall, and puff. See Animations for clip tables.
  5. Wire the species into the companion catalog (today: docs catalog; later: project registration via CLI).
bash
companion/my-buddy/
├── companion.json
├── assets/
│   └── idle.png
└── animations/
    ├── idle/
    ├── happy/
    ├── sleep/
    ├── fall/
    └── puff/

Species vs instances

A companion folder describes a species. The live host spawns instances of that species onto the page (max one of each type today). Future versions may support multiple instances of the same species with independent Bond, mood, and personality — same design, different characters.