Server documentation

WorldPulse

Active

Hytale • Version 0.3.0

Regional wildlife ecology with breeding, growth, native predator foraging and species chat notices. Supports eligible natural fauna from the game and other mods.

Mod overview CurseForge

Overview

Hunt the same area every day and its wildlife becomes scarce. Leave it alone and populations recover, with suitable neighbouring regions helping them return. Healthy wildlife can breed, and young animals grow into adults.

WorldPulse runs automatically in single-player worlds, friend-hosted worlds and dedicated servers. Install it and play. Commands are for administration and diagnosis.

Installation

Requires Hytale 0.7.0+.
Download WorldPulse-0.3.0.jar from the CurseForge Files tab.
Close the world or server. Replace the previous WorldPulse JAR in UserData/Mods/ or the server’s mods/ folder, keeping only one copy.
Start the world. No player commands are needed. Configuration is created at mods/durkz_WorldPulse/WorldPulse.json.

Regions, hunting and recovery

Population health is a regional index, not a count of all living animals. The default region is 8 x 8 chunks, or 256 x 256 blocks. Each world keeps independent species populations. A player kill of eligible naturally spawned wildlife removes killImpact from the local index, down to minHealth. Melee and player-owned projectiles count.

Recovery uses the world’s in-game calendar. The baseline recoveryDays is 4 days from 10% to 90%; demography, habitat, hunting pressure and migration change the actual pace. Suitable neighbouring regions can help recolonization. This does not physically move existing animals. Sleeping and time skips can advance recovery; stopping the game calendar does not age animals by wall-clock time.

Scarcity reduces future natural spawn targets and respects native group sizes, regional/global quotas and pending spawns. Existing animals are not culled. Eligible natural marker and ambient-beacon fauna use their own source-aware limits. Command-spawned animals, pets, monsters and scripted or faction encounters remain excluded by the default policy.

Wildlife discovery and compatibility

WorldPulse reads the game’s registered roles and resolved categories, model capabilities and display-name keys, including those supplied by other mods. Folder rules remain available, and automatic category discovery extends them without a hardcoded list of species. Native wildlife includes suitable terrestrial, aquatic and avian roles; monsters, humanoids and tamed animals are excluded by the default policy.

extraRoles and excludedRoles are optional administrative overrides. Check /wp inspect <role> for the actual inclusion or exclusion reason, model or lifecycle limitations, food evidence and active native quotas. An eligible role may support population tracking while lacking the model data needed for breeding. No compatibility claim covers every asset pack or every registered NPC.

Compatibility uses registered data rather than bundled copies or per-pack patches. WildTale 5.2 was checked alongside WorldPulse, including eligible wildlife and capture/taming transitions. Invalid third-party roles and item spawners remain the responsibility of their source mod. Foraging support is narrower than population tracking; an animal can participate in ecology without gaining a new foraging AI.

Breeding and growth

Breeding needs eligible mature parents, a suitable habitat, population health of at least 60%, hunting pressure no higher than 50%, parent cooldowns and room under native spawn limits. Default lifecycle timing is derived from model volume, bounded to 1 to 4 in-game days. Births also respect collision clearance and reservation limits.

A native juvenile role is selected only when its relationship with the adult is unambiguous. Otherwise the original model starts at 60% scale. Young animals begin at 50% native health and outgoing damage and grow gradually while keeping their native AI. If the adult collision box cannot fit, growth remains juvenile until there is room. Identity and health fraction are retained through growth.

Lifecycle state is saved with the animal. Returning to an unloaded chunk can advance growth according to the running world calendar, but there is no queue of births while a chunk is unloaded. Taming retires identifiable WorldPulse age effects while preserving independent model or stat overrides.

A cancelled or failed birth returns its reserved daily slot and parental cooldowns. A successful child keeps the reservation even if later bookkeeping fails. An abrupt crash with an unknown spawn outcome conservatively retains the durable reservation to avoid duplicate births; replay never creates animals.

Ecology messages

Players in the affected region receive notices naming the relevant species: hunting decline, scarcity, recovery, pressure discouraging return, a completed birth or a young animal reaching adulthood. Notices are based on actual state changes or completed lifecycle events. They do not announce physical migration.

There is a shared per-player limit of one message per 10 seconds and a two-minute cooldown per species/event scope, with a critical-decline exception. This prevents repeated scans from flooding chat. Species labels use registered names and available game translations; the message sentences are currently English. Set enableEcologyMessages to false to disable them.

