# 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": false,
        "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_damage` | `true` | Register an ECS system that cancels entity damage in hub worlds unless the victim has `DamageBypassFlags`. Keep this on for duel arenas in hub worlds. |
| `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. |

For duel arenas inside a hub world, use `disable_damage=true` and `disable_pvp=false`. Hytale needs world PvP enabled for player-vs-player damage to exist; Hub then blocks normal hub damage and lets duel victims through via `DamageBypassFlags`.

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