Configuration Reference

Configuration reference

Looking for a setting, its limits, or what it inherits? This page covers stable 0.2.0, with later beta fields labelled separately. Your generated template.json comments and the editor's field descriptions explain the fields available in the build you're actually running.

File format

Active templates live at:

config/clockwork-bosses/boss-templates/<template>/template.json

The file supports JSON with // comments through Gson. Strict JSON also works. Generated note blocks group explanations above each section. Saves preserve unknown values and regenerate comments, so hand-written comment wording is not retained exactly.

The JSON examples in this wiki are valid partial objects. Copy their fields into the named sections of your existing template. Don't replace the whole template with one of these examples.

Use Save for editor changes, then Reload saved to apply saved templates to loaded bosses. For external file edits, use /boss reload. Neither action loads a new jar.

Development source: shared definitions

The experimental schema foundation reuses the existing core defaults/help, client/server editor types and bounds, and API BossSetting declarations. It exports JSON Schema Draft 2020-12 with x-clockwork annotations for inheritance, override scopes, ordered collections, percentage display and action settings. No separate list of website limits is introduced. x-clockwork.numeric_input also exports the real decimal parser limits for declared edits; ordinary JSON Schema checks values rather than lexical input bounds.

Schema defaults describe creation/form values; importing a template must not automatically populate missing fields. Null phase overrides use base settings; Attack-child overrides use their parent. Null dormant-darkness fields inherit the first phase's compiled darkness. Unset phase darkness uses its legacy base fallback, not dormant darkness. Registered action settings use their own declared defaults rather than inheriting another action object.

Schema revision 2 adds x-clockwork.omitted rules separately from creation defaults. For example, omitted loot.source means table, while newly created templates explicitly choose entries. server_default gives no portable literal; keep that field absent when saving an imported file. Missing support sections remain disabled. Null subphase_order means sequential, null roar_between_subphases enables interludes when roars exist, and null loot disables template rewards while retaining vanilla drops.

visible_when shares the game editor's action/geometry selectors with tooling. Legacy attack counts, recovery duration and combat overrides appear only where used; registered actions use their declared action_settings. Hidden values remain stored. The core roar's file field accepts a lowercase OGG basename up to 68 characters, or blank/null for the native roar. Actual media/addons/registries/ world checks are explicitly listed in server_only_checks.

Spatial range fields export x-clockwork.automatic separately from creation defaults and legacy omission. Null inherited overrides remain null; missing imported fields stay missing on save. Automatic audio uses arena geometry, not activation geometry; music keeps its arena audience. See Sounds and music.

The schema handles portable types, ranges and structure. Server validation still checks cutoff order, inherited attack budgets, reward quantity relationships, geometry, addon availability, registry IDs and media contents. These remaining checks are listed in x-clockwork.runtime_checks. A first experimental browser editor now uses these definitions; it does not replace server validation. This schema and automatic sound distance are included in stable 0.2.0 and beta.6. Installation and connected schema availability are separate. See Templates and presets.

Settings map

Area	Documented location or editor route	Guide
Spawn	spawn; /boss setspawn <template>	Templates and presets
Base attacks	attacks.melee, attacks.sonic_boom	Combat and targeting
Targeting	targeting; phase/Attack-child overrides	Combat and targeting
Health stages	phases; Manage phases	Phases and subphases
Subphase pattern	Phase subphases, subphase_order, roars, roar_between_subphases	Phases and subphases
Activation	activation	Arenas and activation
Arena	boss_bar.visibility_area	Arenas and activation
Beacon effects	boss_bar.area_effects	Player support
Fight health	boss_bar.player_health; Arena effects	Player support
Reusable potion	boss_bar.reusable_potion; Arena effects → Reusable potion	Player support
Appearance	skin; Skin preview / eyes	Skins and face controls
Native mob volume	sounds.mob_volume	Sounds and music
Event sounds	sounds.spawn, sounds.phase_change, sounds.death	Sounds and music
Voice and music	Root voice_lines and music	Sounds and music
Darkness	dormant_darkness; phases.<phase>.darkness	Darkness and visual effects
Glow	warden_effects.color; phase overrides	Darkness and visual effects
Rewards	Root loot; Loot → Entry editor or Datapack table	Loot