Hunger-driven searches, concentrations of hungry predators and successful hunts can also produce local notices. A notice reports observed activity; it does not guarantee an attack or identify a house as a target.

Predator hunger and foraging

Eligible adult predators accumulate hunger only while loaded. With normal prey availability, the default pace is 40 loaded minutes from fed to fully hungry; known prey scarcity can double that pace. Searching starts at 50% hunger, uses 24-block steps and allows up to eight simultaneous searches per world by default. Successful eligible hunts reduce hunger.

Predators use native navigation and combat. They search nearby loaded terrain and suitable neighbouring areas, with bounded work and retries for blocked routes. WorldPulse does not locate beds, homes or distant players and does not spawn or teleport predators to create encounters. Existing native aggression remains active regardless of hunger.

The default list contains 20 native roles. Adding a modded role to foragingRoles does not guarantee compatibility: the role also needs a supported native template, movement and usable metadata. Tamed animals leave this system. Loaded-time hunger and lifecycle state persist with the animal; offline time does not accumulate a queue of hunts or births.

Food web

A predator/prey link activates after three distinct prey UUIDs have been killed by the same predator role in that world. Only eligible natural predator-attributed lethal interactions supply evidence; fear or hostility alone does not establish a diet. Once a link is known, local prey availability can lower future predator spawning, bounded by predatorMinFactor.

This models repeated lethal interactions, not eating animations or a complete biological diet. Unknown diets are neutral. Evidence is persisted per world and shown by /wp inspect <role>.

Features

Regional populations: each species has its own population health in every region, 8 x 8 chunks by default. Player hunting reduces future natural spawning there.
Recovery and hunting pressure: populations recover over in-game days. Habitat and pressure affect recovery, while healthy neighbours can support recolonization.
Physical breeding: eligible natural wildlife can produce young when parents, population health, habitat and native spawn limits allow it.
Growing young: young animals start smaller and weaker, then grow gradually. Native juvenile roles are used when a reliable relation exists; otherwise the original model is scaled.
Notices for each affected species: nearby players receive chat messages about decline, scarcity, recovery, hunting pressure, actual births and adulthood, with cooldowns.
Native and modded wildlife: registered role metadata supplies classification, models and names. No player setup or built-in list of another mod’s animals is required.
Learned predator relations: repeated predator kills establish local prey links. Prey scarcity can then reduce future predator spawning; unknown diets remain neutral.
Persistent worlds: populations, pressure, breeding cooldowns, young animal state and learned food relations survive saves and restarts.
Hungry predators: 20 configured native predator roles can search nearby loaded terrain for food using native navigation. Prey scarcity accelerates hunger, while native aggression remains independent.
Marker and beacon fauna: eligible natural animals from map markers and ambient beacons participate in ecology and breeding within their own native spawn limits. Pets, monsters and scripted encounters retain their exclusions.

Commands

Admin command: /wp. Regular players receive ecology notices without command permission.

Command	Description
`/wp here`	Show wildlife population health in the current region.
`/wp set <species> <percent>`	Set local population health, from 0 to 100, for a registered spawn role.
`/wp tick <days>`	Advance population recovery in this world by the requested in-game days; this is not a full world time skip.
`/wp reset`	Clear regional populations, habitat, pressure and breeding reservations/cooldowns in this world. Does not erase the separate learned food file.
`/wp stats`	Show hunt, spawn, catalog and capability counters.
`/wp inspect <role>`	Explain tracking eligibility, model/lifecycle support, learned prey evidence and active native quotas.

Permissions

durkz.worldpulse.command.wp: access to /wp commands and update notices. Operators have it by default.

Configuration

File: mods/durkz_WorldPulse/WorldPulse.json. Defaults below apply to a new configuration. Existing valid choices are retained, so an older world can keep its previous recovery setting. Restart after editing. configVersion is managed by the mod.

