Compatibility and Testing

Compatibility and testing

For a full in-game session, use the playtest checklist. It provides commands, repeatable steps and expected results for core features, multiplayer, permissions, optional clients, the example addon and cleanup. Record Pass, Fail and Not run separately; recorded test evidence below is distinct from that plan.

The recorded 0.1 release targets Minecraft 26.3, Fabric Loader 0.19.5, and Fabric API 0.161.0+26.3. That released jar needs the same Clockwork Bosses version on the server and every connecting client. The later source change below adds optional client support.

Release 0.2.0 — 2026-10-12

• Full Java 25 offline build, 5,216 core audit assertions, file-worker checks and all thirteen workshop suites pass. Both JSON Schema exports validate, with 14 accepted / 11 rejected fixtures and 642 portable-contract assertions.
• All 40 native Minecraft 26.3 GameTests pass without and with Lithium 0.26.2. New cases preserve melee wind-up during movement, hit once at its original deadline, reject escaped/obstructed impacts and cancel lost targets.
• The exact packaged jar passes disabled-workshop and unreachable-relay boots, native commands/fight lifecycle, byte-preserving migration and clean shutdown. Loader rejects an old companion before initialization.
• Native client checks pass 2,700 model comparisons and 65,536 emissive pixels with Sodium/Lithium, EMF 3.3.8 / ETF 7.2.4 and EMF 3.3.11 / ETF 7.2.5. Before correction, the tint-mask regression failed on an opaque body pixel; the tendril mask now covers only its native UV regions.

These are scripted native positions and loaded model/mask checks, not a rendered multiplayer chase or screenshot. Confirm the reported whole-skin flash in the actual encounter. Mixed-client latency, full live-pack fights, TPS and long-term heap checks remain manual. Earlier beta relay/frontend tests remain separate. No live server or installed client was modified or restarted for these checks.

Development source: potion death and grave recovery

Recorded on 2026-10-11: the prior source reproduced the reported problem with Universal Graves 3.13.0+26.3, which captured a marked fight bottle before Fabric's AFTER_DEATH callback. The new cleanup runs before native death loot.

Common/client compilation and 5,013 offline assertions passed. All 33 native Minecraft GameTests passed both without third-party mods and with the isolated supplied server pack, followed by normal shutdown. A narrower run with the exact supplied Graves, Lithium and Polymer jars also passed and shut down. The grave contained the personal offhand and ordinary potion, and no fight bottle. Native respawn and grave recovery restored those items exactly once after /boss remove. Additional cases cover keepInventory, a Fabric death veto, totem survival and an older saved copy being removed on attempted use.

Early runs stalled at shutdown after passing assertions because the test used an occupied grave position as its respawn checkpoint and fell back to world spawn. A separate, asserted checkpoint in the loaded test area fixed the fixture; the gameplay cleanup code did not need a chunk-ticket workaround. The test's embedded players acknowledge 26.3 world loading before fatal damage; without that, the server rejects damage and would not verify death handling.

Existing service/Discord exclusions from the supplied-pack tests still apply. This does not test every grave mod or real client latency/packet decoding. No jar was packaged/deployed and no installed files or live worlds were edited.

Development source: removal and schema review

Recorded on 2026-10-11 after the review fixes: common/client compilation, 5,013 offline assertions including 628 template-contract checks, and independent schema validation passed. Both schemas were valid; 14 valid fixtures were accepted and 11 invalid fixtures rejected, including the reported null/omission/roar filename cases. All 29 native Minecraft GameTests passed in an isolated development server. Potion tests cover the actual remove command, offhand restoration, inventory/cursor copies, orphan cleanup, overlap, and authoritative full inventory packet delivery.

Two older Sonic Boom tests were updated to check the API's already implemented interruption contract: phase changes/reloads cancel pending action damage, and a replacement charge gets its complete wind-up. No combat implementation changed in this test correction. The ordinary offhand removal test passed before the cleanup change; the reported real client's exact cause remains unconfirmed. Retest that display after packaging. No jar was packaged/deployed, no live world was edited, and these checks do not verify a real client, high-latency network, the server modpack, browser forms or the live schema-export command.

Development source: template schema foundation

Recorded on 2026-10-11: common/client compilation and 4,947 offline assertions passed, including 562 template-contract checks. Tests exercise every bundled preset, both production writers, version/duplicate rejection, UTF-8/nesting limits, unknown addon data, large numeric tokens, explicit nulls, nested metadata-like keys and encounter order. An isolated loader proved the portable codec runs with only the JDK, Gson and its decimal helper, with Minecraft/Fabric absent.