Inheritance

The general combat chain is Attack child → health phase → base settings. Children can override movement speed, knockback resistance, follow range, melee, Sonic Boom, and targeting. Health, scale, Darkness, glow, boss-bar identity, and phase-transition effects remain health-phase concerns.

Value	Meaning
Phase scale: null	Use the base scale.
Missing phase attack override	Use the base attack setting.
Null/missing phase targeting field	Use its base value.
Null/missing phase-change sound field	Use the shared phase-change sound field.
Phase-change sound file: ""	Mute that transition.
Explicit phase-change filename	Use that choice even if the file is missing; do not fall back automatically.
Null roar sound field	Inherit phase roar.sound, then base attacks.roar.sound.
Event/voice/custom-roar range: 0	Automatic arena/boss-bar radius or inclusive 3D box diagonal, capped at 512; no usable arena falls back to 32.
Omitted/null legacy base audio range	Keep 32 blocks; newly created files explicitly choose 0.
Registered core roar action_settings.range omitted/null	Use its declared Auto default 0.
Empty roar filename	Use the normal Warden roar.
Empty music filename	Disable encounter music.

Missing health/potion support sections in older files stay disabled. Missing loot stays disabled. Opening and saving an old file doesn't necessarily enable new features.

Fresh default templates have the Beacon effects master switch off, with individual level-I effect entries enabled. The six player-count presets have the master switch on with only Regeneration I enabled. Both enable the 100 HP fight-health floor, first-entry healing, and the default reusable potion.

Numeric limits and units

Setting	Documented range or default
Boss maximum health	1–1,000,000 HP
Scale	0.25–4.0; 1.0 is normal size
Health-phase count	1–16
Non-final phase cutoff	0–100%, descending; equality advances
attacks_before_next	1–1,000; default 3
Recovery duration_ticks	1–12,000; default 60
Melee charge	0–12,000 ticks; default 0
Melee recovery	0–12,000 ticks; default 4
Sonic Boom charge	0–1,000,000 ticks; bundled base default 40; 0 fires immediately
Sonic Boom recovery	0–12,000 ticks; default 26
Automatic follow_range	0 selects arena sizing, capped at 256 blocks; unset arena falls back to 24
Target switch chance	JSON 0–1 / GUI 0–100%; default 0.5 / 50%
min_target_ticks	Default 60 ticks; 0 disables the time gate
Target min_attacks / max_attacks	Defaults 1 / 4; max must be at least min
Arena/activation radius	1–256 blocks, 3D
Selection box	Maximum 256 blocks per axis
Beacon-effect level	1–5, using human-readable levels
Player minimum max health	1–1,000 HP; default 100
Potion heal_hp	0–1,000 HP; default 20
Potion cooldown_seconds	0.05–600 seconds; default 15
Potion hunger_restored / saturation_restored	0–20 each; hunger must be an integer; defaults 20 / 20
Loot entry count / key length	Maximum 32 entries; keys 1–48 lowercase letters, digits, underscores, or hyphens
Loot item ID	Registered non-air item ID, maximum 256 characters
Loot min_count / max_count	Inclusive integer quantities 1–64; min must not exceed max
Loot chance	File 0–1 / GUI 0–100%; independent rolls
Native mob volume	0–1; default 0.25
Voice chance	0–1; default 0.25
Voice volume / pitch / range	0–4 / 0.5–2 / 0–512; new defaults 1 / 1 / 0 (automatic)
Custom-sound range	0 uses arena radius/inclusive box diagonal; positive is manual, maximum 512; legacy omitted base value 32
Music volume / fade	0–4 / 0–10 seconds; default fade 2 seconds
Eye Scale X/Y	0.5–4, rounded to 1–8 atlas pixels; default 1 gives 2×2
Eye coordinates	Integers 0–15 in the editor; rendered X/Y clamp to 16 minus current width/height
Eyebrow coordinates	Integers 0–12; fixed 4×4 masks
Phase particle count	Capped at 128; default 128 at size 0.65

