init

2026-05-26 23:18:17 -04:00
commit b2a780064d
18 changed files with 906 additions and 0 deletions
@@ -0,0 +1,83 @@
+# Configuration
+
+## Location
+
+`<plugin data dir>/config.json`. Written with defaults on first boot.
+
+## Full config
+
+```json
+{
+    "worlds": {
+        "hub_worlds": []
+    },
+    "protection": {
+        "disable_block_break": true,
+        "disable_block_place": true,
+        "disable_block_damage": true,
+        "disable_pvp": true,
+        "disable_fall_damage": true,
+        "apply_world_config": true
+    },
+    "messages": {
+        "welcome": "Welcome to the hub, {player}!",
+        "join_announcement": "{player} joined the hub.",
+        "leave_announcement": ""
+    },
+    "spawn": {
+        "teleport_on_join": true
+    }
+}
+```
+
+## Fields
+
+### worlds
+
+| Field | Default | Meaning |
+|---|---|---|
+| `hub_worlds` | `[]` | World names this plugin treats as hubs. **Empty = every world this server hosts is treated as a hub.** Most hub servers run one world, so empty is fine. If you have multiple worlds and only some are hubs, list the hub names here. |
+
+### protection
+
+| Field | Default | Meaning |
+|---|---|---|
+| `disable_block_break` | `true` | Register an ECS system that cancels `BreakBlockEvent` in hub worlds. Players cannot mine blocks. |
+| `disable_block_place` | `true` | Register an ECS system that cancels `PlaceBlockEvent` in hub worlds. Players cannot place blocks. |
+| `disable_block_damage` | `true` | Register an ECS system that cancels `DamageBlockEvent` in hub worlds. Blocks cannot be damaged (the partial-damage step before a break). |
+| `disable_pvp` | `true` | Apply `WorldConfig.setPvpEnabled(false)` on the hub world. Players can't damage each other. |
+| `disable_fall_damage` | `true` | Apply `WorldConfig.setFallDamageEnabled(false)`. Players don't take fall damage. |
+| `apply_world_config` | `true` | Master toggle for the world-flag application (PvP + fall damage). Set false if you want to manage these flags yourself in Hytale's world config and have Hub leave them alone. Does NOT affect the ECS block protections - toggle those individually via the `disable_block_*` flags. |
+
+> Note: Hytale's `GameMode` only has `Adventure` and `Creative`. `Adventure` is the equivalent of Minecraft's *Survival* (players can still break/place). There is no gamemode that prevents block actions, which is why hub protection uses ECS event cancellation instead.
+
+### messages
+
+| Field | Default | Meaning |
+|---|---|---|
+| `welcome` | `"Welcome to the hub, {player}!"` | Sent privately to the joining player on `PlayerReadyEvent`. `{player}` is replaced with their username. Empty/null disables. |
+| `join_announcement` | `"{player} joined the hub."` | **Replaces** Hytale's built-in join broadcast on `AddPlayerToWorldEvent`. `{player}` is replaced. Empty/null suppresses the broadcast entirely (no replacement and no default). |
+| `leave_announcement` | `""` (empty) | **Replaces** Hytale's built-in leave broadcast on `RemovedPlayerFromWorldEvent`. `{player}` is replaced. Default is empty so no leave message is shown - staff plugin handles network-wide leave announcements. Set to e.g. `"{player} left the hub."` if you want a per-server leave line. |
+
+### spawn
+
+| Field | Default | Meaning |
+|---|---|---|
+| `teleport_on_join` | `true` | On `PlayerReadyEvent`, teleport the player to the world's spawn point. The spawn point comes from `WorldConfig.getSpawnProvider().getSpawnPoint(...)` - same source Hytale uses for new players. |
+
+## Recommended setups
+
+**Single-world dedicated hub server (most common):**
+- Defaults are fine. `hub_worlds: []` means "everything on this server is a hub".
+
+**Multi-world server where only one world is a hub:**
+- `hub_worlds: ["lobby"]` (or whatever your hub world is named).
+- Other worlds are unaffected by protection / spawn-on-join / messages.
+
+**Hub world managed entirely outside this plugin:**
+- `protection.apply_world_config: false` to leave the world's PvP/fall flags alone.
+- `protection.disable_block_*: false` to leave block events alone.
+- Hub will still do welcome message + spawn-on-join + join/leave message replacement.
+
+**Allow building in the hub (e.g. for staff):**
+- Hytale's permission system would need a per-player override; this plugin cancels at the world level, not per-player. If you want admins-can-build behavior, that needs a small change to the protection systems to check a permission node before cancelling.