Equipment

What it models

Every fitting a tank can carry, and the two ways one acts. A passive contributor is recomputed from scratch at the top of each tick into one of four shared resources — surface, flow, light, aeration — so unplugging a filter takes its contribution away the same hour. An active emitter pushes a delta instead: heat, water, CO₂, fertiliser, food, or the bed’s own organics and nutrients.

Status

Mechanic	Status	Why
Flow as turnover	settled	Flow is capacity × target turnover, capped at a class ceiling. The same filter is worth less in a bigger tank, which is the physical claim.
Surface as colony ceiling	settled	Every colonisable cm² in one number, and the biofilm is a stock spread over it. Surface leaving the tank takes its share of the colony.
Passive resources hold no state	settled	Rebuilt each tick from the fittings that are there. Nothing accumulates, so nothing can go stale.
The bed as an ammonia source	settled	A per-litre reserve of mulm at the bed’s own composition, rotting where it lies on the law every organic pool follows, refilled by food and waste settling in.
The bed as a nutrient store	settled	N, P, K and Fe the bed holds for root feeders: aqua soil comes charged, root tabs refill any bed, and a share leaks into the water each tick.
Tab placement	scaffolding	The store is mixed through the whole bed: a tab feeds every root in the tank, not the plant it was pushed beside, so a big tank dilutes it.
CO₂ as a metered mass	settled	Bubble rate buys milligrams, not ppm, so an evaporated tank reads higher off the same setting.
Heater thermostat	scaffolding	A switch: full wattage below setpoint, nothing at or above it. No hysteresis, no proportional band, and no failure state.
Air pump sizing	scaffolding	Four capacity bands, not a rate. A 151 L tank gets twice the air of a 150 L one on the far side of the same step.
Aeration as a boolean	scaffolding	On or off. A sponge filter in a nano and a full air stone in a 400 L deliver the identical multiplier and the identical direct O₂.
Lid	scaffolding	Four hardcoded multipliers outside config/, and they reach evaporation only.
ATO trigger	scaffolding	A switch at 99 % of capacity that refills to exactly 100 % in a single tick, however far it fell.
The doser	settled	A set volume of one fertiliser formula, once a day. The plants fill their stores at their own composition rather than the bottle’s ratio (Plants), so the water drifts toward whatever the planting leaves behind.
The feeder	settled	A set ration of food, once a day at its hour. What the fish don’t eat rots and settles like any other feeding.
Hardscape and bed chemistry	scaffolding	Calcite adds KH and GH, driftwood spends KH, aqua soil spends both. Wood and soil draw on finite hand-set reserves that taper as they are spent; calcite never runs out.
Filter class limits	scaffolding	maxCapacityLiters is display only — the tick never reads it. A sponge on a 500 L tank is undersized in the readout and unpunished in the model.
Wear, clogging, failure	missing	No fitting ages, fouls or breaks. Media is never consumed and never cleaned; the only maintenance the engine models at all is swapping the bed.
Cooling	missing	There is no chiller. Heat has one direction.
Lid as a gas boundary	missing	Sealing a tank stops its evaporation and changes nothing about its gas exchange.

How it works

The four passive resources

Resource	Contributed by	Unit
surface	Tank glass, filter media, substrate, hardscape	cm²
flow	Filter, powerhead, air-pump bubble uplift	L/h
light	The light fixture, if enabled and inside its schedule, attenuated to the substrate	µmol/m²/s
aeration	Air pump, or an air-driven filter	boolean

All four are overwritten every tick before anything reads them, so they describe the tank as it is right now rather than as it was assembled. Light is also written into the day’s history each plant’s light is read against — see Light.

Filters

Flow is capacity × targetTurnover, capped at the class ceiling.

Type	Target turnover	Flow ceiling	Media surface	Air-driven
sponge	4 ×/h	300 L/h	8,000 cm²	yes
hob	6 ×/h	1,250 L/h	15,000 cm²	no
canister	8 ×/h	4,500 L/h	25,000 cm²	no
sump	10 ×/h	none	40,000 cm²	no

The ceiling bites at 75 L for a sponge, 208 L for a HOB and 562 L for a canister — which is under the 568 L the canister class is rated to, so a canister on the largest tank it is sold for is already delivering below its own target turnover. The two limits are independent numbers and were never reconciled.

Only the sponge aerates, because only the sponge moves water with air. That one boolean is worth more to a tank’s oxygen than the flow it comes with.

Surface

Source	Contribution
Tank glass	Four walls plus the bottom of the box capacity implies
Filter media	8,000–40,000 cm² by class, only while the filter is enabled
Substrate	0/400/800/1,200 cm² per litre for none / sand / gravel / aqua soil
Hardscape	400 cm² a rock, 650 driftwood, 100 a plastic decoration

In any tank with a bed, the bed dominates. That is why pulling the substrate is the most expensive thing that can be done to a biofilter: the colony is a stock spread over total surface, so a swap removes the share that was living there and lays sterile material in its place. The film of algae on the floor goes out with the old bed, and the new one arrives bare.

Slots cap hardscape at two per gallon of capacity, to a hard maximum of eight. A piece lifted out takes its biofilm and its film of algae with it and stirs one slot’s share of the bed, and pieces lifted together stir their shares of the bed as it stood; a piece set down arrives sterile and bare, so the film’s coverage thins over the new surface. Resetting the scape lifts every piece at once and sets each back fresh, so a tank carrying more pieces than slots keeps them all — see Nitrogen cycle and Algae.

