Ambient birds

Birds cross the arena from random points outside the frame, alone or in flocks, over the pit and out the far side. Which species fly depends on the time of day, and nobody flies in rain or a sandstorm: when a storm starts the birds already in the air turn away and leave, and new arrivals wait until the sky has been clear for a few seconds.

They are scenery only. They have no collision, never touch the combat RNG and are never saved, so a mod that only changes birds keeps the vanilla profile (achievements, XP and leaderboards stay on).

A mod changes birds with two optional files beside mod.json:

my_birds/
  mod.json
  birds.json            species, flocks, timing and limits
  models.json           Birds/<Name> GLBs (new species or replacements)
  Models/Flamingo.glb

The shipped values are in vanilla_reference/birds.json (a copy of the game's Data/birds.json). example_birds adds flamingos at dusk and retunes two vanilla species; its Blender source is included.

birds.json

{
  "version": 1,
  "settings": {"density": 1.3},
  "species": {
    "flamingo": {"model": "Birds/Flamingo", "active": {"twilight": 3, "night": 1},
                 "group": [6, 16], "flock_chance": 1.0, "formation": "v"},
    "sandgrouse": {"group": [10, 24]},
    "raven": {"active": {"day": 0}}
  }
}

Mods are merged in load order over the vanilla file: settings key by key and species by id. An id that already exists keeps every field you leave out, so {"raven": {"active": {"day": 0}}} only silences ravens by day. A new id needs a model; the fields it omits come from the vanilla raven, except call_family, which defaults to none for new species. A field that fails validation is named in the log and the Mods screen, and the value before it is kept.

settings

The hour is the luminance of the world's time-of-day tint: 1.0 at noon, about 0.60 at dusk and 0.19 at night. It moves with the waves (day turns to dusk on difficulty 1, dusk to night on 2, night to dawn on 3) and follows a mod's time_of_day settings, so bands are the robust way to target an hour.

species

Flight sounds

Wing strokes follow the descending wing pose. Gliding is silent; calls are spaced events attached to the visible birds. Position, height and distance from the shared overview/cockpit camera determine stereo direction, volume and the loss of distant high frequencies. Zooming near their altitude makes nearby wings easier to hear. They use the Sound Effects volume setting. Pause suspends playback; departing birds release their sources, and a run reset clears them. The showcase is silent. At most eight wing events and three calls can play together, even with large modded flocks.

The stock call families use field recordings: corvid calls for ravens, short mixed-bird calls for swifts and sandgrouse, and owl hoots. Other species have wing sounds only. A new species must explicitly choose a family if desired; it never inherits the raven call. These are artistic families, not a complete species-specific sound library.

The normal sounds.json overrides can replace bird_wing_0 through bird_wing_2, bird_corvid_0/1, bird_small_0/1 and bird_owl_0/1. Use short, mono events with no leading silence for accurate spatialization. The CC0 sources and preparation steps are documented in Assets/Sounds/Birds/CREDITS.md and tools/audio/prepare_bird_audio.py.

Bird models

A bird is one GLB at its in-game size, in Torreta's Blender frame (X forward, Y left, Z up), with the origin between the shoulders and the wings spread flat. The game flaps the wings on the GPU, so a model has no bones or animations. It carries its rig as data:

• UV map 2 (BirdRig): U is the signed span, 0 at the shoulder and ±1 at the wingtip, positive on the bird's right; V is the part: 0 body, 1 wing, 2 tail (U runs 0 at the vent to 1 at the tip, and the tail spreads in turns), 3 head, 4 legs. Blender's glTF export flips V, so write 1 - part in Blender.
• Empties ShoulderL, ShoulderR, WristL, WristR, children of the model's root: the two hinge lines of each wing. The hand (beyond the wrist) folds and sweeps back on the upstroke.

Both are optional. Without the UV map the game derives the wing from the span (everything beyond the shoulder flaps, the rear of the body is tail); without the empties it places the shoulder at 12% and the wrist at 52% of the half-span. An untagged GLB still flies, only more stiffly.

tools/art/build_blender_birds.py builds the eight stock birds with this rig and tools/mods/build_bird_example.py builds the flamingo from the same code.

In models.json use "material": "game" for vertex-coloured plumage, lit like the stock birds, or "imported" to keep your own PBR colour, texture and roughness (a texture replaces the procedural feather lines). Keep a bird under about 6,000 triangles: up to 64 can be in the air at once.

A mod may also replace a stock bird by shipping its key, for example "Birds/Raven": {"file": "Models/MyCrow.glb", "material": "game"}.

Checking a bird

Enable the mod in Options → Mods and restart. With the in-game admin weather panel (F8) you can set the hour's weather to rain to watch the birds leave. In the repository, ART_REVIEW_BIRDS=1 runs the native review: species by hour, weather, limits, the reset and a close-up photograph of every species.

ART_REVIEW_REGRESSION=bird_audio ART_REVIEW_AUDIO_DRIVER=CoreAudio checks real mixed distance/height attenuation, stereo passage, gameplay zoom, pause, mod controls and bounded playback. Use a real native audio driver: Dummy does not mix any samples. On Windows, use WASAPI instead.