Boss Observatory and Test Mod - clockworktownsmp/clockwork-bosses GitHub Wiki

Boss Observatory and Test Mod

Boss Observatory is a separate testing tool for Clockwork Bosses. The Test Mod runs real encounters on the server, and the browser lets you see their progress and results. The basic selected-template combat workflow is verified in 0.4.1-dev for a local disposable profile. It's still a development tool, isn't part of the stable core, and hasn't been installed on the live server or published as an application.

Status and compatibility

These tests use a fingerprinted 0.3.0-beta.5 core snapshot with Carpet. Don't swap in stable 0.2.0 or beta.6 and assume it'll work. The test hooks depend on helpers from that specific version and experimental API revision 1. Keep the exact core, Test Mod, Minecraft, Carpet, and other mod versions with each run's results.

Available in local development Unfinished or unverified
Local browser connection to the disposable testing profile Native F8 GUI runtime, real login and rendering
Selected real-template sword/axe repeats, loadouts and normal gear wear Better Combat combos and broader combat-mod behavior
Saved results, restart recovery and cancellation cleanup Full GUI/browser acceptance beyond this basic workflow
Stability lifecycle checks and browser report comparisons Live installation or public application deployment

The browser's basic selected-template workflow is verified against the server-side runner. The native F8 GUI compiles, but its runtime, login and rendering still need a manual check. The planned address is observatory.clockworkboss.com; a placeholder site isn't a published testing application.

Keep encounters and tests separate

A boss template is the fight you're making: phases, attacks, player support, visuals, and loot. A test preset/scenario is how you want to test it: which encounter, how many players, their gear and bot behavior, how many runs, the time limit, and what should happen.

The server owns presets, validation, execution and results. Runs capture their starting preset, and revision checks protect concurrent edits. The browser now uses that testing service for the verified basic workflow. The native GUI uses the same definitions in source, but its complete in-game flow remains unverified.

Use the existing local stability runner

Use an isolated disposable profile, never the live server. The local project needs Java 25, Node.js, cached Gradle dependencies, Carpet and the matching development core. From the Observatory repository, start open-test-profile.cmd, then open http://127.0.0.1:4187/fight-results.html. The local profile stays ready for another run after a test ends; it isn't the older 4186 preview.

Choose Server stability for repeated encounters and cleanup checks. Save the test conditions before starting. Stop cancels the current test, preserves results and leaves incomplete work labelled separately. Earlier migration compilation checks alone didn't establish runtime readiness; the later 0.4.1-dev runs below provide the new local evidence.

Run the selected-template combat test

  1. Start open-test-profile.cmd and open the local Fight Results page.
  2. Choose Encounter balance and load combat-sword or combat-axe.
  3. Select a real boss template, player conditions, repetitions and time limit.
  4. Choose Save, then Start. Watch progress and read the saved results.

The real-template dropdown includes bundled 1_player through 6_players. Your separate test-template library is work/test-profile/data/boss-templates/<name>/template.json. Boss templates define the encounter; the saved test preset defines the experiment.

The verified loadouts use damageable diamond armor with Protection IV/Unbreaking III and a netherite sword or axe with maximum compatible enchantments. Arena HP defaults to 100. Normal combat wears equipment; a separately labelled one-durability fixture checks item breakage. Don't treat that break fixture as normal balance conditions.

The native runner repeats the selected encounter and stores its results. PASS means the measurement/cleanup suite worked, not that the players won. A valid suite can include wipes or timeouts; read each encounter outcome separately.

What the first stability suite checks

The low-damage 35-HP fixture rotates empty offhand, occupied shield and full inventory cases with diamond Protection IV/Sharpness V gear and 100 arena HP. It observes four health phases and native boss death, then checks inventory, temporary potions, baseline health/effects and owned world state.

The test checks whether the core restored everything before clearing equipment/effects or disconnecting the test players. Otherwise, the test could clean up a mess the mod left behind and incorrectly call it a pass. Each cycle keeps its expected results, time limits, and pass/fail/not-tested results.

A historical six-cycle run passed each case twice; each fight took 195 native ticks. This is a lifecycle smoke fixture, not a balanced encounter recommendation. Its evidence predates the newer GUI/service extension and was not rerun after migration.

Commands

These commands belong to the separate Test Mod, with native owner permission, normally operator level 4. Core installation alone does not provide them.

