Phases and subphases

Health phases change the fight as the boss loses or gains HP. Subphases let you build a sequence of attacks and Recovery periods inside each health phase. You can also add roar interludes between them.

Health phases

Open Manage phases in the editor. You can add, remove, and reorder 1–16 health stages. The order in the file is the order used in the fight.

For each stage except the last, choose the HP percentage where the boss moves to the next one. Use 0–100%, going from highest to lowest in fight order. If you set 75%, the boss changes phases as soon as it reaches exactly 75%. The last stage covers whatever HP is left and doesn't need a cutoff.

Default phase	Health range
ANNOYED	Above 75%
AGITATED	Above 50%, up to 75%
ENRAGED	Above 25%, up to 50%
FURY	25% or less

You can give each phase its own movement speed, knockback resistance, follow range, scale, melee, Sonic Boom, targeting, glow color, Darkness, and phase-transition effects. New phases use the base settings until you override them. A phase scale of null inherits the top-level scale.

Adding a new final phase gives the previous final stage a cutoff halfway below the preceding cutoff. Other cutoffs stay unchanged. Reordering may require adjusting cutoffs before the editor accepts a Save.

Attack subphases

Open a phase, then Subphases. An Attack subphase starts with that phase's settings, falling back to the base settings where needed. You can override movement speed, knockback resistance, follow range, melee, Sonic Boom, and targeting.

Subphases don't have their own health thresholds, and you can't nest more children inside them. Health, scale, Darkness, glow, boss-bar identity, and phase-change effects stay under the health phase's control.

attacks_before_next accepts 1–1,000, with a default of 3. It counts completed attacks:

• Completed melee swings count, including blocked swings.
• Fired Sonic Booms count.
• Cancelled wind-ups and disabled/cooldown-rejected attempts do not count.

The attack doesn't have to hurt anyone to count toward the sequence. Voice lines work differently: those only roll after a successful hit.

Sequence order

Set subphase_order to:

• sequential: follow file order, then loop.
• random: shuffle the children, run each once, then reshuffle. With at least two children, the round boundary avoids an immediate repeat.

Missing or empty subphases keeps ordinary phase behavior. Entering a different health phase, reloading templates, or reloading the entity resets the attack sequence and roar cycle. Sequential starts at its first child; random starts with a fresh shuffle.

Recovery

Set a child to type: "recovery" for a pause. duration_ticks accepts 1–12,000, default 60 ticks, or 3 seconds at normal server speed.

Recovery pauses attacks and navigation. Native sensors, cooldown expiry, physics, and health-phase selection continue. A health-phase change or reload cancels the old pause. Your combat settings stay saved if you want to switch back to Attack, but they don't apply during Recovery.

This partial template shows an ordered attack/rest/attack pattern:

{
  "phases": {
    "annoyed": {
      "subphase_order": "sequential",
      "subphases": {
        "heavy": { "type": "attack", "attacks_before_next": 3 },
        "rest": { "type": "recovery", "duration_ticks": 60 },
        "light": { "type": "attack", "attacks_before_next": 5 }
      }
    }
  }
}

Merge these fields into the matching section of your existing template. This is a partial example, so don't use it to replace the whole configuration.

Roars between entries

Open Roars between inside the phase. Roars have their own list. With roar_between_subphases: true and a nonempty roars list, an interlude runs after every child, including Recovery and the loop boundary. The first child starts without a preceding roar.

The roar waits for attack recovery, pauses attacks, uses Minecraft's roughly 84-tick animation, plays its selected sound once, and starts the next child. Disable interludes or empty the roar list to skip them.

• Sequential order cycles the roar list independently: one repeats, two alternate, and a shorter list wraps.
• Random order chooses a roar independently at every transition. Repeated roars are allowed.
• Null sound fields inherit the phase's roar.sound, then base attacks.roar.sound.
• An empty filename uses the normal Warden roar.
• A custom filename with volume 0 gives a silent roar animation.

Place custom roar OGG files in the template's sounds/ folder. The normal event audio limits apply.

A heavy and light pattern

This partial template alternates two heavy swings and four light swings, with the same roar between them:

