spigot-heights/README.md

Spigot Heights

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.

Requirements

• Purpur 26.2 build 2618
• Java 25 or newer

Potions

Potion of Shifting Stature

Amethyst Shard | Chorus Fruit   | Amethyst Shard
Amethyst Shard | Awkward Potion | Amethyst Shard
Amethyst Shard | Chorus Fruit   | Amethyst Shard

Drinking it chooses a random configured scale in 0.1 increments.

Potion of Growth

Gold Ingot | Amethyst Shard             | Gold Ingot
Amethyst   | Potion of Shifting Stature | Amethyst
Gold Ingot | Rabbit's Foot              | Gold Ingot

Potion of Diminution

Use the Growth recipe with a Fermented Spider Eye instead of the Rabbit's Foot. Growth and Diminution adjust scale by one configured step and clamp at the limits.

Potion of Restoration

Gold Ingot     | Amethyst Shard             | Gold Ingot
Amethyst Shard | Potion of Shifting Stature | Amethyst Shard
Gold Ingot     | Sugar                      | Gold Ingot

Produces one Potion of Restoration. Drinking it restores scale to exactly 1.0 (normal size), even outside configured limits. This size is saved across reconnects, respawns, and server restarts. Other saved scales are still clamped to the configured range.

Tiny-player launchers

A player below the configured scale threshold can walk onto a hopper whose output points into a dispenser. If the block in front of that dispenser is passable, the player is moved there and launched in the direction the dispenser faces. The launcher does not require redstone.

Configuration

Defaults are in src/main/resources/config.yml:

height:
  minimum: 0.4
  maximum: 2.0
  adjustment-step: 0.1
launcher:
  maximum-player-scale-exclusive: 0.5
  speed: 1.5
  cooldown-ticks: 20

Player scales are stored by UUID in plugins/SpigotHeights/state.yml.

Commands

Operators (or senders granted spigotheights.admin) can use:

/heights settings
/heights set min 0.2
/heights set max 3.0

Console is supported. Tab completion suggests subcommands, bound names, and valid example values; other valid numbers may also be entered.

Changes are saved to plugins/SpigotHeights/config.yml and take effect without a restart. Minimum must be at least 0.0625, maximum at most 16.0, minimum cannot exceed maximum, and the launcher threshold must remain within the range. Invalid changes or save failures leave active settings unchanged.

Players are not immediately resized. Subsequent potion use, joins, and respawns use the new limits; Restoration still returns and preserves exact scale 1.0. These commands only change min/max; edit other settings in the configuration file and restart the server.

Build

./gradlew clean check jar

The plugin JAR is written to build/libs/.

Releases

Gitea Actions checks pushes and pull requests and stores a development JAR. Pull requests validate conventional commits. Main-branch conventional commits drive semantic releases when the repository defines a RELEASE_TOKEN with contents-write permission.