ZombieRounds Documentation

Configuration files

ZombieRounds uses a small set of YAML files, with most map behaviour living in a per-map configuration file.

lobbies.yml

The lobby selector reads lobbies.yml. Each entry requires a human-readable display_name and a source_config pointing to a map configuration file in the plugin data folder. Entries whose source config does not exist are skipped.

lobbies:   - display_name: "Metro"     source_config: "config.yml"    - display_name: "Amsterdam"     source_config: "config_amsterdam.yml"

The selector generates an internal slug from the display name, with duplicate IDs receiving a numeric suffix.

Map config.yml

Each map config can define its lobby position, round rules, enemy selection, spawn zones, power-ups, special rounds, doors, breakable floors and Mystery Box. The examples below show the structures currently understood by the plugin source.

Lobby and game settings

cod_zombies_gun_mode: true  lobby:   maxPlayers: 4   teleportLocation:     world: world     x: 100.5     y: 64     z: -20.5     yaw: 90     pitch: 0   hubLocation:     world: world     x: 0.5     y: 80     z: 0.5     yaw: 0     pitch: 0   powerupProbability: 5.0

Characters and character voices

ZombieRounds has an optional per-map character system. At the beginning of a game it can assign each lobby player a unique configured character, temporarily apply that character's skin, and play character-specific dialogue in response to game events such as taking damage, killing a zombie, buying a door, starting a round or being downed.

Enabling characters for a map

Character support is deliberately opt-in. It is enabled for the active map only when both of the following are true:

1. plugins/ZombieRounds/characters.yml exists.
2. The active map config contains a non-empty lobby.characters list.

If either part is missing, ZombieRounds simply runs without character assignment, temporary skins or character dialogue.

lobby:
  maxPlayers: 4
  characters:
    - arnold
    - attenborough
    - bob
    - queen

The list is map-specific, so different maps may use different casts. The actual character definitions remain global in characters.yml. Character IDs are matched case-insensitively. Unknown IDs in lobby.characters are skipped and logged.

Character assignment

At game start the characters supported by the active map are shuffled and assigned uniquely to online lobby players. A character is therefore not permanently tied to a particular player. If there are more players than configured characters, the extra players keep their normal skin and receive no character voice.

Character assignments, voice cooldowns and temporary skins are cleared when the game ends. A player's original skin is also restored when they leave.

characters.yml

Each entry beneath characters defines an ID, display name, optional skin and any number of voice-event rules.

characters:
  arnold:
    displayName: "Arnold Schwarzenegger"

    skin:
      value: "<base64 texture property>"
      signature: "<texture signature>"
      # Alternatively:
      # url: "https://textures.minecraft.net/texture/..."

    voices:
      onDamage:
        chance: 0.25
        cooldown: 4
        volume: 1.0
        pitch: 1.0
        duration: 2.0
        sounds:
          - "minecraft:zombierounds.character.arnold.on_dmg"

      onKill:
        chance: 0.10
        cooldown: 8
        volume: 1.0
        pitch: 1.0
        duration: 2.5
        sounds:
          - "minecraft:zombierounds.character.arnold.on_kill"

      onDoorPurchased:
        chance: 0.5
        cooldown: 5
        sounds:
          - "minecraft:zombierounds.character.arnold.on_door_purchase"

      onNotEnoughMoneyForDoor:
        chance: 1.0
        cooldown: 3
        sounds:
          - "minecraft:zombierounds.character.arnold.on_no_money"

Skin configuration

Skins are applied temporarily using the Paper/Bukkit player-profile API. A character may contain voices without a skin; failure to apply a skin does not disable character voice support.

Voice rule properties

If no settings are required, an event may also be expressed directly as a list of sounds:

voices:
  onKill:
    - "minecraft:zombierounds.character.arnold.on_kill"
    - "minecraft:zombierounds.character.arnold.on_kill_2"

Currently wired character events

Reserved voice events

The character file format also recognises the following event names. They are reserved in the character event enum for additional hooks, but are not all currently wired into gameplay:

onHeadshotKill
onMeleeKill
onWeaponPurchased
onNotEnoughMoneyForWeapon
onMysteryBoxUsed
onMysteryBoxWeaponReceived
onPowerOn
onPowerupPickup
onPlayerRevived
onOutOfAmmo
onLowAmmo

Voice playback and overlap prevention

Character dialogue uses Minecraft's VOICE sound category and is played directly against the player rather than at a world location. This keeps the dialogue attached to that player instead of fading as they move away from the position where the line started.

