Skip to content

Writing Your Own Events

Jump to bottom
github-actions[bot] edited this page Oct 18, 2026 · 1 revision

Writing your own events

Every NeroEvents event is a JSON file in a data pack, so a server owner can tune the shipped events, switch them off or add new ones without writing code. This page is the short guide. The full reference — every field, every payload setting and a complete example for each event type — is EVENT-DEFINITIONS.md.

1. Make a data pack

<world>/datapacks/my_events/
  pack.mcmeta
  data/my_events/neroevents/events/night_drop.json

The file's id is its namespace and path: my_events:night_drop. The shipped events live in the neroevents namespace (for example neroevents:core/supply_drop); a file with the same namespace and path in your pack replaces the shipped one.

2. Write the definition

A night-time supply drop for busy servers:

{
  "type": "neroevents:supply_drop",
  "category": "reward",
  "display": {
    "title": "event.my_events.night_drop.title",
    "what_to_do": "event.my_events.night_drop.what_to_do",
    "announce": "event.my_events.night_drop.announce"
  },
  "weight": 4,
  "cooldown_ticks": 72000,
  "announce_ticks": 3600,
  "duration_ticks": 12000,
  "location_public": true,
  "conditions": {
    "dimensions": ["minecraft:overworld"],
    "min_online": 3,
    "time_of_day": { "from": 13000, "to": 23000 }
  },
  "bounds": { "kind": "radius", "radius": 96 },
  "payload": { "tier": 2, "loot_rolls": 3 },
  "rewards": {
    "budget": 400,
    "lines": [
      { "kind": "currency", "amount": 200 },
      { "kind": "xp", "amount": 200 }
    ]
  }
}
  • type is what the event does. The types are neroevents:supply_drop, meteor_shower, debris_crash, solar_storm, planetary_storm, pirate_raid, alien_invasion, boss, market_shock, faction_war and debug_marker. A type whose mod is not installed does not exist, and a definition using it is skipped.
  • category decides which switches and limits apply (reward, hazard, combat, raid, invasion, boss, economy, war). An event that changes blocks must say "destructive": true, and a destructive event can never skip the vote.
  • weight (0 to 1000) is how often the scheduler picks it; 0 means only an operator starts it.
  • Times are in ticks: 20 = 1 second, 1200 = 1 minute, 72000 = 1 hour.

3. Give it words

The display entries are translation keys. Put them in a resource pack for your players (assets/my_events/lang/en_us.json):

{
  "event.my_events.night_drop.title": "Night Drop",
  "event.my_events.night_drop.what_to_do": "Find the pod in the dark and open it first.",
  "event.my_events.night_drop.announce": "A supply pod is coming down in %1$s in about %2$s min. %3$s",
  "event.my_events.night_drop.todo": "Find the pod — %s"
}

In announce, %1$s is the dimension, %2$s the minutes until it starts and %3$s where it is. The optional .todo line is the short instruction on the console and the HUD; %s is the time left.

4. Load it and check it

  1. /reload.
  2. /neroevents list — your event is listed; the skipped count tells you if a file was rejected.
  3. /neroevents preview my_events:night_drop — every scheduling rule with a tick or a cross, a sample place (or which protection refused one), whether it would open a vote, its reward budget and every warning about the file.
  4. /neroevents start my_events:night_drop in a test world.

A file with a mistake never stops the server: the log names the file and the key. A missing required field, an unknown type or a payload value outside its range skips the file; an out-of-range optional field falls back to its default with a warning.

Limits that always apply

Your events follow every rule the shipped ones do: the kill switches, the protection rules, the calm window, the concurrency caps and the daily reward budget. See Protection and fair play.

See also

Clone this wiki locally