Lifecycle Model

This page defines the mathematical model used by the standalone Python simulation tool. The purpose is not to be biologically perfect. The purpose is to make Faerals tunable before the game systems are implemented in Rust.

The model tracks populations by zone × species, then updates them each tick using climate, biome fit, predator pressure, player pressure, migration, and sanctuary restoration.

Core loop

State variables

Each simulated pair keeps four values:

• population - current local density in the range 0.0 to 1.0
• pressure - how heavily the player has been farming that pair
• anomaly_pressure - how unstable the zone currently is
• extinction_streak - how many ticks the population has stayed below the extinction threshold
• region_affinity - intrinsic pull toward a region, independent of pressure and climate
• habitat_tags - region features such as water, grass, sand, snow, hot, or sunny

Compatibility score

The simulation computes a compatibility score for each zone × species pair.

compatibility =
  hard_habitat_gate
  × combined_biome_habitat_climate_food_score
  × prey_balance_score
  × sanctuary_score
  × region_affinity

hard_habitat_gate is 0 when a species requires a habitat tag that the zone does not have. That means a water-bound species cannot spawn in a dry zone, even if other factors look favorable.

This score drives both spawn likelihood and migration pressure.

Spawn score

The encounter model is:

spawn_score =
  base_spawn_modifier
  × compatibility
  × support_score

support_score is shaped by current population presence, prey balance, player pressure, and sanctuary stability. The result stays in the 0.0 to 1.0 range. If compatibility is 0, the spawn score is 0.

Parameter reference

Parameter	What it controls	When you raise it
season_length_ticks	How fast the world moves through Spring, Summer, Autumn, Winter	Seasons turn over faster and climate swings become more visible
biome_weight	How much preferred biome matters in spawn score	Species become more concentrated in their home biomes
climate_weight	How much temperature and humidity matter	Climate mismatches suppress spawns more aggressively
population_weight	How strongly local abundance affects spawns	Dense populations become easier to encounter and observe
region_affinity_weight	How much intrinsic region pull affects spawns	Species cluster more strongly in their preferred regions
predator_weight	How much prey/predator balance matters	Food-chain pressure has a larger effect on encounters
pressure_weight	How much capture pressure suppresses spawns	Repeated farming drives spawn rates down faster
sanctuary_weight	How much restoration stabilises a zone	Restored sanctuaries recover encounter density sooner
base_capture_rate	The baseline strength of player capture activity	Encounters convert into population loss more quickly
pressure_gain_per_capture	How much one capture raises pressure	Farming leaves a longer trace in that zone
pressure_decay_rate	How quickly pressure fades with no farming	Overused species recover faster after the player leaves
sanctuary_recovery_rate	How quickly restored zones shed anomaly pressure	Recovered sanctuaries become stable faster
anomaly_growth_rate	How quickly unrested zones worsen	Unrestored zones become unstable faster
local_extinction_threshold	The population level that counts as dangerously low	Species are declared extinct sooner
local_extinction_ticks	How long low population must persist	Extinction becomes stricter and less noisy
reintroduction_rate	How much released Faerals restore a depleted zone	Releasing Faerals has a stronger recovery effect

Visual companion

The simulator writes plots into tools/lifecycle-sim/outputs/:

• population_timeseries.png
• spawn_score_timeseries.png
• pressure_recovery.png
• zone_species_heatmap.png
• spawn_rates_by_region.png
• heatmap_frames/tick_####.png
• zone_species_heatmap.gif
• events.jsonl
• extinction_risk.png
• sanctuary_timeline.png

Running the tool

cd tools/lifecycle-sim
python -m faerals_lifecycle.cli run --scenario balanced_mvp --ticks 240 --seed 42 --out outputs/balanced

The balanced_mvp, overcapture, delayed_sanctuaries, and reintroduction scenarios are designed to stress different parts of the lifecycle loop. Migration is intentionally small per tick. A species only shifts noticeably when local compatibility drops or a neighboring region becomes clearly better. If climate, prey balance, or sanctuary state improves again, the flow reverses and the population drifts back toward the more compatible region. The CLI shows a progress bar while the simulation runs and streams major events such as sanctuary restoration, reintroduction, and local extinction.