Add seasonal theme presets

Author: mrfloris

CHANGELOG.md

@@ -2,6 +2,48 @@
 
 This changelog records source milestones. A listed feature is not production approval; release evidence and the Paper/live-data acceptance result belong in [checklist-walktheplank.md](checklist-walktheplank.md).
 
+## [2.6.0-022] — 2026-07-20
+
+Expected artifact: `1MB-WalkThePlank-v2.6.0-022-j25-26.2.jar`
+
+### Seasonal appearance presets
+
+- Added validated, named appearance presets that atomically select the platform palette, placement particle, visibility, and count without changing scoring, reachability, rewards, or the historical Classic leaderboard.
+- Bundled `default`, `summer`, `halloween`, `winter`, and `valentine` presets use safe full blocks with exact untyped Paper 26.2 particles. Operators can define up to 32 lowercase presets with up to 16 blocks each.
+- Retained `theme.active: custom` as the backward-compatible default. Historical live files continue using their top-level `parkourBlocks` and `particle` values until an operator deliberately selects a preset.
+- Existing UUID-owned particle preferences remain authoritative: `full`, `reduced`, and `off` are applied to the selected preset, so seasonal configuration cannot override player accessibility choices.
+- Configuration validation and reload fail closed for missing presets, unsafe blocks, typed/unsupported particles, invalid counts, malformed names, or unknown preset keys. The safe configuration fingerprint and `/walk debug config` now include the effective theme.
+
+## [2.5.4-021] — 2026-07-20
+
+Expected artifact: `1MB-WalkThePlank-v2.5.4-021-j25-26.2.jar`
+
+### Precise landing sampling
+
+- Changed the Paper movement listener to inspect precise-position changes, including a landing that remains inside one block coordinate, while continuing to ignore orientation-only packets.
+- Added focused sampling regressions for within-block movement and look-only events.
+- A real-player score-9 run confirmed sequential scoring, immediate departed-platform restoration, exact two-platform rotation, milestone/combo feedback, and clean final restoration.
+
+## [2.5.3-020] — 2026-07-20
+
+Expected artifact: `1MB-WalkThePlank-v2.5.3-020-j25-26.2.jar`
+
+### Exact air restoration
+
+- Added a primary-thread restoration strategy that writes captured `AIR`, `CAVE_AIR`, and `VOID_AIR` directly through Paper's block-data API.
+- Retained Structure-based restoration for non-air blocks so tile state, PDC, and unknown metadata remain preserved.
+- Extended failpoint instrumentation and regression coverage for both restoration strategies.
+
+## [2.5.2-019] — 2026-07-20
+
+Expected artifact: `1MB-WalkThePlank-v2.5.2-019-j25-26.2.jar`
+
+### Historical GUI-default inheritance
+
+- Fixed inherited translation defaults so historical live `translations.yml` files materialize the new player-head, back, and close menu sections in memory.
+- Retained operator-customized translations and avoided rewriting the historical file.
+- Added a regression proving a legacy translation file can open the complete six-action menu.
+
 ## [2.5.1-018] — 2026-07-20
 
 Expected artifact: `1MB-WalkThePlank-v2.5.1-018-j25-26.2.jar`

README.md

@@ -1,22 +1,22 @@
 # WalkThePlank future improvements and release status
 
-This is the authoritative future-development TODO and release-status document. It separates what is implemented through source release **v2.5.1 build 018** from what still needs server acceptance or future design work. “Implemented” means the behavior is present in source; the table or checklist identifies whether automated or Paper/live-data evidence still remains. It does not mean the summer-event candidate is production-approved. The release candidate still has to pass [checklist-walktheplank.md](checklist-walktheplank.md).
+This is the authoritative future-development TODO and release-status document. It separates what is implemented through source release **v2.6.0 build 022** from what still needs server acceptance or future design work. “Implemented” means the behavior is present in source; the table or checklist identifies whether automated or Paper/live-data evidence still remains. It does not mean the summer-event candidate is production-approved. The release candidate still has to pass [checklist-walktheplank.md](checklist-walktheplank.md).
 
 Status labels:
 
-- **Implemented** — present in the current build-018 source.
+- **Implemented** — present in the current build-022 source.
 - **Implemented; beta verification pending** — present, but the final JAR still needs the named Paper/live-data test.
 - **Partial** — a safe foundation exists, but an important workflow or assurance remains.
 - **Proposed** — not present and must not be advertised as a current feature.
 
 ## Deferred modernization queue
 