Field	Default	Description
`configVersion`	`3`	Internal configuration format.
`enabled`	`true`	Enable WorldPulse.
`regionSizeChunks`	`8`	Region edge in chunks, 1 to 64.
`killImpact`	`0.1`	Population health lost per counted player kill.
`killImpactByRole`	`{}`	Optional per-role kill impact overrides.
`minHealth`	`0.02`	Lowest population health.
`recoveryDays`	`4.0`	Baseline in-game days from 10% to 90%, modified by ecology.
`enableDemography`	`true`	Use demographic recovery modifiers.
`enableHuntingPressure`	`true`	Track and apply hunting pressure.
`enableBreeding`	`true`	Allow eligible wildlife births and growth.
`enableEcologyMessages`	`true`	Send automatic species notices in chat.
`autoDetectWildlife`	`true`	Discover wildlife through resolved native categories.
`enableMigration`	`true`	Allow statistical regional recolonization.
`enableHabitat`	`true`	Apply observed habitat suitability.
`enableFoodWeb`	`true`	Apply learned predator/prey supply factors.
`migrationPerDay`	`0.04`	Maximum regional migration gain per in-game day.
`predatorMinFactor`	`0.4`	Minimum predator spawn factor from food availability.
`faunaFolders`	`["Creature", "Aquatic", "Avian"]`	Folders accepted as wildlife.
`excludedFolders`	`["Creature/Mythic", "Creature/Hunt"]`	Excluded wildlife subfolders.
`excludedRoles`	`[]`	Optional role exclusions.
`extraRoles`	`[]`	Optional explicit role inclusions.
`checkForUpdates`	`true`	Check the site and notify players with command access of newer releases.
`debugLog`	`false`	Verbose spawn decisions for diagnosis.
`enableForaging`	`true`	Enable hunger-driven searches for eligible configured predators.
`foragingRoles`	`20 native roles`	Explicit role list; see the default list below.
`forageHungerMinutes`	`40.0`	Loaded real-time minutes from fed to fully hungry with normal prey.
`forageStartHunger`	`0.5`	Hunger fraction that permits searching.
`forageStepBlocks`	`24`	Search step length in blocks.
`maxForagers`	`8`	Maximum concurrent foraging searches per world; 0 disables searches.

Default foraging roles

["Wolf_Black", "Wolf_White", "Fox", "Hyena", "Bear_Grizzly", "Bear_Polar", "Leopard_Snow", "Tiger_Sabertooth", "Raptor_Cave", "Crocodile", "Rex_Cave", "Toad_Rhino", "Toad_Rhino_Magma", "Snake_Cobra", "Snake_Marsh", "Snake_Rattle", "Spider", "Molerat", "Spider_Cave", "Spider_Cave_Ambush"]

Data files and recovery

Path	Purpose
`populations.json`	Populations, habitat, pressure and breeding bookkeeping.
`populations.journal`	Committed incremental population updates.
`food-relations.json`	Learned predator/prey evidence checkpoint.
`food-relations.json.journal`	Committed incremental food evidence.

These files live under <world save>/WorldPulse/. Young animal lifecycle components are stored with the native entities. Keep both world entities and WorldPulse files together in backups.

Checkpoints use atomic replacement and journals replay committed records. An unfinished final journal line is ignored. Invalid committed records or unsupported future formats preserve the originals and suspend the affected capability instead of silently starting over. A food-data failure is isolated from population checkpointing. Logs and /wp inspect report food failures. A crash before an asynchronous write is committed can still lose that pending observation.

For a persistence error, stop the server and back up the files before restoring a known-good copy. Do not delete data as a routine upgrade step.

Start with the defaults and give populations several in-game days to respond.
Rotate hunting grounds. Raise recoveryDays or lower killImpact to adjust the pace.
Use /wp inspect <role> before adding compatibility overrides. Most correctly classified wildlife needs no manual registration.
Back up world data before changing regionSizeChunks; a different region grid changes how saved coordinates map to terrain.

Verifying it works

Check startup logs for WorldPulse and enabled=true; no player command is required for normal play.
Use /wp stats to see the registered wildlife catalog. Use /wp inspect <role> on a real role from the installed game or asset pack.
Hunt eligible naturally spawned wildlife, then use /wp here to check the local decline. Manually spawned animals are not a substitute.
Give the running world several in-game days. Look for recovery and, where conditions allow, actual births and young growth. Chat notices have cooldowns.
Save, stop and restart the world. Recheck a depleted region and any young animals to confirm their state persists.

Status and known limitations

Active project. Automatic discovery depends on usable role metadata and valid models. Broken third-party assets can exclude individual roles. Regional migration changes population health; compatible hungry predators can separately move through loaded terrain using native navigation. Searches depend on terrain, prey and native behaviour and do not guarantee an encounter. Existing animals are not culled. Ecology message sentences are currently English; species labels use available game translations with a readable fallback.