Ambient Events

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.

Weather mechanical effects

Where weather_events above only fires a message at the instant weather starts/stops, weather_effects (also in config.yml) checks the world's live weather state — World#isThundering() / World#hasStorm() — on the same ~1s tick, so it can keep applying for as long as the storm actually lasts:

weather_effects:
  enabled: true
  fog_chance: 0.05
  wind_chance: 0.03
  wind_strength: 0.15

• While thundering: fog_chance per player per tick to apply a brief (3-second, ambient) Darkness potion effect — a fog-like pulse, not a literal fog particle.
• While raining (including during a thunderstorm) and the player is standing under open sky: wind_chance per tick to nudge the player sideways with a small random-direction velocity of magnitude wind_strength.
• Both rolls are independent — a Darkness pulse and a wind nudge can both land for the same player during the same thunderstorm.

Admins can flip weather_effects.enabled in-game via the Admin Config menu instead of editing the file. Full key reference: Configuration → weather_effects.

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, weather_effects, and nether_events.acid_rain are fixed-shape sections instead — there's nothing to add a new named entry to, only values to tune.