-Build 003 remains the historical modernization baseline, build 004 the event-safety release, build 005 the destructive-testing foundation, build 006 the off-main durability release, and build 007 the command/API modernization release. Build 008 added bounded migration-backup retention, milestones/accessibility, separate Combo/Flawless categories, rate-limited movement anomaly evidence, and a verified audit chain. Builds 009–013 addressed the 1MB GUI and Paper 26.2 real-player compatibility regressions. Build 014 made asynchronous block-cleanup completion idempotent and applied the shared recursively non-italic pastel 1MB tooltip style. Builds 015–016 completed the Play proofreading and configuration-aware tutorial. Build 017 added the live personal-stat head plus `/menu` and close controls within the existing hardened GUI session model. Build 018 keeps the durable successor hidden until landing and restores the original current-plus-one-destination gameplay window. Every remaining unchecked feature stays deferred so its evidence cannot be confused with this candidate.
+Build 003 remains the historical modernization baseline, build 004 the event-safety release, build 005 the destructive-testing foundation, build 006 the off-main durability release, and build 007 the command/API modernization release. Build 008 added bounded migration-backup retention, milestones/accessibility, separate Combo/Flawless categories, rate-limited movement anomaly evidence, and a verified audit chain. Builds 009–021 addressed the 1MB GUI and Paper 26.2 real-player compatibility regressions, culminating in a successful real-player score-9 run with correct two-platform rotation and cleanup. Build 022 adds validated seasonal appearance presets without changing mechanics or Classic scores. Every remaining unchecked feature stays deferred so its evidence cannot be confused with this candidate.
 
 1. [x] **v2.1.1 build 004 — event-safety and operations implemented; beta acceptance still pending.** External-teleport decisions occur at `HIGHEST` with observation-only `MONITOR` and next-tick verification; GUI sessions bind owner UUID/nonce/generation/exact inventory with one pending action; trusted formatting is parsed separately from literal dynamic components with explicit `minimessage:` opt-in and legacy `&` compatibility; `/walk admin doctor` produces a privacy-safe report with an asynchronous SQLite probe.
 2. [x] **v2.1.2 build 005 — disposable Paper integration and fault-injection harness implemented; final-candidate and real-client evidence pending.** A separate test plugin, Java 25 Class-File API instrumented-copy builder, 24 named failpoints, two-start/PlaceholderAPI/lifecycle/log runner, real-player queue/teleport/GUI/reconnect/exit probes, reflection event contracts, and positive/negative production-isolation checks are present. Development-artifact runs passed the automated two-start profile and the `config.after_runtime_commit` exit-97/recovery profile; repeat them against the clean committed candidate and complete every applicable real-client/hard-kill checklist row before treating this item as release-qualified.
 3. [x] **v2.2.0 build 006 — two-phase off-main durability pipeline implemented; Paper/destructive acceptance pending.** Bukkit/Paper capture, validation, restoration, and mutation remain on the primary thread. Immutable journal bytes go to a bounded FIFO recovery writer; audit/export/config work uses an independent bounded operations writer. Exclusive lifetime ownership is acquired before recovery journals open and remains held until any delayed writer truly terminates. Successful completion returns to the primary thread and revalidates exact run/session/platform generations, arena/block leases, player state, permissions, and block fingerprints. Uncertain post-rename commits and failed discards retain exact evidence for retry. Successor preparation begins while the player traverses the current jump; build 018 corrects the original implementation so durability completion remains hidden until the exact landing consumes it. Predecessor journal deletion/fsync completes off-thread. Reload, administrative recovery, and shutdown use explicit barriers/completion queues without async Bukkit access or caller-thread durability fallback.
-4. [ ] **Remaining Summer Season feature bundle.** Preserve the imported Classic leaderboard while adding cosmetic themes, a versioned daily course and separate ranking, seasonal Momentum, quests, durable UUID claim keys, and a community plank goal. Milestones, accessibility preferences, and separate Combo/Flawless categories moved into build 008; daily/seasonal scoring must still run in shadow mode before rewards or public ranking.
+4. [ ] **Remaining Summer Season feature bundle.** Preserve the imported Classic leaderboard while adding a versioned daily course and separate ranking, seasonal Momentum, quests, durable UUID claim keys, and a community plank goal. Build 022 implements cosmetic block/particle themes; milestones, accessibility preferences, and separate Combo/Flawless categories moved into build 008. Daily/seasonal scoring must still run in shadow mode before rewards or public ranking.
 5. [x] **v2.3.0 build 007 — command/API modernization and machine qualification completed; human acceptance remained pending.** The former 2,789-line handler is split into player, queue, arena, season/export, reward, investigation, and database/diagnostic modules. A typed Brigadier tree is registered from the standard `JavaPlugin` through `LifecycleEvents.COMMANDS`, retaining aliases and compatibility forms without requiring `paper-plugin.yml`. Online-player and UUID arguments, bounded limits, enum/literal branches, dynamic suggestions, and destructive confirmation words are represented in the tree. Experimental Dialog/data-component APIs remain intentionally absent. SQLite-only storage, no direct CMI database access, no Vault coupling, no uncertain-reward replay, and the historical Classic leaderboard are unchanged. The controlled scenarios, reproducibility/freeze, standalone/full-stack Paper smoke, and test-server synchronization passed for the tagged `v2.3.0-007-rc.1` artifact; that evidence is historical and does not qualify build 008.
 6. [x] **v2.4.0 build 008 — fair-play, accessibility, categories, retention, and audit-chain source implemented; Paper/human acceptance pending.** Schema v3 adds UUID-owned preferences and atomic per-run/category projections without altering Classic. Configured native milestones respect full/reduced/off particles and sound/title toggles. Combo and Flawless are separate leaderboards. Event defenses plus an authoritative sweep cover flight/glide/riptide/pearls/consumable teleports/projectiles/vehicles/velocity/effects/attributes/walk speed/bounds/jump rate; detected integrity failures persist no score and never auto-ban. Automatic backups are quick-checked before bounded pruning, and retained JSONL audit records are hash-chained and restart-verified.
 