Hardscape and bed also move the water’s hardness: calcite rock dissolves and adds KH and GH alike, driftwood’s tannic acid spends KH, and aqua soil takes a share of the KH every hour and as much GH with it; sand and gravel are inert. Wood and soil spend down finite reserves, so both fade over months — a fresh soil tank starts acidic and drifts toward the tap. The rates live on Water & gases.

Heater

Below setpoint the heater delivers wattage / water °C per hour, scaled by the same volume term temperature drift uses — which is what makes an underpowered heater plateau below its target instead of asymptoting to it. At or above setpoint it emits nothing. It reads the shipped temperature constants directly, so a tuned volume exponent moves drift but not heating.

Lid and ATO

The lid multiplies evaporation and does nothing else. The ATO watches the fill fraction, and the moment it drops below 99 % it adds enough water to reach capacity in one tick — blending temperature, O₂ and CO₂ toward the tap and adding the tap’s KH and GH in the process. Nitrogen compounds are stored as mass, so they need no blending; their ppm falls out of the new volume.

Air pump

Capacity	Air output	Flow from bubble uplift
≤ 40 L	60 L/h	6 L/h
41–⁠150 L	120 L/h	12 L/h
151–⁠400 L	240 L/h	24 L/h
> 400 L	400 L/h	40 L/h

Nothing downstream reads the air output. It sets the flow contribution and then stops mattering, because aeration itself is a boolean.

CO₂, the doser and the feeder

The CO₂ generator meters CO2_MASS_RATE per bubble-per-second into the standing water, on its own schedule — a ~0.1 mL bubble of CO₂ at 1.8 mg/mL. One bubble a second holds a 20–40 gal tank with a canister’s surface agitation near 20–30 mg/L. The doser fires once at its hour and adds one dose of the four-nutrient formula, then latches until midnight. The feeder drops its ration into food at its hour, every day it is on. All three land in the settle pass, so plants meet the day’s carbon and fertiliser, and fish the day’s food, in the same tick it was metered.

The bed

Substrate carries independent per-litre properties: colony surface; an organic reserve, mulm rotting in place, a fresh bag’s at a lean food’s 5 % nitrogen and Redfield’s N:P; a nutrient store; and, in aqua soil only, a KH reserve the bed spends as it strips alkalinity, and the same mg of GH, out of the water. The KH reserve never refills. What the organics do downstream belongs to the nitrogen cycle; how roots draw on the store belongs to Plants.

Stocks and rates

Stock	Fills it	Drains it	Unit
organicReserve	A bed swap, at the new type’s rate × capacity; food and waste settling in	Rot, at rate.mulm — about a 10-day half-life at 25 °C; disturbance, into waste; the gravel vac	g, with its content
khReserve	A bed swap: 700 mg/L × capacity of aqua soil, none for inert beds	Every mg of KH the bed takes out of the water	mg CaCO₃
nutrients	A bed swap: NO₃ · PO₄ · K · Fe at 50 · 5 · 20 · 1 mg/L × capacity of aqua soil, none for inert beds; root tabs	bedLeakRate of what remains per tick, into the water; root feeders’ stores	mg of each
tannins	A new driftwood piece: 3,000 mg; none for other pieces	tanninLeachRate of what remains per tick, out of kh	mg CaCO₃
dosedToday	Firing the dose	The midnight reset	flag

Everything else on this page is either recomputed from nothing each tick or pushed straight out as an effect. Equipment holds almost no state, which is what makes its contribution reversible the instant a fitting is switched off.

Key tunables

The bed’s tunables are listed in the reference under Decomposition and Nutrients; every other number on this page is a module constant.

Constant	Meaning	Value
CO2_MASS_RATE	CO₂ metered per bubble per second, off a ~0.1 mL bubble	648 mg/hr/bps
WATER_LEVEL_THRESHOLD	Fill fraction below which the ATO refills to full	0.99
baseOutputLph	Air output of the smallest pump band	60 L/h
flowPerAirLph	Share of air output that becomes water movement	0.1
MAX_LIGHT_PAR	Ceiling on a fixture rating — full noon sun at the surface	2000 µmol/m²/s

Seams

Neighbour	Read	Written
Environment	water and temperature size the heater’s rate and the ATO’s refill; capacity gives the box	temperature, water
Nitrogen cycle	—	surface is the colony ceiling; the bed holds the mulm food and waste settle into, rotting to ammonia where it lies; a bed swap scales both guilds by the surface fraction it kept
Water & gases	—	flow and aeration set the exchange rate; CO₂ injection adds co2; hardscape and aqua soil move kh and gh; the ATO blends oxygen and co2 toward tap values and adds tap kh and gh as it refills
Light	—	The fixture’s rating and photoperiod are the whole of the light chain’s input
Plants	—	The doser writes nitrate, phosphate, potassium and iron; the bed’s store feeds root feeders and leaks the same four into the water
Livestock	—	The feeder writes food. Otherwise fish meet equipment through the water it conditions
Algae	—	The glass, the floor and the hardscape are film’s habitat; a piece set down thins its coverage, a piece lifted takes its share, and a swapped bed takes the floor’s
Actions	—	A root tab fills the bed’s store. No other verb reaches a fitting: settings are plain fields the host writes, and a bed swap is an equipment helper of its own — the one such call that costs an organism stock, since both colonies and the floor’s film leave with the substrate
State & persistence	—	Every fitting’s settings serialise; the passive four are recomputed rather than stored

Source

src/simulation/equipment/ for the fittings and the passive-resource collection; src/simulation/config/ for the bed’s tunables.