An independent Draft 2020-12 validator accepted both exported schemas, all seven presets, the default document and a sample addon; six invalid fixtures were rejected. The standalone export launches no Minecraft process. These results do not verify browser behavior, the live /boss template schema command or new GUI interactions. No jar was packaged/deployed for this work; 0.1-client-optional.1 predates it. The website was still future work during those checks; they are not browser test evidence. A later first web editor is described in Templates and presets.

Development source: optional client support

The latest server source adapts native Warden tracking for players without Clockwork Bosses. Install a newly built server jar to use it; previously released or installed 0.1 jars do not contain this change. Players who install the core client must still match the server build. The presence check reads Fabric's negotiated core editor channel; it grants no permissions and does not verify the jar version.

Feature	Matching client mod	Without the client mod
Server attacks, targeting, phases and subphases	Full behavior	Same server behavior
Native boss bar, particles, scale, rewards and player support	Available	Available
Player/custom skin, glow, eyes and phase flash	Available	Vanilla Warden appearance
Custom OGG events, voice lines and music	Available	No custom file audio
Editor and enhanced selector feedback	Available to operators	No editor; use commands/files
Custom melee/Sonic animation timing	Synchronized visuals	Native timing may differ from damage

Server-played vanilla sounds keep their configured volume. Client-local heartbeat volume requires the mod. An unmodded client retains its native max-health limits for local entity display; server health and boss-bar percentage remain authoritative.

How it works: the first tracking snapshot and later dirty updates remove only Clockwork Bosses' twelve visual metadata fields for clients without it. Later Warden fields from other mods keep their serializers and values, with IDs adjusted for the removed slots. Matching modded clients receive the original data. Ordinary Wardens use the same adapter because other-mod field IDs can be shifted there too; unrelated entities and attribute/movement packets keep their native path. Other required mods must still have compatible client/server layouts. Custom skin/sound/music channels already check whether each recipient supports them.

There is no additional watcher, presence map or handshake timer. The adapter uses Minecraft 26.3's existing pairing and filtered tracking broadcasts. It covers this core's Warden fields, not an addon's custom registries or direct packet formats. Native-only addons such as the lightning example can operate without a client addon or core; addons with new entities, items, renderers or networking may need installation on clients.

Status: common/client compilation passed on 2026-10-11. The development test jar clockwork_bosses-0.1-client-optional.1.jar is now packaged, including experimental API revision 1 and its safety updates. No tests, game launch or deployment were performed for this change. The previous release artifact remains separate; the new test jar is not a published release. Before production use, check one matching client and one without Clockwork Bosses tracking the same ordinary Warden and boss; every phase; late join/tracking; reconnect/dimension changes; high boss HP; support/rewards; full media on the modded client; and other-mod Warden fields with the intended pack. The earlier release checks below do not verify this source change.

What the release checked

The 0.1 release recorded:

• 4,384 config/media assertions
• 1,038 native GUI assertions
• 28/28 native server tests, both with and without the supplied server pack
• A production-jar startup and spawn/activate/save/remove check in a disposable local pack server, followed by normal shutdown

Native GUI assertions don't replace hands-on checks of every GUI scale and preview control. These results do not establish real multiplayer latency behavior, full-pack client play, or compatibility with every mod combination.

Experimental API checks still pending

The later API source and lightning example have compiled, including core common/client code. Those checks do not establish in-game behavior or update the recorded 0.1 results above. The latest source must be packaged before installation; an older packaged development jar may lack subsequent changes.

Before a stable API release, check:

• Legacy combat/recovery and native roar timing, targeting and cooldowns.
• Server-only addon controls, type changes, invalid/stale saves and missing addons.
• Two bosses executing the same addon independently.
• Completion, phase change, reload, death, removal, unload and shutdown cleanup.
• Temporary entity persistence through chunk and passenger saves.
• Burrow terrain/scale safety, target movement/exit/death, surface restoration and restart recovery.
• Radius membership, support and music while buried and after emergence.
• Event order, final audiences, unload-versus-death reasons and failing listeners.
• Lithium, Sodium, ETF, EMF, the intended pack and real multiplayer connections.

Compiling the code and reviewing the docs don't tell us how it behaves in-game. Runtime testing and deployment are still separate steps; no new API gameplay result or deployment is claimed here.

Targeted compatibility work

Earlier targeted checks in the same release line covered:

• Native server tests with and without Lithium 0.26.2+mc26.3
• 2,700 native model comparisons in an isolated client with Sodium 0.9.2+mc26.3, ETF 7.2.4, EMF 3.3.8, and Lithium
• Offhand ownership and transfer cases, including copied stacks, changed counts/data, replacement offhand items, and ordinary-totem conversion in the supplied pack

Recovery guards native Brain.tick behavior calls while preserving Lithium's optimized implementations, memory expiry, and sensors. Only marked recovering bosses pause behavior execution.

