Skip to content

Zones

Jump to bottom
okereke-dev edited this page Jul 12, 2026 · 7 revisions

Zones

RPGMood divides the world into zones. Whenever a player crosses into a new zone, they get a Title + Subtitle, a sound, and particles — all at once, entirely on one channel (no action bar hop). Zones are defined in zones.yml.

Zone types

BIOME

Triggers when the player's current biome matches the configured id. Matching is lenient — the configured id is compared against the current biome name (case-insensitive, spaces/underscores normalized), and partial matches are allowed (e.g. id: PLAINS also matches SUNFLOWER_PLAINS).

zones:
  elden_meadows:
    type: BIOME
    id: PLAINS
    title: "&aElden Meadows"
    subtitle: "&7Where the wind whispers secrets..."
    sound: "ambient.weather.wind_light"
    particles: "NONE"
    flavor_texts:
      - "The breeze gently brushes your face."
      - "The grass shimmers under the sunlight."

WORLDGUARD

Triggers when the player is standing inside the named WorldGuard region. Requires WorldGuard to be installed — if it isn't, WORLDGUARD zones are silently skipped (never trigger), everything else keeps working normally.

zones:
  protected_spawn:
    type: WORLDGUARD
    id: "main_spawn"
    title: "&eSanctuary of Initiation"
    subtitle: "&aA safe place to rest"
    sound: "ui.toast.challenge_complete"
    particles: "HAPPY_VILLAGER"
    flavor_texts:
      - "You feel safe within the walls."

id must match the WorldGuard region ID exactly (case-insensitive) — create the region first with /rg define main_spawn.

particles spawns a burst of the named Particle enum value above the player's head on zone entry (20 particles, small spread). Set to "NONE" (or omit) to disable for a zone. An invalid/misspelled particle name is skipped silently rather than erroring.

subtitle + flavor_texts

These aren't two separate messages — they're one combined pool. On each zone entry, RPGMood picks one line from subtitle + all of flavor_texts (deterministically, varying by where exactly you are in the zone) and shows it as the Title's Subtitle. This is what gives repeat visits some variety instead of the exact same line every time — write 2-3 flavor_texts per zone if you want that. There's no separate action-bar message anymore: everything rides the Title/Subtitle, which is the one channel in RPGMood that's never competing with anything else for the player's attention (see Configuration → messages for why that matters).

Unclaimed areas — dynamic zones

Any area that doesn't match a configured BIOME or WORLDGUARD zone still gets a zone identity, generated on the fly from the player's biome group and a 256×256-block grid cell (world|biomeGroup|regionX|regionZ). This guarantees every corner of the map feels named, not just the areas an admin explicitly configured.

A dynamic zone gets:

  • A procedurally-combined name (see below)
  • A biome-appropriate Subtitle, picked from a built-in pool per biome (not configurable via YAML — see ZoneManager.java if you want to add more) — same combined-pool/rotation behavior as configured zones' subtitle + flavor_texts

How dynamic names are generated

RPGMood ships ~20 hand-written names per biome group (e.g. PLAINS: "Elden Meadows", "Sunlit Barrows", "Whispering Grasslands", ...). Each name is split on its first space into an adjective and a noun at startup. Recombining them independently turns ~20 names per biome into up to adjectives × nouns (typically 300–400) unique combinations, without needing to author hundreds of new names by hand.

The specific combination for a given grid cell is picked deterministically (seeded from the cell's coordinates), so revisiting the same area within a server session always shows the same name. If every combination for a biome is somehow already in use elsewhere on the server, RPGMood falls back to a numeric suffix (Elden Meadows 2) — this is a last resort that should essentially never happen in practice given the size of the combinatorial pool.

Assigned names are cached in memory (capped at 2000 entries) but not persisted to disk — a server restart can reassign a previously-visited area a different name from the same pool.

Avoiding title spam

Three independent mechanisms keep zone feedback from becoming annoying, regardless of how you're moving (on foot, at a border, on horseback, in a boat/minecart, or flying with an elytra):

Dwell time (hysteresis)

A zone change isn't confirmed the instant you cross a boundary — RPGMood waits 1.5 seconds (3 seconds while gliding or riding a vehicle) and re-checks whether you're still in that zone before firing any feedback. If you crossed back out before the wait is over (pacing on a border, clipping a biome corner while flying, blasting through on a fast horse), nothing fires at all. This is the main fix for border flicker and fast pass-throughs.

Cooldown

settings.zone_change_cooldown in config.yml (default 45 seconds) throttles how often a single player can trigger zone feedback at all, on top of the dwell time above.

Title-specific memory

Even after the dwell time and cooldown both pass, the big Title/Subtitle only shows if you haven't seen that same zone's title in the last 5 minutes — independent of the ambient cooldown above. The sound and particles aren't affected by this and still play normally. While gliding or riding a vehicle, the title (when shown) also uses a shorter fade-in/stay/fade-out so it doesn't linger over your view during fast, precision movement.

Players who find the on-screen titles specifically annoying (as opposed to the whole ambience system) can run /rpgmood toggle titles to disable just that part — sound and particles keep working. See Commands.

Every zone-change event that clears the cooldown also counts toward that player's /rpgmood leaderboard zones total — see Commands.

Clone this wiki locally