WorldPulse

A world that reacts to what your players actually do.

WorldPulse is a Paper plugin built around a simple loop: player activity → world state → world reaction → new player activity. Instead of firing random events on a timer regardless of what's happening on your server, WorldPulse continuously measures real player behavior in each world and lets that measurement drive how the world responds. No two servers — and no two worlds on the same server — will ever pulse the same way, because the numbers are generated by your players, not a dice roll.

This page covers the v0.2 release, which adds a full World State layer on top of the activity tracking introduced in v0.1.

Concept

WorldPulse models each world in layers:

1. Activity (Pulse) — a 0–100 value per channel (Mining, Combat, Farming, Exploration, Nature) that reflects how much of that kind of play is happening right now.
2. World State — four derived scores (Threat, Stability, Ecology, Civilization) computed from Activity and from dedicated signals like player deaths, trading, and building.
3. Reaction — when a World State score crosses a threshold, the world announces it (a warning when things get dangerous or a forest starts dying, a recovery message when it settles back down).

Everything decays smoothly over time rather than resetting on a timer, so the numbers always describe the recent, lived history of a world instead of a lifetime total.

Features in v0.2

Activity Tracking (5 channels)

• ⛏ Mining — breaking stone, deepslate, and ores (including nether variants and ancient debris). Blocks a player placed themselves are excluded, so silk-touch "place and re-mine" loops don't inflate the number.
• ⚔ Combat — killing hostile mobs and raid mobs (zombies, skeletons, creepers, endermen, blazes, pillagers, ravagers, and more).
• 🌾 Farming — harvesting fully grown crops (wheat, carrots, potatoes, beetroot), breaking pumpkins/melons, and breeding animals.
• 🧭 Exploration — discovering new chunks, with bonus credit for entering the Nether or the End.
• 🌲 Nature (new) — felling trees, planting saplings/mangrove propagules, and fishing. Player-placed logs are excluded from felling credit the same way placed ore is excluded from Mining.

World State (new)

Four scores (0–100) computed every update tick from Activity Pulse values and from their own dedicated signals:

• ⚠ Threat — rises with sustained Combat activity and spikes on player deaths; fades on its own once things calm down.
• ⚖ Stability — smoothly tracks a target derived from Threat and from extreme (very high) Mining/Combat activity. A world that's quietly ticking along stays stable; a world in overdrive drifts out of equilibrium.
• 🌱 Ecology — a running ecological balance, not a decaying activity count. Felling pulls it down, planting pushes it up, and it drifts gently back toward a healthy baseline on its own when left alone — forests don't wither away just because nobody's watching.
• 🏛 Civilization — grows with completed villager trades, building-material placement, and bed placement, and scales with how many players are currently active in that world and how much of it has been explored. Fades if a world goes quiet.

Automatic Reactions (new)

WorldPulse now reacts on its own when a World State score crosses a configurable threshold — a chat announcement when a world's Threat spikes, its Ecology declines, or its Stability drops, and a matching recovery message once it settles back down. Each reaction uses separate "warning" and "safe" thresholds (hysteresis) plus a cooldown, so a value hovering right at the line won't spam chat.

This is the foundation that Dynamic Events (actual gameplay changes, rewards, GUIs) will build on in v0.3 — v0.2 intentionally only announces, it doesn't yet act.

World Statistics & Decay

Every value — Activity and World State alike — now updates through a continuous exponential decay model instead of a fixed time window: recent activity pulls a value up, and in its absence the value fades back down smoothly on its own (configurable via pulse.decay-per-hour). Everything still runs purely in memory on a configurable interval (10 seconds by default); no database access happens on the hot path, so per-block or per-kill events have effectively zero performance cost.

SQLite History

Periodic snapshots (every 5 minutes by default) of both the Activity Pulse and the World State are written asynchronously to a local worldpulse.db, across two tables (world_statistics, world_state_snapshots). Upgrading from v0.1 migrates your existing database automatically — no need to delete or recreate it.

Commands

Command	Description	Permission
/worldpulse status [world]	Shows the current Activity Pulse and World State for a world (defaults to your current world)	worldpulse.status
/worldpulse reload	Reloads config.yml without a restart	worldpulse.admin

Configuration

Everything is controllable per world, including whether Reactions are announced there:

worlds:
  world:
    enabled: true
    statistics:
      mining: true
      combat: true
      farming: true
      exploration: true
      nature: true
    reactions:
      enabled: true

Disable WorldPulse entirely in a world, disable individual Activity channels, or turn off Reaction announcements per world. Decay rate, update frequency, per-channel thresholds, every World State formula's weights, reaction warning/safe thresholds and cooldown, and the database snapshot interval are all configurable in config.yml.

How the Numbers Are Calculated

Activity Pulse — each tracked action adds points to that world's in-memory counter for the current tick. On every update, the counter is converted into a gain and blended with the previous value:

new = clamp(old × decayFactor + gain, 0, 100)

where decayFactor comes from pulse.decay-per-hour (0.9 by default — a world with zero activity loses about 10% of its Pulse every hour), and gain scales with how much activity happened relative to the channel's configured threshold. Sustained activity at the threshold rate keeps a Pulse near 100; nothing happening lets it fade.

World State mostly reuses the same decay-and-gain shape, with two deliberate exceptions:

• Ecology never decays toward zero on its own — only felling/planting impact and a gentle pull toward a configurable recovery baseline move it, since an untouched forest shouldn't wither away from time alone.
• Stability doesn't accumulate "points" at all; it continuously tracks a target value computed from current Threat and activity extremes, closing the gap a little more each tick.

Roadmap

WorldPulse is being developed in stages, and each version is built on a fully working previous stage:

• v0.1 — Activity tracking, World Statistics, SQLite, /worldpulse status, configuration
• v0.2 (current) — World State layer (Threat, Stability, Ecology, Civilization), continuous decay, Automatic Reactions, Nature activity channel
• v0.3 — Dynamic Events that respond to World State, an Event GUI, boss bars, titles, sounds, and rewards
• v0.4 — Player Influence tracking, player profiles, achievements, and Pulse history
• v1.0 — Full GUI, PlaceholderAPI support, DiscordSRV integration, a public API, and complete documentation

Requirements

• Server software: Paper (or a Paper fork) — Spigot/CraftBukkit are not supported
• Minecraft version: 1.21.x
• Java: 21+
• No other plugin dependencies

Notes

WorldPulse bundles its own SQLite driver — no external database setup is required, and no other plugin dependencies are needed to run v0.2.

Feedback on v0.2's World State formulas and default thresholds is especially welcome, since the Reactions in v0.2 and the Dynamic Events planned for v0.3 both key off these same numbers.