Workshop

Optional hosted workshop

Clockwork Bosses 0.2.0 includes the Workshop connection and the sound uploads from companion version 0.3.7. Install one Clockwork Bosses jar with Fabric API. Players can use the same jar for the in-game editor and visuals, or play without it using the vanilla fallback. The Workshop connection only starts on dedicated servers. You don't need to host a website or open an inbound HTTP port.

The editor stays at https://workshop.clockworkboss.com. The mod connects through an outbound TLS WebSocket. Failed connections pause browser access while fights continue. Publishing the mod does not publish the separate Cloudflare website.

Upgrade and settings

1. Stop Minecraft; back up both old jars outside mods/.
2. Remove the old core and companion jars, then install the merged core jar.
3. Restart the server yourself. Open a new workshop login after restart.

Fabric rejects an old clockwork_bosses_web companion before either initializer runs. The adapter has a matching explicit upgrade guard. Keep its config/data.

On its configuration worker, startup copies an existing config/clockwork-bosses-web.properties into config/clockwork-bosses/workshop.properties byte for byte. Comments, unknown properties, flags and secrets survive. The original remains; an existing canonical file wins. Invalid, oversized, linked or concurrently changed source files are rejected without replacing settings. Reload does not resurrect a deleted canonical file. Fresh installations default both access flags to false.

Identity, drafts, draft media, backups and publication journals remain under config/clockwork-bosses-web/. Keeping those paths preserves the relay address and recoverable publications. Templates, presets and active media remain under config/clockwork-bosses/. No media is bulk-moved or reset. Browser sessions and one-use links are memory-only; restart invalidates them as before.

To enable access, edit the canonical server settings:

enabled=true
template_access_enabled=true
relay_url=https://workshop.clockworkboss.com

Commands and permissions

Command	Purpose
/boss workshop open	Private one-use login link; expires after two minutes.
/boss workshop logout	Revoke your links/sessions, including during an outage.
/boss workshop reload	Apply workshop settings asynchronously.

Run Open in game. Minecraft's native owner permission, normally operator level four, and online-mode are required. Boss permission nodes do not grant workshop ownership. Console can reload, but cannot issue a player login. Hosts need outbound TLS on port 443; no extra inbound web port is needed.

The old /bossworkshop open, logout and reload commands are temporary aliases with identical handlers/permissions. /boss reload applies gameplay settings and media, separately from the connection settings above.

Unchanged settings keep valid sessions. Disabling access or changing origin revokes them. Invalid reloads retain the previous settings. Transient reconnects retain sessions but never replay an interrupted save/upload/publish; review the draft before retrying a failed mutation. Logout revokes even while disconnected.

Drafts and media

Publication and autocomplete — prepared 0.3.0-beta.5

Save draft keeps a draft on the server. Publish draft commits its validated template/media and automatically updates the game's template autocomplete list. Future spawns read the published settings from disk.

Publish uses the saved server draft, not unsaved browser fields. Wait for a successful Save draft, then a successful Publish draft, before reloading. An Active template changed error means the requested operation was rejected. In-game spawn/area commands can change the active document after loading a draft. Download JSON to keep a backup of browser edits, load and review the Active version under Saved templates, reapply the desired fields, then save/publish again. This preserves newer spawn/arena coordinates; importing an entire older download can undo those changes. Do not bypass revision protection to force a stale save.

Run /boss reload to apply these changes to bosses that are already spawned. Publishing preserves running encounters' current settings. /boss workshop reload reloads the workshop connection settings; it does not reload boss settings.

The existing web file worker refreshes one owned template's name in an immutable suggestion snapshot after the publication commits. It adds no tick scan and never reloads a running boss. If refreshing suggestions fails, publication is still saved successfully; run /boss reload to refresh the list manually. Older mod versions, including beta.4, require that manual reload for autocomplete.

Automatic template-list refresh was introduced in beta.5 and is included in the locally packaged/tested beta.6 checkpoint. The Minecraft artifact is not deployed. Stable 0.2.0 and older beta builds require manual /boss reload to refresh autocomplete. Beta website rc.3 excluded beta.6 at the October 13 checkpoint; deployed rc.4 now explicitly supports it. Website release and Minecraft jar installation are separate steps.

Save creates a complete immutable JSON/media draft from its selected preset, active template or prior draft. Publish rechecks draft/active revisions, validates with the live core/addon schema, backs up replaced files, then commits. Unknown addon properties and precise number tokens survive. Native editor saves and web publication share a worker-only lock to reject stale edits.

