# 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](design/index.md).

## Requirements

- Purpur 26.2 build 2618
- Java 25 or newer

## Potions

### Potion of Shifting Stature

```text
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

```text
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

```text
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`:

```yaml
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:

```text
/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

```bash
./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.