Ticks use game time. At normal server speed, 20 ticks is one second. Seconds-based audio limits and file byte limits are listed on Sounds and music.

The target time gate can postpone forced rotation beyond max_attacks. Minimum native melee scheduling can also prevent a small configured cooldown from producing equally fast attacks. A value can be within the allowed range without making attacks happen at exactly that interval.

Naming and media limits

• Template identifiers: lowercase ASCII letters, digits, dots, underscores, or hyphens; no spaces.
• Media references: single lowercase filenames, no directory paths.
• Custom skin: PNG, exactly 128×128, at most 512 KiB.
• Event/voice sound: OGG Vorbis, at most 1 MiB minus 1 KiB and 30 seconds.
• Music: OGG Vorbis, at most 8 MiB minus 1 KiB and 10 minutes.
• Voice discovery: up to 64 valid files in the direct voice-lines/ folder.

Use regular files inside the template's own folder. Linked template/media parents and linked files are rejected.

Experimental action configuration

Stable 0.2.0 and beta.6 resolve a subphase's type through the registered action catalog. An addon introduces the mechanic; the template selects its ID and supplies its declared action_settings values. See API reference and Lightning addon walkthrough.

Settings support numbers, booleans and bounded text/options. For registered 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. Within that object, missing or null declared scalar fields use their defaults. Native combat inheritance stays separate; a custom action does not inherit another action's settings.

Unknown setting keys survive saves but are not exposed as arbitrary controls or execution settings. Missing action IDs fail validation. Client catalog metadata is virtual and is not written into templates. Switching Type replaces action_settings with the new mechanic's defaults.

Existing legacy attack and recovery types keep their original root-level attacks_before_next and duration_ticks fields. For namespaced core IDs, those values belong inside action_settings. Generated comments and the editor show each registered field's description, default and limits.

Development preview: encounter PvP protection (0.3.0-beta.1)

Partial example:

{
  "boss_bar": {
    "pvp_protection": { "enabled": true }
  }
}

This boolean is encounter-wide, not a phase/subphase override. Missing/null sections or missing/null enabled mean disabled; new files explicitly use true. The schema exports creation true separately from omitted false. String values such as "true" are rejected by editors; use a JSON boolean. /boss reload applies edits to loaded bosses. It uses boss_bar.visibility_area, not the activation trigger. See Player support.

Development source: eyebrow expressions and combat events

The later source adds fields under skin.glowing_eyebrows. They are packaged in local checkpoint 0.3.0-beta.6, not deployed. See Skins and face controls for the editor workflow, example and current validation limits.

• expression: angry (default), neutral, curious or sad.
• left_rotation, right_rotation: whole degrees -45–45, default 0; positive clockwise.
• events.enabled: false by default; missing/false preserves the static face.
• events.melee, sonic_boom, roar, hurt, target_change: each holds expression (inherit, a named shape, or random) and nullable left/right rotation overrides. Inherit always means the base shape; null angles use the base angles, not a previous event.
• events.hit_duration_ticks / target_duration_ticks: 1–12000, default 20.
• events.hit_cooldown_ticks / target_cooldown_ticks: 0–12000, default 20.
• events.random_between_attacks: false by default; when enabled, resting expressions roll once after a completed melee swing/sonic beam.
• events.random_pool: angry/neutral/curious/sad booleans, default true; all false uses base.

Hit overrides attack/roar, then new target, then rest. Expiry reuses the ten-tick watcher and may add up to nine game ticks. These fields affect glow appearance only. All seven bundled presets include disabled event defaults; existing omitted settings keep the legacy look. Native fixture/editor/atlas checks passed in beta.6; real multiplayer and deployment remain pending. Hosted beta does not yet declare this jar compatible. See Compatibility and testing.