Uploads target drafts only. Event/voice files accept path-free, lowercase OGG Vorbis names, at most 1 MiB minus 1 KiB / 30 seconds. Music accepts at most 8 MiB minus 1 KiB / 10 minutes. Use mono event/voice clips for positional playback; music can be mono or stereo. Full bounded decode, CRC, duration and filename checks validate contents. Confirmed replacements get backups; publication journals recover interrupted writes. The hosted UI also needs the matching upload capability; a jar upgrade does not update that UI.

Sound uploads are included in merged Clockwork Bosses; no separate companion is required. Upload availability comes from the running server opened by your login link. If the page reports missing upload support, install Clockwork Bosses 0.2.0-beta.4 or newer and restart that Minecraft server. Live and test workshop links access separate server installations.

The relay refreshes older connection metadata automatically when an upload first needs a capability added by a website update. This reconnect leaves boss fights running. Review the saved draft before retrying any interrupted save or upload; the relay never replays those operations automatically. Explicitly unsupported servers remain connected and receive the normal upgrade message.

Privacy, ownership and limits

Keep clockwork-bosses-web/relay-server.key private and backed up. Losing it changes the server address; copying it to another running server lets that server replace the connection. Login secrets stay in private chat fragments and bounded memory, never logs. API operations and commits recheck current native ownership. Cookies are scoped, secure and HttpOnly; mutations require CSRF.

File guards reject linked ancestors, including Windows junctions. OS permissions must still exclude untrusted local writers: addons/processes with server privileges are not sandboxed. Queues, deadlines and retries are bounded; shutdown cancels requests, streams, workers and timers. No workshop tick watcher exists. Minecraft state stays on its thread; blocking file/network work stays on workers.

See Performance audit for exact limits and Preflight for test evidence and remaining playtest limits. Automated codec/relay checks do not replace rendered multiplayer tests or a live-server TPS profile.

Beta preview: explicit Workshop channels (0.3.0-beta.4)

Explicit release channels — beta preview 0.3.0-beta.4

workshop_build_channel in gradle.properties is packaged into Fabric metadata. Allowed values are stable, beta, development. This checkout explicitly uses beta. Version spelling, prerelease suffixes and Git branches never choose a host. The immutable released 0.2.0 jar retains its existing stable behavior and protocol; it was not rebuilt or modified.

Channel	Browser and outbound relay origin
stable	https://workshop.clockworkboss.com
beta	https://beta.clockworkboss.com
development	https://dev.clockworkboss.com

Selection order in workshop.properties:

1. Nonempty testing_channel deliberately selects one of those channels.
2. Otherwise an existing explicit relay_url stays pinned to its exact origin.
3. Otherwise use_build_channel=true uses the packaged channel.
4. Legacy files missing both fields retain the old stable default.

New default files include use_build_channel=true, blank testing_channel, and disabled access flags. They do not create an identity or open a connection until enabled. Existing files are not rewritten. Browser links, websocket and metadata reads use one normalized exact origin; no host fallback or release routing negotiation exists. Invalid reloads retain previous settings with an error; a valid selection with unavailable metadata stays on that selected host and pauses writes.

Credential/trust behavior: first upgrade preserves the old key and records its currently configured origin in the non-secret relay-server.origin beside it. That adoption trusts the owner's existing explicit relay_url. Later attempts to reuse that identity on another origin are refused. Testing overrides and build-selected non-stable hosts generate independent keys under clockwork-bosses-web/relay-identities/<origin-hash>/; they never copy, derive from, rotate or migrate the production key. Changing the connection revokes old links/sessions. Use a separate online-mode test instance with separate configs and worlds: different cloud namespaces do not separate a shared filesystem. No actual server credentials/settings were touched by this development task.

Example for an isolated test instance, applied manually with /boss workshop reload:

enabled=true
template_access_enabled=true
use_build_channel=true
testing_channel=beta

Website compatibility

The new /api/status adds exact installed mod_version, packaged mod_channel, selected workshop_channel (including custom for self-hosted URLs), workshop_origin and workshop_compatibility. The latter reports state, writable, reason, web_version and build. Website metadata channel names production/beta/dev map to mod names stable/beta/development. An intentional override may make the mod and selected workshop channels differ.

Before server saves, copies/renames, publishing or sound uploads, the mod checks the selected host's credential-free /build-info.json. The installed version must appear exactly in compatible_mod_versions; all required_capabilities must be available. Website and mod patch versions are independent: website 0.2.1 can support mod 0.2.0. Unknown requirements fail closed. Existing feature flags/codec checks, permission, CSRF, revision and commit guards stay in place. Checks are cached for at most 30 seconds, bounded to 16 KiB/five seconds, run on existing workers and never follow redirects. No tick watcher is added.