Only one character line may occupy a player's voice channel at once. Lower or equal priority events are ignored until the current line's configured duration expires. A higher-priority event can stop and replace the current line. This prevents combinations such as a damage quote and a death quote playing over one another.

Resource-pack sound entries

The strings in sounds refer to sound event IDs defined by the server resource pack's sounds.json. Multiple sounds can be configured for one event and ZombieRounds chooses one randomly when that voice rule fires.

{
  "zombierounds.character.arnold.on_kill": {
    "sounds": [
      "zombierounds/characters/arnold/on_kill"
    ]
  },
  "zombierounds.character.arnold.on_dmg": {
    "sounds": [
      "zombierounds/characters/arnold/on_dmg"
    ]
  }
}

Example map-specific cast

# config_kino.yml
lobby:
  characters:
    - arnold
    - queen
    - attenborough
    - bob

# config_metro.yml
lobby:
  characters:
    - bob
    - arnold

Both maps use the same global characters.yml, but each map chooses which characters are eligible for assignment.

Rounds and mob scaling

Weighted enemy rotation

probability acts as a weight; the values do not need to add to exactly 100. An entry with includeInRotationAfterZones becomes eligible when any listed zone is unlocked.

round:   introTitle: "West Berlin - October 28 1963"   mobStats:     baseHealth: 12     baseSpeed: 0.25     baseAttack: 3.0    aliveMobCap:     base: 24     perPlayer: 4     max: 36    mobProportions:     - mob: HUSK       probability: 39     - mob: PILLAGER       probability: 39     - mob: ZOMBIE_PIGLIN       probability: 22       includeInRotationAfterZones: [4, 5]    startItems:     steak: 0     throwing_knife: 0    progressItems:     steak: 0     throwing_knife: 2

Zombie spawns and zones

zombieSpawnLocations is a list of locations. A spawn without a zone is global and can always be selected. A spawn with a zone only joins the valid spawn pool after that zone is unlocked.

zombieSpawnLocations:   - world: world     x: 100.5     y: 64.0     z: 20.5    - world: world     x: 120.5     y: 64.0     z: 18.5     zone: 2    - world: world     x: 145.5     y: 63.0     z: 10.5     zone: 4

Zones are runtime state. They can be unlocked by doors, the /unlockzombiezone <id> admin command, or map logic that ultimately calls the zone manager. The DSL can test them with zone[unlocked=ID].

Power-ups

Known power-up IDs in this version:

DOUBLE_POINTS, INSTA_KILL, DEATH_MACHINE, MINIFY, KABOOM, MAX_AMMO, BARBEQUE, IRON_UP, HONEY_RUSH, DREADNOUGHT, MULE_KICK, RAPID_FIRE, FAST_RELOAD, FIRE_SALE, WAJOO.

lobby.enabledPowerups accepts either plain names:

lobby:   enabledPowerups:     - MAX_AMMO     - INSTA_KILL     - DOUBLE_POINTS

or richer map entries. The power-up name may be supplied as type, powerup or name:

lobby:   enabledPowerups:     - type: MAX_AMMO     - type: FIRE_SALE       includeInRotationAfterZones: [2]     - type: DEATH_MACHINE       includeInRotationAfterZones: [4, 5]

As with mob gating, matching any listed unlocked zone is sufficient.

Special rounds

If a specialRounds section exists, the config-driven resolver overlays your settings onto built-in defaults. Omitting a property keeps that special round's default. If the entire section is absent, the legacy hard-coded special-round path is used.

specialRounds:   WOLF:     Enabled: true     Frequency: 5     Money_On_Completion: 3000     Reward: MAX_AMMO     Play_Boss_Round_Jingle: false    WARDEN:     Enabled: true     Frequency: 25     Money_On_Completion: 5000     Reward: INSTA_KILL     Play_Boss_Round_Jingle: true

Doors

Doors are named configuration objects. Each door contains one or more cuboid regions and may optionally unlock a zombie zone. DSL rules can detect interaction within a configured door and call unlockDoor by ID.

doors:   station_gate:     cost: 750     zone: 2     material: CUT_COPPER     regions:       - from: { world: world, x: 10, y: 64, z: 20 }         to:   { world: world, x: 12, y: 66, z: 20 }     afterUnlocking:       - from: { world: world, x: 10, y: 64, z: 20 }         to:   { world: world, x: 12, y: 66, z: 20 }     afterUnlockingMaterial: GLASS     afterUnlockingMode: ADD

Typical DSL door hook

