Ambient microfauna · Torreta viki

Small colonies live in the pit and on the plain above it. Each one has a stone shelter, and its creatures come out from under it and go about the ground nearby. Ants walk a trail to a seed pile and back, each carrying a seed. Beetles wander, crickets wander and hop, and butterflies flit from spot to spot. At night the butterflies go back under their stone. They all run for cover when insects pass close by or a storm comes. As the maze grows, some colonies stay under their stones, and they come back out when towers are sold.

The microfauna is scenery only. It has no collision, never touches the combat RNG and is never saved, so a mod that only changes the microfauna keeps the vanilla profile (achievements, XP and leaderboards stay on).

A mod changes the microfauna with two optional files beside mod.json:

my_microfauna/
  mod.json
  microfauna.json       species, groups, limits and timing
  models.json           Microfauna/<Name> GLBs (new species or replacements)
  Models/Scorpion.glb

The shipped values are in vanilla_reference/microfauna.json (a copy of the game's Data/microfauna.json). The stock models are built by tools/art/build_blender_microfauna.py; their editable source is Assets/Models/Source/Microfauna.blend. The sample mod example_microfauna adds a desert scorpion.

How many colonies live in the pit, relative to the plain, is set apart, in weather.json: scenery_fx.pit_microfauna (see WEATHER.md).

microfauna.json

{
  "version": 1,
  "settings": { "colonies": [16, 24, 32, 40] },
  "species": {
    "butterfly": { "fly_on": 0.4 },
    "scorpion": {
      "model": "Microfauna/Scorpion", "behavior": "wander",
      "speed": [1.3, 2.1], "size": [0.85, 1.1], "length": 5.0
    }
  },
  "groups": {
    "scorpion_den": { "pit": 1.2, "plain": 1.0, "members": { "scorpion": [1, 2] } },
    "butterflies": { "pit": 0 }
  }
}

The file is merged over the vanilla one key by key: settings field by field, and species and groups by id. A new species id needs a model and inherits the beetle's other fields. A new group needs members. Unknown or invalid fields are named in the mod errors and left out.

A species only appears through a group. To add one, give it a group of its own or add it to an existing group's members. To take one out, set the weights of the groups that hold it to 0. In the example, "butterflies": {"pit": 0} keeps lone butterflies out of the pit.

settings

Field	Meaning
`enabled`	`false` turns the microfauna off.
`colonies`	Colonies per preset (Low, Medium, High, Ultra), up to 64. Half live on the plain; the pit holds `pit_microfauna` of that many.
`tower_ease`	`[from, to]` towers: from the first count on, colonies start going home, until only `full_maze_share` of them stay out at the second.
`full_maze_share`	The share of colonies that stays out in a full maze, 0-1.
`hidden_by_rain`, `hidden_by_sand`	Above this much rain or sand, everything stays under its stone.
`night_below`	Below this much of the hour's light it is night, for `hides_at_night` and `hides_by_day`.
`shadows`	Whether the creatures cast shadows, per preset.
`shelter_model`, `seed_model`	The `Microfauna/<Name>` models of the shelter stone and of the ants' seed pile.

species

Field	Meaning
`model`	A `Microfauna/<Name>` model key.
`behavior`	How it moves: `trail` (an ant: to the colony's seed pile and back with a seed, in its own lane, with short pauses), `wander` (a beetle: from spot to spot), `hop` (a cricket: wanders, and hops now and then), `flutter` (a butterfly: flies from spot to spot and lands).
`speed`	`[min, max]` in world units per second.
`size`	`[min, max]` scale of the model.
`length`	Body length at size 1, in world units; the creatures keep about this much ground between them.
`hop_height`, `hop_every_seconds`	For `hop`: how high, and `[min, max]` seconds between hops.
`flight_height`	For `flutter`: how high it flies.
`fly_on`	For `flutter`: the chance, 0-1, that after landing it flies on to another spot instead of going home.
`hides_at_night`, `hides_by_day`	`true` keeps it under its stone at night, or by day. The day journey (difficulty 1) has no night.

groups

Field	Meaning
`pit`, `plain`	How likely a new colony in the pit, or on the plain, is to be this group, 0-100. The weights are relative to the other groups'.
`members`	`{species: [fewest, most]}`: how many of each species the colony holds, in order. A colony holds at most 12 creatures.

A colony that holds a trail species also gets a seed pile.

Models

A microfauna model is a small mesh in its in-game size, in Godot's frame: facing +X, +Y up, feet on y = 0. The stock ant is about 3 units long, the scorpion about 5, and a tower tile is 64. In Blender (Z up, exported with glTF's +Y up) that is X forward and Z up.

With "material": "game" in models.json, the model wears the game's cuticle shader: its colour comes from the vertex colours (COLOR_0, linear), and the vertex alpha is the cuticle's finish (low: glossy wax, high: dry and rough), not transparency. It also gets wet in the rain. Its parts then move by a second UV set (UV2), as in the stock models:

`UV2.x`	Part	Motion
0	Body	Rigid.
±1, ±2, ±3	Legs, the sign by side	Step; 1 and 3 swing together and 2 opposite, so 1-2-3 per side walks like an insect.
±4	Feelers, claws, a tail	Sway sideways.
±5	Wings	Flap (folded at rest, beating in flight).
6	The seed an ant carries	Shown only while it carries one.

UV2.y is the part's weight: 0 where it joins the body, 1 at its tip. In Blender, which flips V on export, store 1 - weight. Without a second UV set the model rides rigidly.

With "material": "imported" (the default), the model keeps its own PBR materials and rides rigidly.

Replacing a stock key (Microfauna/Ant, Beetle, Cricket, Butterfly, Shelter, Seed) changes that creature's model only. Its behaviour stays in microfauna.json.