The Flow — Resource Cycles

The Flow models the resource economy of the Living World: how resources are generated, consumed, depleted, and replenished. It connects directly to The Wild (fauna consume resource nodes) and The Veil (climate conditions modify regeneration rates). Players and NPCs harvest from resource nodes via The Echo.

Resource nodes

A resource node is a point in a zone that holds a depletable quantity of a resource. Nodes are defined by ResourceNodeDefinition assets:

{
  "id": "berries_north_forest",
  "resourceType": "berries",
  "zoneId": "zone_north_forest",
  "capacity": 500,
  "initialLevel": 500,
  "regenRate": 0.05,
  "regenConditions": {
    "minPrecipitation": 0.2,
    "minTemperature": 5,
    "vetoWeatherStates": ["Drought"]
  },
  "wildConsumers": [
    { "speciesId": "rabbit", "consumptionRate": 0.01 }
  ]
}

Key fields:

• capacity — the maximum level the node can reach
• regenRate — fraction of capacity restored per world-day under ideal conditions
• regenConditions — Veil constraints on regeneration. If current precipitation falls below minPrecipitation, regeneration is halved. If the zone’s weather state is Drought, regeneration is zero.
• wildConsumers — species that passively consume this node. Each rabbit in the zone consumes consumptionRate per world-day.

Harvesting from game code

Players harvest resource nodes via The Echo’s auto-emission system. When you call ResourceNodeService.Harvest(), the engine automatically emits a Mine or Harvest Echo event with the appropriate magnitude.

var resourceService = Services.Get<ResourceNodeService>();

// Attempt to harvest 50 units from a node
HarvestResult result = await resourceService.HarvestAsync(
    nodeId: "berries_north_forest",
    requestedAmount: 50
);

if (result.Success)
{
    Logger.Info($"Harvested {result.AmountGranted} berries. Node level: {result.RemainingLevel}");
    playerInventory.Add("berries", result.AmountGranted);
}
else
{
    // Node depleted
    Logger.Info("The berry bush is bare.");
}

HarvestAsync is async because it submits the Echo event to the Root for validation before confirming. The granted amount may be less than requested if the node level is lower than expected (another player may have harvested recently).

Reading Flow state

Query current resource levels synchronously from the local cache:

var worldState = Services.Get<IWorldStateQuery>();

ResourceLevelSnapshot berries = worldState.GetResourceLevel(
    zoneId:     "zone_north_forest",
    resourceId: "berries"
);

Logger.Info($"Berry level: {berries.Current}/{berries.Capacity} ({berries.Percent:P0})");
Logger.Info($"Trend: {berries.Trend}"); // Replenishing | Stable | Depleting | Exhausted

Scarcity events

Subscribe to ResourceScarcityEvent to react when a resource drops below a threshold:

var cache = Services.Get<WorldStateCache>();
cache.Changed += (sender, change) =>
{
    if (change is ResourceScarcityEvent scarcity
        && scarcity.ZoneId == myZoneId
        && scarcity.ResourceId == "berries"
        && scarcity.Severity == ScarcitySeverity.Critical)
    {
        // Below 10% capacity — adjust NPC foraging behaviour
        NpcForagingDirector.SetResourceScarce("berries", zoneId: myZoneId);

        // Show an environmental hint to the player
        HintSystem.Show("The berry bushes are nearly bare. The animals are struggling.");
    }
};

Scarcity severity levels: Moderate (< 40% capacity), Severe (< 20%), Critical (< 10%), Exhausted (0).

Resource Flow Editor

The Resource Flow Editor panel (View → Living World → Resource Flow Editor) provides:

• A zone-by-zone view of all resource nodes and their current levels
• Historical level graphs over world-time
• Regen rate override controls for testing
• Wild consumer assignment — drag species from the Wild species library onto a node to add consumption
• Veil sensitivity configuration — set per-node regen modifiers for each Veil condition

How Wild and Veil interact with The Flow

The three subsystems form a feedback loop:

1. Wild fauna consume resource nodes each tick. A large rabbit population depletes berry nodes faster than they regenerate.
2. The Veil’s current precipitation and temperature affect regen rates. Drought suppresses plant node regeneration entirely.
3. Depleted food sources reduce Wild population growth rates (less food = lower birth survival), which in turn reduces consumption, allowing nodes to recover.

This feedback loop runs without any developer-authored logic. It emerges from the interaction of the three subsystems and creates naturally cyclical resource scarcity patterns that survive for years of world-time.