/zr execute if block.interact within door[id=station_gate] run unlockDoor[door=station_gate]

One-way barriers

One-way barriers are virtual cuboids. They can independently block players and active ZombieRounds mobs according to direction of travel.

barriers:
  kino_stage_drop:
    from: { world: kino, x: 12, y: 64, z: 20 }
    to:   { world: kino, x: 17, y: 67, z: 20 }
    playerCannotPassThru: NORTH
    mobsCannotPassThru: DISABLED

The value is the prohibited direction of travel. For example, NORTH blocks northbound crossing but permits southbound crossing.

Breakable floors

Breakable floors are disabled unless breakableFloors.enabled is true.

breakableFloors:   enabled: true   defaultBreakDelayTicks: 10   defaultBreakRadius: 4   regions:     metro_platform:       material: STONE_BRICKS       breakDelayTicks: 8       breakRadius: 5       regions:         - from: { x: 20, y: 60, z: -4 }           to:   { x: 40, y: 60, z: 6 }

Mystery Box

The active Mystery Box implementation uses the lowercase mysterybox section. It supports multiple locations, zone-gated locations, a spinning/reveal period, a player accept period, visual beam settings and a whitelist of rewards.

Reward types

Reward entries use type: WEAPON_MECHANICS or type: VANILLA. WeaponMechanics rewards require weaponTitle. Vanilla rewards require a Bukkit material and can also set amount, display name, unbreakable state and enchantments. Either type can be marked wonderWeapon: true.

mysterybox:   enabled: true   cost: 950   spinSeconds: 5   acceptSeconds: 10    displayOffset:     x: 0.0     y: 1.2     z: 0.0    beam:     enabled: true     height: 20     points: 40     particle: END_ROD    locations:     - world: world       x: 100       y: 64       z: 20       facing: NORTH     - world: world       x: 200       y: 65       z: 10       facing: EAST       includeInRotationAfterZones: [3]    whitelist:     - id: mp40       type: WEAPON_MECHANICS       weaponTitle: MP40       wonderWeapon: false      - id: wonder_gun       type: WEAPON_MECHANICS       weaponTitle: ThunderGun       wonderWeapon: true      - id: sword       type: VANILLA       material: DIAMOND_SWORD       amount: 1       name: "&bMystery Sword"       unbreakable: true       enchants:         sharpness: 5

MasterButton

The optional MasterButton section identifies a block location and controls its redstone pulse behaviour.

MasterButton:   world: world   x: 50   y: 64   z: -10   pulseTicks: 20   forcePulse: true   chunkRadius: 1

Global shared bank

ZombieRounds includes an API-backed global bank. A player's bank balance is keyed by UUID and shared across ZombieRounds servers, so money deposited on one server can be accessed on another. It is separate from the temporary in-round wallet.

Bank signs

Right-click a dedicated bank sign. Line 1 must be exactly [BANK]; line 2 selects the operation.

Sign setup

# Deposit sign
[BANK]
Deposit

# Withdraw sign
[BANK]
Withdraw

# Balance sign
[BANK]
Balance

Deposit and Withdraw are intentionally separate signs; there is no combined Deposit/Withdraw sign or sneak modifier.

Cross-server flow

Server A: wallet -> [BANK] Deposit -> GLOBAL BANK
Server B: GLOBAL BANK -> [BANK] Withdraw -> wallet
Server C: [BANK] Balance -> same shared balance

Bank API

The bank client uses UUID-based shared endpoints. There is no per-server bank key.

POST /bank/deposit
POST /bank/withdraw
POST /bank/balance

{
  "player_uuid": "<uuid>",
  "amount": <amount>
}

ZR DSL

The ZR DSL is executed with /zr execute <statement>. It is designed for command blocks and map logic. Command blocks and console execute quietly; players receive a result/error message. DSL commands return the resulting boolean to Bukkit, allowing command-block conditional chains to branch on the result.

The parser is case-insensitive for keywords/action names. The current predicate grammar supports chaining with and only; there is no or operator in this version.

/zr execute if <predicate> run <action> /zr execute nif <predicate> run <action> /zr execute while <number> <ticks|seconds|minutes> [if <predicate>] run <action> /zr execute every <number> <ticks|seconds|minutes> [if <predicate>] run <action>

DSL statements

Timed units supported by the parser are exactly ticks, seconds and minutes.

DSL predicates

Zone state

zone[unlocked=2]

True if the given Zombie Zone is currently unlocked.

Round comparisons