Command Purpose
/cwtest init Create missing scenario examples under config/clockwork-test/scenarios/.
/cwtest scenario <name> Run a configured scenario.
/cwtest batch <name> Run its paired/repeated variants.
/cwtest stability <cycles> Run the stability suite on a marked disposable, empty dedicated server at ordinary tick rate.
/cwtest inspect Show progress.
/cwtest cancel Stop the current trial/batch.
/cwtest start <template> <players> <seconds> <potions> Legacy ordinary-speed manual run with iron gear and a 45% potion threshold.

The earlier command-driven scenario reference uses diamond Protection IV, Sharpness V and drinking below 40% HP. The verified browser combat presets use the damageable diamond/netherite loadouts above. Configure conditions for the party you intend to test; the legacy command has different defaults.

Balance reports and measurements

Existing command-driven batches accept player counts, equipment/enchantments, potion thresholds, seeds and variants. Reports include win/wipe/timeout rates, duration, survivors, lowest/final HP, actual potion healing/doses, targeting and damage by phase/subphase. Final HP is captured before support cleanup changes maximum health; nested damage frames are handled separately.

Import JSON, JSONL or a batch index into Fight Results for charts and comparisons. JSON/JSONL copies of one run count once. Cancelled/failed runs are excluded from the balance-rate denominator. Imports stay in the tab; keep original report files. Older reports without timelines are labelled accordingly.

Keep gear, versions, settings, and seeds the same when comparing runs. Supported random-number generation is reset and recorded, but Minecraft scheduling and addons can still change what happens. The same seed doesn't guarantee an identical fight.

The bots use simple melee/cautious behavior with their own reaction timing. They don't reliably dodge, kite, make human decisions, or execute Better Combat combos. Use the results to help tune a fight, with those limits in mind.

Acceleration changes real server tick rate on a designated disposable dedicated server, preserving movement, combat, cooldown and drinking ticks. It requires the disposable flag and no unrelated players, and restores the prior rate on orderly completion/cancellation. Stability runs stay at ordinary 20 ticks/s. This is not simplified damage math.

Verified local checkpoint: 0.4.1-dev

The final Test Mod jar has SHA-256 92f1889e06c54758aee9004cd758680999379fdb0fb9d5ae43be39159becc4d3 and an exact 0.3.0-beta.5 core dependency. The final source fingerprint is 1f48b82d5667b437ed995e448fb9a253e7ff27ba7c3dfa16baf64ef10b001f98. These identifiers describe this tested development build; they don't declare beta.6 or stable compatibility.

The reported final runs include two sword timeouts at 20 seconds, two two-bot axe victories using the 1_player template, and three lifecycle cleanup cycles. All three aggregate UUIDs were still saved after a fresh-profile restart. Loadouts, normal wear, the separate break fixture and cancellation cleanup were verified for the local workflow.

This readiness is limited to the browser and disposable profile. The native F8 GUI compiled but wasn't runtime/login/rendering tested. Better Combat combos, real multiplayer and live installation remain separate; no deployment or publication occurred. The earlier 0.4.0-dev six-cycle fixture above remains historical evidence, not a replacement for these results.

Evidence and remaining coverage

Individual fights export JSON, JSONL, sampled CSV and readable text under clockwork-test-reports. Stability jobs retain reports, forced checkpoint journals and independently captured console output. Exact settings/artifact fingerprints help distinguish changed inputs. A crash can leave the disposable world dirty; an exit is not proof of cleanup.

Tick measurements include native execution and the test callbacks; asynchronous work and other exclusions are documented separately. More heap usage or entities can be worth investigating, but that alone doesn't prove a leak. A short successful run doesn't prove long-term stability either.

Subphases, simultaneous encounters, comprehensive entry/exit/death/disconnect/reconnect cases, duplicate rewards, long soak/leak investigation and empty-server pause/rejoin need additional coverage. Fixture rewards are disabled. Carpet bots do not prove real login, networking, rendering, resource packs, poor connections or human balance.

Basic selected-template browser combat controls are now verified locally. Expanded behavior controls, overhealing and attack-level reporting, and complete native GUI/browser acceptance still need further evidence. Use the Observatory repository's STABILITY.md, SCENARIOS.md, TELEMETRY.md and TEST_EVIDENCE.md for exact implementation limits. Keep these development results separate from core release evidence and manual playtests.

⚠️ **GitHub.com Fallback** ⚠️