Skip to content

Ambient Events

Jump to bottom
okereke-dev edited this page Jul 17, 2026 · 4 revisions

Ambient Events

triggers.yml defines scheduled messages/sounds tied to time of day, weather changes, and block breaks. All events are checked once per second for every online player who hasn't disabled effects (/rpgmood toggle).

Time and weather event messages (not block-break, which goes to chat) are delivered through MessageService — action bar by default (sticky, see Configuration → messages), same channel farming/animal feedback uses. Zone entry is separate and doesn't use this channel at all — see Zones.

Time events

Fire when the world's time-of-day ticks (0–24000) crosses within 100 ticks of a configured time, with a 10-minute cooldown per event key to avoid re-firing every second while the game clock sits near that value.

time_events:
  dawn_arrival:
    trigger: "on_time_change"
    time: 2300
    message: "&e[Ambient] &7Dawn breaks. The world stirs anew, and the air tastes of fresh danger."
    sound: "entity.chicken.egg"
  • time — Minecraft world time (0–24000). Common reference points: 0 sunrise, 6000 midday, 12000 sunset, 18000 midnight.
  • message — supports &-color codes.
  • sound — any Bukkit Sound enum name (lowercase, dotted), e.g. entity.wolf.howl.

Matching correctly wraps around midnight (tick 23999 → 0), so an event configured at time: 0 fires reliably instead of only when the clock lands on exactly 0.

Weather events

Fire on weather transitions (not on a fixed schedule) — comparing each world's current weather (clear / rain / thunder) against what it was last tick.

weather_events:
  rain_start:
    weather: "rain"
    state: "start"
    message: "&bThe sky darkens and rain begins to fall over {location}."
    sound: "ambient.weather.rain"
  rain_end:
    weather: "rain"
    state: "stop"
    message: "&aThe rain eases, leaving behind a glistening path."
    sound: "entity.item.pickup"
  • weather — rain or thunder. (clear isn't itself a triggerable target — it's just the state when neither is active.)
  • state — start (weather just began) or stop (weather just ended).
  • Same 10-minute per-event cooldown as time events.

Block-break events

Chance-based ambient message when a specific block type is broken.

block_events:
  diamond_ore:
    trigger: "on_block_break"
    block: "DIAMOND_ORE"
    chance: 30
    message: "&e[Ambient] &bAn ancient energy emanates from the broken crystal..."
  • block — a Bukkit Material enum name.
  • chance — integer 0–100, percent chance per matching block break.
  • No cooldown — every matching break gets an independent roll.

Day/night ambient sounds

Separate system from the time/weather messages above, living in config.yml (not triggers.yml) since it's a fixed day/night pair rather than a list of named events. Checked on the same ~1s tick, per online player:

ambient_sounds:
  enabled: true
  chance: 0.02
  day:
    - "entity.parrot.ambient"
  night:
    - "ambient.cave"
  • chance — probability (0–1) per player per tick that a sound plays at all. At the default 0.02, checked once a second, that's roughly one sound every ~50 seconds per player.
  • day / night — pools of Bukkit Sound names (or resource-pack custom keys), selected by whether it's currently vanilla day or night (13000–23000 ticks) at the player's location. One entry is picked at random and played quietly (0.5f volume) directly at the player — purely cosmetic, no chat/action-bar message accompanies it.

Full key reference: Configuration → ambient_sounds.

Nether acid rain {#nether-acid-rain}

The Nether has no vanilla weather to hook weather_events into, so it gets its own standalone periodic hazard in triggers.yml, checked once per second for every online player currently in a Nether world:

nether_events:
  acid_rain:
    enabled: true
    chance: 0.01
    damage: 1.0
    message: "&4Ash rains from above, searing your skin."

Unlike time_events/weather_events/block_events above, nether_events isn't a list of arbitrarily-named events — acid_rain is the one hazard under it, and the key name itself is fixed (not user-defined). chance is rolled independently per player per tick; on a hit, damage is applied via Player#damage() and message is delivered through the usual MessageService channel (action bar by default, see Configuration → messages).

Adding your own

All three of time_events, weather_events, and block_events accept as many keys as you want — the key name itself (dawn_arrival, rain_start, diamond_ore, ...) is just an internal identifier used for cooldown tracking, and can be anything descriptive. ambient_sounds and nether_events.acid_rain are fixed-shape sections instead — there's nothing to add a new named entry to, only values to tune.

Removed in v1.10.0: weather_effects (brief Darkness pulses during thunderstorms, wind nudges during rain) was removed from config.yml and the ambient tick logic along with the curated zones.yml system. weather_events above (the one-shot start/stop chat/action-bar messages) is unaffected and still works exactly as documented.

Clone this wiki locally