{
  "phases": {
    "annoyed": {
      "subphase_order": "sequential",
      "roar_between_subphases": true,
      "subphases": {
        "heavy": {
          "type": "attack",
          "attacks_before_next": 2,
          "melee": {
            "enabled": true,
            "damage": 60,
            "charge_time_ticks": 20,
            "recovery_time_ticks": 12,
            "cooldown_ticks": 60
          },
          "sonic_boom": { "enabled": false }
        },
        "light": {
          "type": "attack",
          "attacks_before_next": 4,
          "melee": {
            "enabled": true,
            "damage": 15,
            "charge_time_ticks": 3,
            "recovery_time_ticks": 4,
            "cooldown_ticks": 20
          },
          "sonic_boom": { "enabled": false }
        }
      },
      "roars": {
        "warning": {
          "sound": { "file": "roar.ogg", "volume": 1, "pitch": 1, "range": 32 }
        }
      }
    }
  }
}

For cooldown and in-flight attack behavior, continue to Combat and targeting.

Experimental registered actions

Stable 0.2.0 and beta.6 accept registered action IDs as a subphase's Type. The API remains experimental revision 1; older 0.1 jars lack it. See Addon API for scope and compatibility.

Core action ID	Behavior
clockwork_bosses:combat	Both phase-enabled native attacks.
clockwork_bosses:melee	Native melee only.
clockwork_bosses:sonic_boom	Native beam only; disallowed melee cannot block close-range beams.
clockwork_bosses:recovery	Timed movement/attack pause.
clockwork_bosses:roar	One native roar with optional sound.
clockwork_bosses:burrow	Dig, wait underground, emerge near the target, then advance.

Legacy attack and recovery types still accept their original root-level budget/duration fields. For namespaced actions, action_settings is optional: leave it out or use {} for the declared defaults. If present, it must be an object, not null, an array or a scalar. Missing/null declared scalar values use that action's defaults, not another action's settings. Returning complete advances the existing order and roar-interlude system; no new subphases are inserted into existing templates automatically.

Experimental burrow and emerge

Burrow pauses native attacks/navigation, starts a 40-tick digging pose, hides the boss below its saved surface, waits underground_ticks, then resolves the eligible target's latest position. An unavailable target falls back to an eligible arena player under the existing targeting policy; it does not force a switch away from a still-valid current target.

One bounded search checks up to eighty nearby floor candidates. It checks loaded chunks, scaled standing dimensions, arena/world-border limits, native walkable terrain, solid support, collision and liquids. With no eligible player, no safe spot or a vetoed replacement target, the boss emerges at its starting surface. It destroys no blocks and loads no chunks for this search.

underground_ticks accepts 1–12,000, default 60; this is the underground hold, not the total digging-plus-emergence time. depth accepts 1–32 blocks, default 5, and increases automatically for a scaled boss up to the 32-block cap.

The boss faces its accepted target and performs native emergence. Put a combat entry next to attack afterward; a configured recovery or roar next still runs as configured. Attack cooldowns and other mods' target-assignment vetoes remain relevant.

Radius arenas retain their saved surface anchor while the entity is underground, so burial does not temporarily drop membership, support or music. After relocation, that radius follows the new surface. Cleanup and save/restart recovery retain the latest committed surface and restore the original flags, rather than undoing a completed relocation.

This partial object shows burrow followed by ordinary combat without a roar interlude:

{
  "phases": {
    "annoyed": {
      "subphase_order": "sequential",
      "roar_between_subphases": false,
      "subphases": {
        "relocate": {
          "type": "clockwork_bosses:burrow",
          "action_settings": { "underground_ticks": 60, "depth": 5 }
        },
        "attack_target": {
          "type": "clockwork_bosses:combat",
          "action_settings": { "attacks_before_next": 3 }
        }
      }
    }
  }
}

Burrow is included through the experimental action catalog in stable 0.2.0 and beta.6. Keep terrain, scale, interruption, save/restart and moving-radius playtests tied to the exact installed build; old 0.1 results do not verify this action. See Compatibility and testing and the playtest checklist.