chore(knowledge): move canonical docs to shared SoMC wiki
This commit is contained in:
@@ -1,18 +1,9 @@
|
||||
# Spigot Heights Agent Guide
|
||||
# spigot-heights agent entrypoint
|
||||
|
||||
## Canonical design
|
||||
The canonical stories, engineering guidance, and **all process documents** are in the private [SoMC OKF wiki](https://git.garvis.dev/dmg/somc-okf/src/branch/main/index.md).
|
||||
|
||||
- `design/` is the canonical OKF v0.1 knowledge bundle.
|
||||
- Read relevant user stories before implementation and keep acceptance criteria and `design/log.md` synchronized with verified behavior.
|
||||
Before work, read the sibling `../somc-okf/index.md`, `../somc-okf/processes/index.md`, `../somc-okf/projects/spigot-heights/index.md`, `engineering.md` in that project section, and relevant `../somc-okf/user-stories/spigot-heights/` stories. Also follow the parent workspace `AGENTS.md` when present.
|
||||
|
||||
## Engineering
|
||||
For standalone checkouts, start at the [project page](https://git.garvis.dev/dmg/somc-okf/src/branch/main/projects/spigot-heights/index.md) and [shared process](https://git.garvis.dev/dmg/somc-okf/src/branch/main/processes/development.md). Obtain wiki access before feature work; do not recreate a local knowledge bundle. Source builds do not require private wiki access.
|
||||
|
||||
- Target Java 25 and Purpur `26.2.build.2618-stable`.
|
||||
- Use Gradle Kotlin DSL and JUnit 5.
|
||||
- Prefer small, server-independent domain classes with Bukkit adapters at the boundary.
|
||||
- Develop test-first where practical and verify with `./gradlew clean check jar`.
|
||||
- Treat custom item identity as persistent metadata; never trust display names.
|
||||
- Validate all configuration before enabling gameplay behavior.
|
||||
- Persist player data by UUID and use atomic replacement where supported.
|
||||
- Keep event handlers on the server thread and avoid unnecessary work on player movement.
|
||||
- Use conventional commits in the form `type(scope): description`.
|
||||
Development follows [Development cycle](https://git.garvis.dev/dmg/somc-okf/src/branch/main/runbooks/development-cycle.md): approved stories, failing tests, passing implementation, verification, then source/wiki commit and push. GitOps updates are committed locally **without pushing**; only [Do release](https://git.garvis.dev/dmg/somc-okf/src/branch/main/runbooks/do-release.md) authorizes a reviewed GitOps push.
|
||||
|
||||
@@ -2,7 +2,7 @@
|
||||
|
||||
A Purpur 26.2 plugin adding craftable player-scaling potions and dispenser launch tubes for tiny players.
|
||||
|
||||
Approved behavior is specified in the [OKF design bundle](design/index.md).
|
||||
Approved behavior is specified in the [SoMC OKF wiki](https://git.garvis.dev/dmg/somc-okf/src/branch/main/projects/spigot-heights/index.md).
|
||||
|
||||
## Requirements
|
||||
|
||||
|
||||
@@ -1,15 +0,0 @@
|
||||
---
|
||||
type: Index
|
||||
title: Spigot Heights Design
|
||||
description: Entry point for the Spigot Heights OKF knowledge bundle.
|
||||
okf_version: "0.1"
|
||||
---
|
||||
|
||||
# Spigot Heights Design
|
||||
|
||||
This bundle documents craftable player-scaling potions, configurable stature limits, tiny-player dispenser launchers, persistence, and delivery requirements.
|
||||
|
||||
## Explore
|
||||
|
||||
- [User stories](user-stories/index.md)
|
||||
- [Design log](log.md)
|
||||
@@ -1,64 +0,0 @@
|
||||
---
|
||||
type: Log
|
||||
title: Spigot Heights Design Log
|
||||
description: Chronological record of material decisions affecting Spigot Heights.
|
||||
---
|
||||
|
||||
# Spigot Heights Design Log
|
||||
|
||||
## 2026-09-07T00:00:54Z — Player-height commands completed
|
||||
|
||||
- Added `/heights player <name> [scale]` for exact online-player lookup, base/effective scale reporting, immediate saved changes, and permission-protected name/size completion.
|
||||
- Command-set scales honor live limits and the exact `1.0` restoration exception. The player-state store now publishes cached changes only after successful persistence, and commands save before applying scale.
|
||||
- Verified `./gradlew clean check jar`: all 33 tests passed, including permissions, input validation, completions, scale reporting, reload, and failed-save protection. Inspected Bukkit lookup/attribute and join/respawn wiring; live-server/client verification remains unperformed.
|
||||
- Updated README and completed US-008 and related US-004/US-007 criteria.
|
||||
|
||||
## 2026-09-06T23:54:36Z — Player-height commands approved and started
|
||||
|
||||
- Approved [US-008](user-stories/us-008-manage-player-height.md): `/heights player <name> [scale]` for online players, admin permissions, tab completion, and UUID persistence.
|
||||
- Values follow current min/max bounds with the exact `1.0` exception; failed saves must not change cached or live player height.
|
||||
|
||||
## 2026-09-06T23:51:22Z — Settings commands completed
|
||||
|
||||
- Added `/heights settings` and `/heights set min|max <value>` with `spigotheights.admin` (default op), generic sender support, and prefix-filtered tab completion of valid example values.
|
||||
- Validated changes are persisted through temporary-file replacement (atomic where supported) before activating shared live settings. Unrelated YAML values are preserved; malformed files and write failures do not activate new limits.
|
||||
- Updated gameplay listeners to read current settings without immediately resizing players or resetting launcher cooldowns.
|
||||
- Verified `./gradlew clean check jar`: all 26 tests passed. Inspected command registration and event wiring; live-server/client verification remains unperformed. Completed US-007 and the related US-004 change.
|
||||
|
||||
## 2026-09-06T23:45:28Z — Settings commands approved and started
|
||||
|
||||
- Approved [US-007](user-stories/us-007-manage-settings-commands.md): permission-protected min/max commands, tab completion, validation, and persistent live updates.
|
||||
- Existing players are not resized immediately; subsequent gameplay reads current limits. The exact `1.0` restoration exception remains intact.
|
||||
|
||||
## 2026-09-06T23:41:16Z — Restoration completed
|
||||
|
||||
- Added the white Potion of Restoration with persistent identity and the approved Sugar upgrade recipe.
|
||||
- Consumption restores exact scale `1.0` through the existing report/save path; saved `1.0` bypasses configured-range clamping on join and respawn.
|
||||
- Verified `./gradlew clean check jar`: all 17 tests passed, including restoration, persistence reload, range exceptions, recipe shape, identity, and existing potion regression coverage.
|
||||
- Inspected Bukkit recipe/metadata and event wiring; live-server gameplay verification remains unperformed. Updated the README and completed US-006 and the related US-004 change.
|
||||
|
||||
## 2026-09-06T23:37:19Z — Restoration approved and implementation started
|
||||
|
||||
- Approved [US-006](user-stories/us-006-restore-default-stature.md): a Sugar-based upgrade of Shifting Stature restores exact scale `1.0`.
|
||||
- Approved an exception to saved-scale clamping in [US-004](user-stories/us-004-configure-and-persist.md) so restoration survives reconnects and respawns even outside configured limits.
|
||||
|
||||
## 2026-09-04 — Initial design approved
|
||||
|
||||
- Player scale defaults to a configurable range of `0.4` through `2.0`.
|
||||
- A moderate recipe creates a random stature potion; more expensive upgrades create targeted growth and diminution potions.
|
||||
- Random stature is selected uniformly in configurable `0.1` increments.
|
||||
- Players strictly below scale `0.5` can be launched through a dispenser fed by the hopper beneath them.
|
||||
- Launcher speed defaults to 1.5 blocks per tick with a 20-tick cooldown and safe-exit checks.
|
||||
- The project follows the neighboring Spigot Base Java 25, Purpur, Gradle, OKF, CI, and release conventions.
|
||||
|
||||
## 2026-09-04 — Implementation started
|
||||
|
||||
- Approved implementation began with user stories, tests, and the Gradle/Purpur foundation.
|
||||
|
||||
## 2026-09-04 — Initial release scope completed
|
||||
|
||||
- Implemented authenticated random, growth, and diminution potions with approved recipes and durable UUID-keyed player scale.
|
||||
- Added validated stature and launcher configuration with safe clamping to Minecraft's scale range.
|
||||
- Implemented cooldown-protected hopper-to-dispenser launch tubes for tiny players with six-axis launch support and empty-exit checks.
|
||||
- Added the Java 25 Purpur build, automated tests, Gitea CI and semantic-release workflows, README, and project-specific agent guidance.
|
||||
- Verified the implementation with `./gradlew clean check jar` and created the public `dmg/spigot-heights` Gitea repository.
|
||||
@@ -1,16 +0,0 @@
|
||||
---
|
||||
type: Index
|
||||
title: Spigot Heights User Stories
|
||||
description: Catalog of user stories for the Spigot Heights plugin.
|
||||
---
|
||||
|
||||
# Spigot Heights User Stories
|
||||
|
||||
1. [US-001: Drink a Potion of Shifting Stature](us-001-drink-shifting-stature-potion.md)
|
||||
2. [US-002: Make precise stature adjustments](us-002-adjust-stature.md)
|
||||
3. [US-003: Launch tiny players through dispensers](us-003-launch-tiny-players.md)
|
||||
4. [US-004: Configure and persist stature behavior](us-004-configure-and-persist.md)
|
||||
5. [US-005: Build and release the plugin](us-005-build-and-release.md)
|
||||
6. [US-006: Restore default stature](us-006-restore-default-stature.md)
|
||||
7. [US-007: Manage stature settings with commands](us-007-manage-settings-commands.md)
|
||||
8. [US-008: View and set player height](us-008-manage-player-height.md)
|
||||
@@ -1,25 +0,0 @@
|
||||
---
|
||||
type: User Story
|
||||
title: "US-001: Drink a Potion of Shifting Stature"
|
||||
description: Let players craft and drink a potion that gives them a random configured scale.
|
||||
status: done
|
||||
---
|
||||
|
||||
# US-001: Drink a Potion of Shifting Stature
|
||||
|
||||
As a **player**, I want to drink a craftable potion that changes my stature unpredictably so that player size becomes a fun survival mechanic.
|
||||
|
||||
## Acceptance criteria
|
||||
|
||||
- [x] The distinct potion is authenticated with persistent item metadata rather than its display name alone.
|
||||
- [x] Its shaped recipe is `ACA/AWA/ACA`, where `A` is Amethyst Shard, `C` is Chorus Fruit, and `W` is an Awkward Potion.
|
||||
- [x] Drinking it consumes one potion, leaves normal bottle handling intact, and selects a scale from the configured inclusive range.
|
||||
- [x] Outcomes are uniformly selected in configured adjustment-step increments, including both endpoints when aligned.
|
||||
- [x] The resulting Minecraft scale attribute is applied and reported to the player.
|
||||
- [x] The resulting scale persists across logout, restart, world change, and death.
|
||||
- [x] Automated tests cover bounds, endpoint reachability, and recipe identity.
|
||||
|
||||
## Related
|
||||
|
||||
- [US-002: Make precise stature adjustments](us-002-adjust-stature.md)
|
||||
- [US-004: Configure and persist stature behavior](us-004-configure-and-persist.md)
|
||||
@@ -1,24 +0,0 @@
|
||||
---
|
||||
type: User Story
|
||||
title: "US-002: Make precise stature adjustments"
|
||||
description: Let players craft upgraded potions that increase or decrease scale by one configured step.
|
||||
status: done
|
||||
---
|
||||
|
||||
# US-002: Make precise stature adjustments
|
||||
|
||||
As a **player**, I want more expensive growth and diminution potions so that I can adjust my stature predictably.
|
||||
|
||||
## Acceptance criteria
|
||||
|
||||
- [x] The Potion of Growth uses `GAG/ASA/GRG`, where `G` is Gold Ingot, `A` is Amethyst Shard, `S` is an authenticated Potion of Shifting Stature, and `R` is Rabbit's Foot.
|
||||
- [x] The Potion of Diminution uses `GAG/ASA/GFG`, where `F` is Fermented Spider Eye.
|
||||
- [x] Each resulting potion has distinct persistent metadata.
|
||||
- [x] Growth adds one configured adjustment step and clamps at the maximum.
|
||||
- [x] Diminution subtracts one configured adjustment step and clamps at the minimum.
|
||||
- [x] Adjusted scales are reported and persisted under the same rules as random stature.
|
||||
- [x] Automated tests cover adjustment, clamping, and potion identity.
|
||||
|
||||
## Related
|
||||
|
||||
- [US-001: Drink a Potion of Shifting Stature](us-001-drink-shifting-stature-potion.md)
|
||||
@@ -1,25 +0,0 @@
|
||||
---
|
||||
type: User Story
|
||||
title: "US-003: Launch tiny players through dispensers"
|
||||
description: Launch sufficiently small players from a dispenser connected to the hopper beneath them.
|
||||
status: done
|
||||
---
|
||||
|
||||
# US-003: Launch tiny players through dispensers
|
||||
|
||||
As a **tiny player**, I want connected hoppers and dispensers to act as launch tubes so that my stature enables playful transport systems.
|
||||
|
||||
## Acceptance criteria
|
||||
|
||||
- [x] A player strictly below the configured threshold triggers when walking onto a hopper whose output points into a dispenser.
|
||||
- [x] No redstone signal is required.
|
||||
- [x] The player moves to a safe centered position immediately in front of the dispenser and receives velocity in its facing direction.
|
||||
- [x] Velocity magnitude and cooldown are configurable and default to 1.5 blocks per tick and 20 ticks.
|
||||
- [x] Obstructed or unsafe exits abort without moving the player.
|
||||
- [x] Players at or above the threshold are not launched.
|
||||
- [x] Cooldown prevents immediate repeated or cyclic launching.
|
||||
- [x] Automated tests cover threshold boundaries, orientations, cooldown, and obstruction policy.
|
||||
|
||||
## Related
|
||||
|
||||
- [US-004: Configure and persist stature behavior](us-004-configure-and-persist.md)
|
||||
@@ -1,32 +0,0 @@
|
||||
---
|
||||
type: User Story
|
||||
title: "US-004: Configure and persist stature behavior"
|
||||
description: Give operators validated settings and durable UUID-keyed player scales.
|
||||
status: done
|
||||
---
|
||||
|
||||
# US-004: Configure and persist stature behavior
|
||||
|
||||
As a **server operator**, I want validated stature and launcher settings with durable state so that behavior remains safe and predictable.
|
||||
|
||||
## Acceptance criteria
|
||||
|
||||
- [x] Defaults are minimum `0.4`, maximum `2.0`, adjustment step `0.1`, launcher threshold `0.5`, speed `1.5`, and cooldown `20` ticks.
|
||||
- [x] Configuration requires finite positive values, minimum no greater than maximum, and a launcher threshold within the supported scale range.
|
||||
- [x] Invalid startup configuration disables the plugin with a clear error.
|
||||
- [x] Player scales are stored by UUID using atomic file replacement where supported.
|
||||
- [x] Updating known state preserves unknown forward-compatible YAML fields.
|
||||
- [x] Missing state defaults safely to scale `1.0` clamped to the configured range.
|
||||
- [x] Saved out-of-range state is clamped before it is applied, except exact scale `1.0`, which is preserved for restoration.
|
||||
- [x] Configuration and state behavior have automated tests.
|
||||
- [x] Approved min/max commands validate and persist changes before publishing live settings to gameplay listeners, without immediately resizing players.
|
||||
|
||||
- [x] Command-set player heights persist by UUID under existing reload rules; failed saves do not publish a new cached or live height.
|
||||
|
||||
## Related
|
||||
|
||||
- [US-008: View and set player height](us-008-manage-player-height.md)
|
||||
|
||||
- [User-story catalog](index.md)
|
||||
- [US-007: Manage stature settings with commands](us-007-manage-settings-commands.md)
|
||||
- [US-006: Restore default stature](us-006-restore-default-stature.md)
|
||||
@@ -1,24 +0,0 @@
|
||||
---
|
||||
type: User Story
|
||||
title: "US-005: Build and release the plugin"
|
||||
description: Give maintainers repeatable Purpur builds, automated verification, and versioned Gitea releases.
|
||||
status: done
|
||||
---
|
||||
|
||||
# US-005: Build and release the plugin
|
||||
|
||||
As a **plugin maintainer**, I want automated builds and releases modeled on Spigot Base so that tested artifacts can be distributed consistently.
|
||||
|
||||
## Acceptance criteria
|
||||
|
||||
- [x] Gradle compiles against Purpur API `26.2.build.2618-stable` using Java 25.
|
||||
- [x] Compiler lint warnings fail the build and JUnit 5 tests run during `check`.
|
||||
- [x] Gitea Actions verifies pushes and pull requests and stores a development JAR.
|
||||
- [x] Pull requests validate conventional commits.
|
||||
- [x] Main-branch conventional commits drive semantic releases and attach versioned JARs to Gitea releases.
|
||||
- [x] The README documents requirements, recipes, configuration, building, and releases.
|
||||
- [x] `./gradlew clean check jar` succeeds.
|
||||
|
||||
## Related
|
||||
|
||||
- [User-story catalog](index.md)
|
||||
@@ -1,28 +0,0 @@
|
||||
---
|
||||
type: User Story
|
||||
title: "US-006: Restore default stature"
|
||||
description: Let players craft a potion that permanently restores their scale to 1.0.
|
||||
status: done
|
||||
---
|
||||
|
||||
# US-006: Restore default stature
|
||||
|
||||
As a **player**, I want a Potion of Restoration so that I can return to normal size.
|
||||
|
||||
## Acceptance criteria
|
||||
|
||||
- [x] Drinking the potion sets scale to exactly `1.0`, regardless of configured limits.
|
||||
- [x] The potion uses distinct persistent metadata rather than its display name for identity.
|
||||
- [x] The new scale is reported and saved by UUID, and retained across reconnects and respawns.
|
||||
- [x] The recipe is `GAG/ASA/GUG`, where `G` is Gold Ingot, `A` is Amethyst Shard, `S` is an authenticated Potion of Shifting Stature, and `U` is Sugar.
|
||||
- [x] Automated tests cover restoration, saved-scale handling, recipe shape, and distinct identity; the README documents the recipe and behavior.
|
||||
|
||||
## Verification
|
||||
|
||||
- `./gradlew clean check jar` passed all 17 tests.
|
||||
- Automated coverage checks scale calculation, storage reload, range exceptions, recipe shape, and enum identity. Code inspection confirms metadata authentication, ingredient registration, and the shared consumption/join/respawn adapters; no live-server gameplay test was performed.
|
||||
|
||||
## Related
|
||||
|
||||
- [US-002: Make precise stature adjustments](us-002-adjust-stature.md)
|
||||
- [US-004: Configure and persist stature behavior](us-004-configure-and-persist.md)
|
||||
@@ -1,36 +0,0 @@
|
||||
---
|
||||
type: User Story
|
||||
title: "US-007: Manage stature settings with commands"
|
||||
description: Let administrators view and persistently change stature bounds with tab-completed commands.
|
||||
status: done
|
||||
---
|
||||
|
||||
# US-007: Manage stature settings with commands
|
||||
|
||||
As a **server administrator**, I want commands with tab completion so that I can change stature limits without restarting the server.
|
||||
|
||||
## Acceptance criteria
|
||||
|
||||
- [x] `/heights settings` displays current settings; `/heights set min|max <value>` changes the selected bound.
|
||||
- [x] Operators and senders with `spigotheights.admin` may use the commands, including console; unauthorized senders cannot change settings or receive suggestions.
|
||||
- [x] Tab completion suggests subcommands, `min`/`max`, and valid example values, filtered by the typed prefix.
|
||||
- [x] Successful changes apply immediately to gameplay and persist to `plugins/SpigotHeights/config.yml` without discarding unrelated configuration.
|
||||
- [x] Invalid arguments or settings produce clear explanations and leave active and saved settings unchanged; persistence failure does not activate the new settings.
|
||||
- [x] Existing players are not immediately resized; subsequent potion use, joins, and respawns use current limits, preserving the restoration exception for `1.0`.
|
||||
- [x] Automated tests and README documentation cover commands, permissions, completion, validation, persistence, and live settings.
|
||||
|
||||
- [x] Command help and completion include the player-height subcommand without changing existing min/max command behavior.
|
||||
|
||||
## Verification
|
||||
|
||||
- Player-command extension verified with `./gradlew clean check jar` (33 passing tests), including existing settings-command regressions and new player-name/size completions.
|
||||
|
||||
- `./gradlew clean check jar` passed all 26 tests, including command execution with authorized/unauthorized generic senders, prefix-filtered valid completions, argument validation, failed saves, YAML reload/preservation, and live domain behavior.
|
||||
- Code inspection confirms command/permission registration and shared settings suppliers in consumption, join, respawn, and launcher adapters. No live-server command or client tab-completion test was performed.
|
||||
|
||||
## Related
|
||||
|
||||
- [US-008: View and set player height](us-008-manage-player-height.md)
|
||||
|
||||
- [US-004: Configure and persist stature behavior](us-004-configure-and-persist.md)
|
||||
- [US-006: Restore default stature](us-006-restore-default-stature.md)
|
||||
@@ -1,30 +0,0 @@
|
||||
---
|
||||
type: User Story
|
||||
title: "US-008: View and set player height"
|
||||
description: Let administrators inspect and persistently set online player scales through tab-completed commands.
|
||||
status: done
|
||||
---
|
||||
|
||||
# US-008: View and set player height
|
||||
|
||||
As a **server administrator**, I want to view and set a player's height so that I can manage individual stature without potions.
|
||||
|
||||
## Acceptance criteria
|
||||
|
||||
- [x] `/heights player <name>` reports the online player's scale, where `1.0` is normal size.
|
||||
- [x] `/heights player <name> <scale>` immediately applies and saves the scale by UUID for reconnects and respawns.
|
||||
- [x] Operators and senders with `spigotheights.admin` can use the commands, including console and targeting themselves.
|
||||
- [x] Tab completion suggests online player names and valid example sizes, filtered by prefix; unauthorized senders receive no suggestions.
|
||||
- [x] Values must be finite and within current configured limits, except exact `1.0` is always allowed as the restoration exception.
|
||||
- [x] Invalid input, unknown/offline players, and persistence failures produce clear messages; failed saves do not change live or cached player height.
|
||||
- [x] Automated tests and README documentation cover viewing, setting, permissions, completion, validation, and persistence.
|
||||
|
||||
## Verification
|
||||
|
||||
- `./gradlew clean check jar` passed all 33 tests. Coverage includes command routing and permissions, completion, base/effective scale reporting, live limits, the restoration exception, UUID reload, and failed-save protection for live/cached/disk state.
|
||||
- Code inspection confirms exact online lookup, scale-attribute access, shared storage with join/respawn handlers, and command registration. No live-server/client test was performed.
|
||||
|
||||
## Related
|
||||
|
||||
- [US-004: Configure and persist stature behavior](us-004-configure-and-persist.md)
|
||||
- [US-007: Manage stature settings with commands](us-007-manage-settings-commands.md)
|
||||
Reference in New Issue
Block a user