@@ -46,7 +46,7 @@ Build 008 includes all previous modernization layers documented in [CHANGELOG.md
 | Capability | Status | Notes |
 | --- | --- | --- |
 | Gradle build and wrapper | **Implemented** | Gradle 9.6.1, Shadow 9.5.1, strict Java 25 compilation. |
-| Paper target | **Implemented; final build-018 smoke pending** | Exact compile API is `26.2.build.62-beta`; `api-version: 26.2` and an explicit `ServerBuildInfo` gate reject older lines/builds. Repeat the controlled profile and full candidate smoke against build 62 or newer before approval. |
+| Paper target | **Implemented; final build-022 smoke pending** | Exact compile API is `26.2.build.62-beta`; `api-version: 26.2` and an explicit `ServerBuildInfo` gate reject older lines/builds. Repeat the controlled profile and full candidate smoke against build 62 or newer before approval. |
 | Standalone SQLite JAR | **Implemented** | SQLite JDBC 3.53.2.0 is shaded; MySQL/MariaDB is absent. |
 | Archive-composition gate | **Implemented** | Rejects bundled Paper/Bukkit/PlaceholderAPI/live-database classes or files and remote-database drivers. |
 | Isolated scenario artifacts | **Implemented; final-candidate rerun pending** | The harness is an independent Paper plugin and the Java 25 Class-File API transformer writes a distinct `TEST-ONLY-` copy. Neither is packaged beneath `build/libs/` or allowed to replace the production JAR. Development-artifact isolation and controlled-profile gates passed. |
@@ -93,6 +93,7 @@ Build 008 includes all previous modernization layers documented in [CHANGELOG.md
 | Movement-integrity controls | **Implemented; adversarial client matrix pending** | Flight/glide/riptide, exploit teleports, projectiles, vehicles, effects, speed state, arena bounds, and minimum inter-jump timing are blocked/rechecked. Non-zero server-applied velocity is replaced with zero without cancelling Paper's cause-less event. A detected altered run persists zero score and no category/reward; anomaly evidence is rate-limited and never auto-bans. |
 | Combo and Flawless | **Implemented; gameplay calibration pending** | Separate atomic personal-best categories. Combo is the maximum within-gap streak; Flawless is the final Classic score only if every transition met the target. Classic is unchanged. |
 | Milestones/accessibility | **Implemented; client presentation pending** | Configured native action bar/title/sound/particle feedback with UUID-owned full/reduced/off particles and sound/title toggles. |
+| Seasonal appearance presets | **Implemented; client presentation pending** | `custom`, `default`, `summer`, `halloween`, `winter`, and `valentine` resolve a validated safe-block palette and untyped Paper particle. The choice changes appearance only and respects each player's particle preference. |
 
 ### Capacity, commands, and operator tooling
 
@@ -197,7 +198,7 @@ Add Classic, Relaxed, and Expert profiles with separate reachability envelopes,
 
 #### Configured themes
 
-Support pirate/summer, tropical, nether, end, ice, or rainbow presentation through validated material/particle/sound sets. Theme alone must not change scoring; a mechanically different theme becomes a separate category.
+**Block/particle presets implemented in build 022; Paper/client presentation pending.** `custom`, `default`, `summer`, `halloween`, `winter`, and `valentine` select validated safe platform palettes and untyped Paper particles without changing scoring. Additional pirate/tropical/nether/end/rainbow presets and optional theme-specific sounds remain presentation work. A mechanically different theme must become a separate category.
 
 #### Seeded daily challenge
 

checklist-walktheplank.md

@@ -1,5 +1,5 @@
-pluginVersion=2.5.4
-buildNumber=021
+pluginVersion=2.6.0
+buildNumber=022
 javaTarget=25
 paperTarget=26.2
 paperApiVersion=26.2.build.62-beta

feature-improvements-walktheplank.md

@@ -706,6 +706,7 @@ private void showConfig(CommandSender sender) {
                 sender,
                 "Arenas",
                 Integer.toString(current.arenas().size()));
+        support.sendField(sender, "Theme", current.activeTheme());
         support.sendField(
                 sender, "Blocks", current.parkourBlocks().toString());
         support.sendField(