purpur-base/README.md

# Spigot Base

A Purpur 26.2 plugin providing progression-gated player bases and quality-of-life unlocks.

Players begin by breaking Survival-mode grass blocks or dirt. The progression paths provide a persistent base, navigation particles, expanding base bounds, controlled flight, personal teleportation, and visitor teleportation.

The approved behavior is specified in the [SoMC OKF wiki](https://git.garvis.dev/dmg/somc-okf/src/branch/main/projects/spigot-base/index.md).

## Requirements

- Purpur 26.2 build 2618
- Java 25 or newer

## Build

```bash
./gradlew clean check jar
```

The plugin JAR is written to `build/libs/`.

## Player commands

```text
/setbase (alias: /sethome)
/base (alias: /home)
/gotobase <player> (alias: /visit <player>)
/basesettings (alias: /homesettings)
/basesettings ui
/basesettings status
/basesettings upgrade
/basesettings pocket upgrade
/basesettings pocket flight <enable|disable>
/basesettings pocket mobs <hostile|passive> <enable|disable>
/basesettings pocket type <void|nether|overworld> <subtype>
/basesettings visitors <allowed|blocked>
/basesettings navigation <enable|disable>
/basesettings flight <enable|disable>
/basesettings border <enable|disable>
/basesettings spawnable <enable|disable>
/basesettings bossbar <enable|disable>
```

`/basesettings` and `/basesettings ui` open Minecraft's native dialog dashboard. The dashboard summarizes Base and Pocket Base progression, provides unlocked setting controls and purchase confirmations, marks unavailable controls as locked, and provides Back buttons from nested screens. `/basesettings status` retains the detailed chat report.

`/setbase` and `/sethome` require the proposed normal base center (the player's block coordinates) to be at least 100 blocks horizontally from the current world's spawn by default. Height and base radius do not affect this check; exactly the minimum is allowed. Rejection reports the remaining distance rounded up and leaves the existing base and relocation cooldown unchanged. This is a placement-only rule: existing bases are never rechecked when players move or spawn changes, and Pocket Base restrictions are unchanged.

Navigation particles appear only in the base's world and when the player is more than 25 blocks beyond the current base border.

After 250 Survival-mode block placements anywhere by default, the spawnable overlay can mark nearby dark hostile-mob spawning surfaces inside the player's base with owner-only red particles. The threshold is configurable.

`/base` has a stationary warm-up. Looking around is allowed, while movement between blocks, damage, teleportation, world changes, death, logout, and conflicting teleport commands cancel it without consuming the cooldown. Home and visitor warm-ups surround the player with nearby-visible floating particles that grow denser as departure approaches. Successful warmed-up teleports leave a cloud at the departure point that thins out over two seconds; cancellation or failure stops emission without a departure cloud.

Base IV owners can purchase and expand a persistent Pocket Base with `/basesettings pocket upgrade`. Activating a complete diamond-block portal frame inside the normal base with flint and steel opens one public entrance to the owner's grass platform in a private void world. Players and non-player living mobs can travel through the entrance and active return portal; items, projectiles, and vehicles are not transported. The owner can move the return portal by building and igniting another complete frame inside the unlocked Pocket Base boundary; only the newly activated return portal remains functional. Natural hostile and passive mob spawning is disabled by default. Owners can control each category independently with `/basesettings pocket mobs <hostile|passive> <enable|disable>`. An owner who wins a raid inside their own Pocket Base permanently unlocks owner-only Survival flight across the full build height and within the current Pocket Base boundary plus a 16-block warning buffer on every side. The owner can control that automatic privilege with `/basesettings pocket flight <enable|disable>`. After the raid unlock, the owner can ignite a complete gold-block portal frame inside the unlocked boundary; any Survival player who passes through receives temporary flight within the same boundary and buffer until leaving the Pocket Base. Entering the flight portal immediately starts the player flying and displays “Pocket dimension flight enabled!” once, without repeating while they stand inside the portal. The owner's automatic-flight preference does not affect portal-granted flight.

Pocket Base owners can also craft a reusable **Pocket Base Keystone**. Its shaped recipe uses an Ender Pearl in the center, Netherite Ingots on the four cardinal slots, and Obsidian in the four corners. Right-clicking the keystone outside a Pocket Base instantly records the player's location and takes them to their own Pocket Base. Right-clicking it again inside their own Pocket Base returns them to that exact location when the world and destination remain available and safe. Saved returns survive reconnects and server restarts. A transferred keystone only works for a player who has unlocked their own Pocket Base.

Owners can change biome metadata without altering Pocket Base blocks, entities, inventories, or portals by using `/basesettings pocket type <void|nether|overworld> <subtype>`. Void uses `the_void`; Nether and Overworld accept their compatible vanilla biome names, such as `crimson_forest` or `plains`. Each change defaults to 16 netherite blocks, is configurable, and affects applicable natural mob selection when spawning is enabled. The Pocket Base remains a void-generated normal-environment world; dimension-specific mechanics do not change.

## Administration

The `spigotbase.admin` permission is granted to server operators by default. `/homeadmin` aliases `/baseadmin`.

```text
/baseadmin status <player>
/baseadmin setlevel <player> <base|size|flight|warmup|cooldown> <level>
/baseadmin setprogress <player> <grass_dirt|stone|deepslate|obsidian|placements|total_placements|base_breaks> <amount>
/baseadmin setsetting <player> spawnable <enable|disable>
/baseadmin config <numeric-key> <value>
# e.g. /baseadmin config spawnable-overlay-unlock-placements 250
/baseadmin config minimum-spawn-distance 100
/baseadmin clearcooldown <player> [personal|visitor|all]
/baseadmin reset <player> <size|flight|warmup|cooldown>
/baseadmin reset <player> all confirm
```

`minimum-spawn-distance` is global and defaults to 100 blocks, including legacy configs without the key. It accepts whole numbers from `0` through `2147483647` (the same 32-bit representation used for spatial settings); overflow and invalid values are rejected without changes. `0` disables the spawn-distance restriction. Successful admin updates are confirmed and saved to `config.yml` for restarts, and affect only subsequent normal base placements—not existing bases. Numeric config writes run off the server tick thread using an isolated YAML snapshot and atomic replacement where supported. Live settings and the success reply change only after the write succeeds; failure leaves live settings unchanged. While a save is pending, another config update receives a retry message rather than overwriting settings with a stale snapshot. `/homeadmin` supports the same command and permission-aware key completion.

Default thresholds and durations are documented in `src/main/resources/config.yml`. Durable UUID-keyed state is stored in `plugins/SpigotBase/state.yml` using atomic replacement where supported.

## 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.