Templates and Presets

Templates and presets

A template holds the settings for one of your named encounters. A preset is a starting point you can copy to make new templates. You can spawn multiple bosses from the same template without setting everything up again, and each runs its own fight.

Folder layout

Each template owns its configuration and media:

config/clockwork-bosses/
  boss-templates/
    my_boss/
      template.json
      skins/
      sounds/
        voice-lines/
  boss-presets/
    2_players/
      template.json
      skins/
      sounds/
        voice-lines/

Only named folders containing template.json under boss-templates/ are active templates. Presets live separately, so you won't see them in /boss template list or active-template autocomplete. Use their own editor tab and preset-name autocomplete instead.

Names use lowercase ASCII letters, digits, dots, underscores, or hyphens. No spaces or capitals.

Each template has its own media. Two templates can both have a roar.ogg and use completely different sounds; their cached files stay separate too. Bosses spawned from the same template share those files, but each boss tracks its own voice playback timing.

Create or copy

/boss create new my_boss
/boss create preset 2_players my_boss
/boss create preset boss-sounds-example my_boss

Choose one of these commands to create a new template, and use a new destination name for each copy.

You can also copy an entire preset folder into boss-templates/, then run /boss reload or restart. Copy the folder, not just its JSON, when it contains media. Rename the destination to another valid template name if needed.

Player-count presets

Preset	Intended players	Boss HP
1_player	1	1,000
2_players	2	1,400
3_players	3	1,800
4_players	4	2,200
5_players	5	2,600
6_players	6	3,000

These presets use scale 2.0 and include Regeneration I arena support plus their skin and phase tuning. The six player-count presets have the Beacon effects master switch on, with only Regeneration I enabled. Fresh default templates have that master switch off, with the individual level-I effect entries enabled for you to choose from. Both enable the 100 HP fight-health floor, first-entry healing, and the reusable potion described in Player support.

Replace the supplied test-arena coordinates. Set the spawn, activation region, and arena for your world before using the encounter. The player-count presets have empty event filenames and empty media folders.

The boss-sounds-example preset includes five sample event clips and four attack voice clips. Copy it as a template, or copy the clips you want into another template's own sounds/ folders. No encounter music track is bundled.

What startup preserves

Restarting keeps your existing preset files. Missing preset documents are recreated in boss-presets/; this does not create or replace an active template. Editing a preset affects future copies only.

Preset copying validates configuration and media before publishing the new folder. The copy job is bounded to 96 files and 32 MiB, with one pending job.

File editing and inheritance

Generated template.json files allow // comments. Existing strict JSON files still work. Saving regenerates the explanatory comments and keeps unknown setting values. It won't preserve your custom comment wording exactly.

Many phase and subphase overrides use null or omission to inherit. An empty string can mean something different:

• Phase scale: null inherits the base scale.
• A phase-change sound's file: null inherits the shared sound.
• A phase-change sound's file: "" mutes that transition.
• An empty roar sound filename uses the normal Warden roar.

See Configuration reference before using a blanket find-and-replace on inherited fields.

Development source: format and schema

The later template tooling foundation adds format_version: 1 to new/saved files and bundled presets. A missing version means an older revision-1 template; reading it leaves the file alone. Unsupported explicit versions and duplicate JSON member names are rejected. Existing installed presets are preserved. This format/schema foundation is included in stable 0.2.0 and beta.6. The older 0.1-client-optional.1 jar predates it.

An operator running a newly built jar can export the shared setting definitions:

/boss template schema

The result is config/clockwork-bosses/template-schema.json, including installed addon actions. gradlew exportTemplateSchema produces a core-only schema at build/template-schema.json without launching Minecraft. The first experimental Template Workshop now reads that JSON without a running server. It is a separate browser editor, not a new screen or feature inside the previously supplied jar.

Schema revision 2 keeps template format revision 1. Creation default values are separate from x-clockwork.omitted runtime rules: new loot.source is entries, but an absent source means table. Missing health/potion sections grant nothing. A server_default annotation means preserve omission rather than guessing a literal from the creation value. visible_when tells an editor which action/geometry controls apply; hiding a value never deletes it. Null sequence-order/roar controls and null loot match supported runtime behavior. The core roar action uses the same lowercase OGG basename rules as event sounds.

Import/export preserves unknown addon fields, arrays, explicit nulls and number values. Missing addon actions remain in the file but cannot run without their addon. Keep member order: it controls phases/subphases/roars. Do not reconstruct files from only the controls an editor recognizes. Browser tooling needs a lossless number parser and ordered member lists; ordinary JavaScript numbers can round large values, and integer-looking object keys can be reordered.

Only root documentation/editor metadata is omitted during save: _documentation, _action_catalog, _action_types, _phase_order, _subphase_orders, _roar_orders and _loot_entry_order. Identical names inside addon objects are preserved. Comments are regenerated. Intentional entry deletion or action-type changes can remove the selected entry or replace that action's settings.

See Configuration reference and TEMPLATE_SCHEMA.md in the source repository for the format/validation boundary.

Experimental browser editor

The Workshop has two workflows. Standalone editing reads local JSON/JSON-with-comments and downloads plain JSON without a server login. Connected editing uses a private Minecraft-issued login to work with server-owned drafts, templates and supported media.

1. Choose a new template or bundled preset, or Import an existing file.
2. Edit settings and manage phases/subphases in the browser.
3. For standalone work, Download JSON, copy it into the intended template folder as template.json, then run /boss reload.
4. For connected work, wait for Save draft, then Publish draft, then run /boss reload to apply it to already spawned bosses. Publishing reads the saved draft, not unsaved browser fields.

Standalone edits stay in the tab until downloaded. Downloads remove handwritten comments/whitespace while preserving unknown addon values, ordered entries, explicit nulls, unedited number tokens and imported omissions. Local preview files are not uploaded server media.

Load addon schema accepts the server's /boss template schema export. Connected editing uses that server's live schema. Neither route runs addon Java in the browser; server validation remains authoritative.

The current Workshop supports appearance previews, skin fetching, authenticated sound lists/playback and draft OGG uploads where the connected server provides the capability. Draft uploads do not alter active encounter files until publication. Built-in preset sources remain read-only; create a draft/copy for changes.

See Workshop for login, media limits and publication, Workshop troubleshooting for conflicts/recovery, and Versions and release status for channel support. The locally tested beta.6 face controls are separate from the last verified hosted beta.

Spawn settings

Spawn position belongs to the template, not a global spawn file. /boss setspawn <template> stores the position and dimension. A missing spawn object or spawn.set: false makes /boss spawn use the command source position.

Delete a template

/boss template delete my_boss

Remove encounter instances first, including instances in unloaded chunks. The command refuses deletion while loaded bosses use that template. It removes the active template from the list and retains the whole folder under config/clockwork-bosses/deleted-templates/.

You can't delete presets with this command. See Commands for boss removal and the rest of the command list.

Boss templates and test presets

A boss preset is a reusable starting point for an encounter. An Observatory test preset describes how to test one: players, loadouts, bot decisions, repetitions, limits and expected outcomes. Keep those definitions separate. The shared test-preset editors are unfinished development work; see Boss Observatory and Test Mod.