88 lines
9.1 KiB
Markdown
88 lines
9.1 KiB
Markdown
# 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/`. `check` includes native label packet tests against the SHA-256-verified Purpur 2618 runtime. The build downloads/patches that runtime under `build/label-runtime/`, loads its registries, and exercises codecs without starting a listening Minecraft server.
|
|
|
|
## 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.
|
|
|
|
Visitors see private floating `Base: <owner>` labels above recorded normal-base centers, inside the actual base bounds and up to 16 blocks beyond the horizontal boundary (within the same world and vertical limits). Labels do not follow the visitor. On entry, the visitor briefly sees `Entering <owner>'s base` in their action bar. Standing inside or jittering across an edge does not repeat the message; leaving the vicinity rearms it. Coincident anchors use stable vertical spacing. Ownership comes from saved player names, with a UUID fallback, so offline owners and blocked visitor teleports do not hide nearby bases or grant teleport access.
|
|
|
|
Labels use client-only text displays with server-reserved IDs; they are never added to the world and do not load anchor chunks. Movement updates visibility, while a five-tick read-only refresh catches relocation, resets and boundary changes. Leaving range, disconnecting, changing worlds, respawning and disabling the plugin clean up label/session state. This is separate from owner-only borders and excludes Pocket Bases. An unsupported native packet layout is logged explicitly without disabling unrelated base features.
|
|
|
|
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.
|