A stable or existing custom relay returning 404 for metadata retains legacy protocol v1 with an unverified diagnostic. Missing/malformed/timed-out metadata on beta/dev never becomes legacy access; malformed-present stable metadata also pauses writes. Login/logout and authenticated downloads/previews remain usable for recovery. The prepared browser SDK also revalidates before writes, pauses autosave and checks separately before raw XHR uploads. Local Import/Download JSON and local recovery remain available.

Historical beta deployment (October 13, 2026): website 0.3.0-rc.3 (build c68627b1) explicitly supports mod versions 0.3.0-beta.4, 0.3.0-beta.3, 0.2.0. Required capabilities are empty; optional features retain their capability gates. Website/mod version equality is not required. Owner authentication, CSRF, exact origins, session isolation, schema validation and revision checks still control publication.

Beta includes the same saved-draft publication safeguards as live Workshop 0.2.2, while retaining its newer interface, schema, presets and compatibility checks. A failed or uncertain save clears approval to publish an older draft. Editing fields while the confirmation is open also requires saving again. Conflict messages explain how to download browser edits, review the Active template, reapply changes, and save and publish successfully.

Hosted files, release metadata and safeguard presence were verified. Real authenticated Minecraft-to-Workshop editing and publishing still need playtesting. This website update requires no new mod jar or server restart.

Use a fresh /boss workshop open link on the deliberately selected beta connection. An existing production URL remains pinned unless the owner sets testing_channel=beta and runs /boss workshop reload; that override uses a separate identity. Server settings and credentials were not changed for this publication. During this beta-only update, live Workshop 0.2.2 and dev kept their existing releases and public file hashes. Earlier frozen releases are retained. Actual-account/cloud relay end-to-end playtesting remains to be done.

Deployed beta texture restoration: 0.3.0-rc.5

The October 14 publisher receipt records beta website 0.3.0-rc.5, build 0ce07f501d56db72d563563117731c0152ccb7071daa9c6d7d9d2a99c6f581b6. It restores four original Warden PNGs without changing public rc.4 code/assets. Exact support remains beta.6, beta.5, beta.4, beta.3 and 0.2.0, with required capabilities unchanged.

The publisher verified all 29 hosted assets, HTTP 200 and PNG CRC/decompression checks for the four images, and a fresh browser textured vanilla preview. Existing exact-jar HTTP and SDK/Java/workerd workflows passed with 0.2.0 and beta.6; the beta.6 Java HTTPS metadata reader reports writable=true. This is publisher-reported website/API evidence, not a new player-login or combat test.

The PNGs live in private local inputs and the ignored release capture, not tracked public source. After preparing public source for a future beta upload, the publisher must reapply that private overlay. Do not add the images or texture-containing capture to the wiki or GitHub. Production stays reported at 0.2.2 with its 27 asset hashes unchanged, and no core/server restart occurred.

Deployed beta website: 0.3.0-rc.4

At the earlier October 14 checkpoint, beta metadata was checked for 0.3.0-rc.4. This historical release explicitly supports core 0.3.0-beta.6, 0.3.0-beta.5, 0.3.0-beta.4, 0.3.0-beta.3 and 0.2.0, with no required capabilities. Its build is a2a517b5843f903a3f2d79c046939f5eded9e866d282277817e3855c00d4735a.

The release receipt verifies all 25 hosted asset hashes, a schema matching the exact beta.6 jar export and that jar's Java HTTPS compatibility check returning writable=true. The face controls are now deployed to beta. Exact origins, ownership, schema, capability, CSRF and revision checks still apply.

The receipt records 41 editor and 40 relay checks and disposable real-HTTPS API/relay/SDK runs, including one-use link exchange, validated uploads, saved-draft publication, cross-server isolation, permission denial and disconnect recovery. No existing Minecraft server was touched and no jar was installed or restarted. A fresh licensed Minecraft login, real multiplayer/runtime checks and real speaker output remain separate.

Production remains reported unchanged at website 0.2.2 in that receipt; this wiki update did not independently refetch it. Website deployment does not deploy the beta.6 Minecraft artifact or make Observatory acceptance-ready.

Local beta.6 and recovery

The canonical local Workshop source includes the new face controls and passed 68 regression checks plus a real browser Import/Download round trip against the beta.6 schema. Its authenticated Save/Publish checks use isolated fixtures. Those earlier fixtures did not establish hosted support. The separately verified rc.4 website release above now declares beta.6 support and adds disposable HTTPS relay evidence; real-player checks remain separate.

At the October 13 hosted checkpoint, production website 0.2.2 and beta website 0.3.0-rc.3 had the saved-draft publication safeguards, but beta excluded mod beta.6 and lacked its new face controls. That gap was resolved by the separately deployed rc.4 website release. Installing a core jar alone still cannot update the site.

Use Versions and release status for the recorded combinations and Workshop troubleshooting for unsupported versions, stale drafts, failed mutations and reconnection.