Normal Wardens and foreign emissive textures keep their own rendering/AI paths. Custom file audio uses native channels without a resource-pack SoundInstance, so mods that process only SoundEngine.play may not apply their effects to these clips.

Better Combat, Combat Roll, visual encounters, real connection loss, and full multiplayer interactions still need hands-on checks in the intended pack. The supplied pack result covers that tested setup. It doesn't establish compatibility with every pack.

Pre-launch checklist

Run these checks in a disposable world or a backed-up test copy of the setup you plan to use.

1. Load and permissions: join with matching jars; verify operator commands and that ordinary users cannot edit.
2. Lifecycle: create/copy a template, set spawn, select regions, spawn dormant, activate, save/reload, and remove.
3. Activation: test outside-to-inside entry, already-inside spawn, redstone edges, dimensions, and region height.
4. Combat: cross every health cutoff; check melee/beam timing, close-range priority, target rotation, blocked swings, and cancelled wind-ups.
5. Sequences: test ordered/random subphases, Recovery, roar interludes, and phase/reload interruption.
6. Support: test late entry, exit/re-entry, health-percentage restoration, overlapping arenas, full inventory, moved offhand items, potion cooldown, death, and reconnect.
7. Media and UI: test the skin/eye/brow preview at your GUI scale, first-use audio downloads, phase/death sounds, music exit/fade, resource reload, and live glow.
8. Rewards: verify enabled source, expected default items, quantity/chance settings, vanilla-drop policy, and a single reward execution on death.
9. Multiple clients: repeat important cases with actual players and the network conditions you expect.

Passing an isolated test is a good start. Testing with actual players also checks packet timing and what happens when their actions overlap.

Compatibility capture

Capture is operator-only, bounded, and disabled by default:

/boss debug on
/boss debug status
/boss debug dump
/boss debug off
/boss debug clear

Turn it on while you reproduce a specific attack/support problem. It does not add a periodic AI snapshot system or diagnostic packet stream. Configuration, skin, sound, and encounter errors still provide normal warnings.

Build from source

Build requirements: Java 25 and the repository's Gradle 9.7.0 wrapper. Fabric/Minecraft versions are defined in gradle.properties.

Windows:

.\gradlew.bat build

Linux/macOS:

bash ./gradlew build

The universal client/server jar is written to build/libs/. build includes the dependency-free auditChecks suite. Native GameTests are a separate check.

Portable local checks on Windows:

.\gradlew.bat auditChecks runGametest

Linux/macOS:

bash ./gradlew auditChecks runGametest

GameTests create a disposable world under build/combat-gametest, so you don't need a production server to run them. The separate runClientcheck task loads native model assets, compares transformed poses, reports its result, and closes. Development test mods are excluded from the universal jar.

Keep source, bundled presets/assets, regression fixtures, and wrapper files in version control. Keep runtime worlds, private server configuration, credentials, logs, caches, and generated builds out.

API safety source review — 2026-10-10

The experimental API gained thread checks, interruption/cleanup guards, temporary-entity portal and cross-dimension rejection, relocation ownership checks, and signed 32-bit integer schema bounds. Java 25 / Minecraft 26.3 common/client compilation succeeded. Native injection signatures were inspected in the configured Minecraft bytecode. No game launch, runtime injection check, heap/load measurement or deployment occurred in this review.

Before release, verify interruption during start/stop/damage/relocation, simultaneous bosses, temporary entity portal rejection and unload, saved burrow recovery, and the editor with a server-only addon. Exercise the actual Lithium/Sodium/ETF/EMF environment. Existing release results do not verify this later source. See API safety and resource limits.

Merged workshop checks

0.2.0-beta.4 combines core and companion 0.3.7. Recorded checks: offline full build, 5,216 core assertions, all workshop/file-worker suites, 37 native GameTests, 14 valid/11 invalid schema fixtures, 33 Cloudflare tests and real merged Java/local workerd upload/publish/reconnect/shutdown. Packaged disposable servers cover disabled access, enabled/unreachable TLS relay, legacy settings preservation, native commands and old-companion rejection before initialization. Windows junction escape and native/web stale publication are also rejected in regression fixtures.

No workshop tick watcher exists. Core commands use bounded workers; native editor and preset-copy jobs keep separate bounded I/O-pool ownership. Permission/entity access remains on Minecraft's thread. Retry has one timer with capped exponential backoff. Shutdown cancels streams/requests/tasks; reader Errors settle futures. No TPS/heap improvement is claimed from these short tests. Registry capture's 2 ms budget is soft per batch, not a guaranteed per-tick cap.

Rendered real-client/no-mod login, poor connections, full live-modpack fights and long-running TPS/heap checks remain manual. Native codec checks are not a rendered client session. The hosted website was not republished by this merge. Follow Workshop and Playtest checklist before release.