Managing the Bestiary
The Bestiary tab of the Content Studio is the primary tool for creating and editing species (Faerals).
Start the studio with:
node tools/content-studio/server.mjs
# Open http://localhost:4173
Species files
Each species is stored as a hand-readable TOML file under assets/data/species/:
assets/data/species/
001_faeral.toml
002_ignicore.toml
…
The filename is always {id:03}_{slug}.toml. Saving through the UI always writes to the correct path automatically.
Creating a species
- Click New in the action bar (or press nothing — the form is blank on launch).
- Fill in id (positive integer, unique) and name.
- Fill all other fields (see field reference below).
- Click Save (or press Ctrl+S).
The file is created immediately; the sidebar refreshes automatically.
Editing a species
Click its name in the left sidebar. The form loads with all current values. Edit any field and press Save.
Duplicate copies the current species into a blank form with the ID cleared so you can assign a new one before saving.
Field reference
| Field | Type | Notes |
|---|---|---|
id | integer | Must be unique and positive |
name | text | Free string; used to derive the filename slug |
attributes | checkbox list | One or more elemental types |
preferred_biomes | checkbox list | Biomes the species naturally inhabits |
temperature_range | range (min/max) | °C range where the species thrives |
humidity_range | range (min/max) | 0–1 scale |
predators | checkbox list | IDs of species that hunt this one (synced bidirectionally) |
preys | checkbox list | IDs of species this one hunts (synced bidirectionally) |
nomadism | number | 0–1 float: migration willingness (0 = fully sedentary, 1 = highly nomadic) |
base_spawn_modifier | number | Multiplier applied to base spawn rate |
mutation_rate | number | 0–1; probability of a stat mutation on birth |
base_stats | four numbers | max_hp / attack / defense / speed |
evolution_chain | chain editor | See section below |
spawn_tiles | checkbox list | Tile types on which this species can spawn |
generic_abilities | checkbox list | IDs of learnable abilities |
special_ability | radio list | Single unique ability (or none) |
base_capture_rate | number | 0–255 scale |
rarity | number | Population weight (higher = more common) |
experience_yield | number | XP awarded on defeating this species |
Predator / prey sync
Predator and prey relations are bidirectional. When you add species #3 to species #1's predators list and save, the studio automatically adds #1 to species #3's preys list (and removes it if you remove the relation). You never need to edit both sides manually.
Evolution chain editor
The evolution chain represents life stages of the same species — different graphics, stats, and animations for each stage (Juvenile → Adult → Elder, etc.). This is not cross-species evolution.
Adding stages
Click + Add Stage at the top or bottom of the chain. A new stage card appears with an editable name.
Reordering / removing
Drag is not yet supported — remove a stage with the × button on its card and re-add it at the desired position.
Evolution conditions (arrows between stages)
Click ↕ (no condition) between two stage cards to open the condition panel. You can set any combination of:
| Condition | Type | Example |
|---|---|---|
| Level | integer | 20 |
| Temp °C | min / max range | 15 – 35 |
| Weather | select | Rain |
| Zone | select | Ocean |
| Object | free text | MoonShard |
Click ✂ Clear all to remove all conditions (the evolution becomes unconditional).
Animation slots
Each stage has 13 animation frame slots. Expand a stage's animation panel with the 🎞 N/13 button.
For each frame slot you can:
- Upload a PNG/GIF directly (saves to
assets/sprites/species/{id:03}/{frame}.png). - Open the Sprite-sheet Helper (🎞 icon) to upload a spritesheet, set columns × rows and FPS, preview the animation loop, then save & assign.
- Clear the current assignment with ×.
Animation frames:
| Frame | Description |
|---|---|
idle_walk_front / back / left / right | 4-directional walking cycle |
attack_front / back | Attack animation |
hurt_front / back | Hit/damage reaction |
altered_front / back | Status-effect altered state |
idle_fight_front / back | High-res combat idle |
capture_front | Capture sequence (front only) |
Sidebar stages
When a species has an evolution chain, its stages appear as sub-rows below the species entry in the sidebar. Clicking a stage row selects the species and scrolls the chain editor to that stage (highlighted in blue).
Keyboard shortcuts
| Shortcut | Action |
|---|---|
| Ctrl+S | Save the current species |
TOML storage format
TOML files are plain text and can be edited by hand. Key storage details:
- evolution_chain — stored as a raw JSON string:
evolution_chain = [{"name":"Juvenile",...}] - spawn_tiles, attributes, preferred_biomes — bracket arrays:
spawn_tiles = ["Grass", "Water"] - predators, preys, generic_abilities — integer arrays:
predators = [2, 5] - special_ability — integer or
none
When saving through the UI the correct format is always written automatically.
Exporting / using species data in-engine
The Rust engine reads assets/data/species/*.toml at startup via faerals-data crate helpers. The TOML schema is defined in crates/faerals-data/src/species.rs. Any field added in the studio must also be added to the Rust struct (and the TOML parse impl) to be used in-game.