lobby[round<5] lobby[round<=5] lobby[round=5] lobby[round!=5] lobby[round>=5] lobby[round>5]

Compares the current round. Supported comparators are <, <=, =, !=, >= and >.

Executing player's movement flags

player.isSneaking player.isSprinting

These require the DSL command sender to be a player.

Executing player's position

player.position at 100 64 20 with radius 3 player.position at \~ \~ \~5 with radius 2

Requires a player sender. Absolute and Minecraft-style tilde-relative coordinates are supported.

Any lobby player's position

anyPlayer.position at 100 64 20 with radius 3 anyPlayer.position at \~ \~ \~ with radius 5

Selects lobby players inside the radius. World/origin context comes from the executing player, command block, or the configured lobby teleport location. Successful selection can then be consumed by player-targeting actions.

Selected player balance

player[balance>=750]

Tests the currently selected player's Vault/Economy balance.

Any player's balance

anyPlayer[balance>=750]

Finds/selects a lobby player whose balance satisfies the comparison.

Specific button interaction

anyPlayer.interact button at 100 64 20

Matches the last captured player block interaction at exactly that block location, selects that player, then consumes the interaction so the same click cannot be reused by a later predicate.

Interaction within a configured door

block.interact within door[id=station_gate]

Matches a click anywhere inside any configured region belonging to the named door, selects the interacting player, and consumes the interaction.

Combining predicates

if zone[unlocked=2] and lobby[round>=5] run true

Current DSL v1 supports and between predicate atoms.

DSL actions

spawnRandomPowerup type restriction

The action factory accepts a types=[...] argument and validates values against the ZombieRounds power-up enum.

spawnRandomPowerup[types=[MAX_AMMO,INSTA_KILL]] at 100 65 20

teleportTo full form

teleportTo[x=100.5,y=64,z=20.5,world=world,yaw=90,pitch=0]

DSL examples

Buy a configured door when it is clicked

/zr execute if block.interact within door[id=station_gate] run unlockDoor[door=station_gate]

The door's own configured cost is used unless the DSL action supplies a cost override.

Override the price for a particular interaction

/zr execute if block.interact within door[id=station_gate] run unlockDoor[door=station_gate,cost=500]

Button-controlled teleporter

/zr execute if anyPlayer.interact button at 50 65 -10 run teleportTo[x=200,y=70,z=40,world=world,yaw=180,pitch=0]

Require both progression and money

/zr execute if anyPlayer[balance>=1500] and zone[unlocked=2] run deductPlayerBalance[cost=1500]

Spawn a restricted random power-up after a zone opens

/zr execute if zone[unlocked=4] run spawnRandomPowerup[types=[MAX_AMMO,INSTA_KILL,DEATH_MACHINE]] at 100 65 20

Repeating map effect

/zr execute every 10 seconds if lobby[round>=10] run addToActiveMobs[mob=HUSK,count=1]

Simple command-block branch

/zr execute if lobby[round>=20] run true

A conditional chain command block after this can use the boolean command result.

How config and DSL fit together

The YAML config defines persistent map objects and rules; the DSL reacts to runtime state and player interactions. The strongest examples are zones and doors:

# config.yml  doors:   platform_gate:     cost: 1000     zone: 3     regions:       - from: { world: world, x: 10, y: 64, z: 20 }         to:   { world: world, x: 12, y: 66, z: 20 }  zombieSpawnLocations:   - { world: world, x: 50.5, y: 64, z: 50.5 }   - { world: world, x: 80.5, y: 64, z: 50.5, zone: 3 }  round:   mobProportions:     - { mob: HUSK, probability: 70 }     - mob: ZOMBIE_PIGLIN       probability: 30       includeInRotationAfterZones: [3]  lobby:   enabledPowerups:     - MAX_AMMO     - type: FIRE_SALE       includeInRotationAfterZones: [3]

# command block / map logic /zr execute if block.interact within door[id=platform_gate] run unlockDoor[door=platform_gate]

Once the door is successfully unlocked, its configured zone can be opened. That same zone then affects which zombie spawn locations are valid, which configured mob types may enter the weighted rotation, and which zone-gated power-ups can enter their pool. This is the core pattern for building progressive ZombieRounds maps.

Commands

Reference notes

This page documents the configuration and DSL surface visible in ZombieRounds 2.1.21.11.31 source. Where a setting is omitted, Bukkit's configured default or the plugin's fallback behaviour applies. Enum values such as Bukkit materials, entity types and particles must be valid for the Minecraft/Paper version being used.