Towns And Nations
- By
Towns And Nations is a Hytale plugin that lets players create, manage, and expand towns and nations with territory control, alliances, and strategic warfare.
What's new
# 📋 CHANGELOG - TownsAndNations
> 🇫🇷 Version française : [CHANGELOG.fr.md](CHANGELOG.fr.md)
## Version 0.1.3 (Current Release)
> ⚠️ **Breaking change for API consumers**: several `TownService` methods now take the acting
> player's UUID and return typed results instead of booleans. See *Typed Results* below.
### 🔧 Hytale API Compatibility
The plugin no longer compiled against Hytale server `0.5.7` (24 compile errors). Fixed:
- 📦 **Vector classes moved to JOML** — `com.hypixel.hytale.math.vector.Vector3d/3f/3i` and
`math.matrix.Matrix4d` are gone, replaced by `org.joml.*`. Accessors changed too: JOML exposes
`.x` / `.x()`, never `.getX()`. (`Transform` and `Rotation3f` remain in `math.vector`.)
- 🔢 `Matrix4d.asFloatData()` no longer exists → `matrix.get(new float[16])`
- 🎨 `DisplayDebug` now expects `org.joml.Vector3fc` instead of `protocol.Vector3f`
- 💬 `Player.sendMessage(Message)` removed — message delivery lives on `PlayerRef`
### 💾 Storage — Crash Safety
- 🛡️ **New `StorageUtils`** — writes can no longer corrupt your data
- Atomic writes: unique `.tmp` file → SHA-256 checksum verified by reading back → previous
version kept as `.bak` → atomic rename (falls back to a plain move on filesystems that
reject `ATOMIC_MOVE`)
- `readWithRecovery()` falls back to the `.bak` when the target is missing **or empty** — an
empty file being the signature of an interrupted write
- `WriteResult` sealed interface: `Success(file, checksum)` / `Failure(file, error, cause)`
- 🔌 **Wired into all 5 JSON load/save pairs** — towns, nations, wars, war invitations,
diplomatic relations. A crash mid-save no longer destroys your towns.
### 🛡️ Protection
- 🐛 **Fixed plot detection** — protection resolved plots at a fake position in the *centre* of
the chunk (`chunk*32+16`, y=64) while the ECS listeners already had the exact block position
and discarded it. Any plot not covering the chunk centre was invisible to protection.
- New `PermissionService.BlockPosition` record carries the real position through
- New `Plot.intersectsChunk()` and `Town.getPlotInChunk()` as the fallback for callers that
only know the chunk — preferring an **owned** plot, since returning a free one would
silently widen permissions on a chunk that also holds someone's private plot
- 💬 **Denial messages with debounce** — blocked actions were cancelled *silently* (except PVP,
which spammed one message per damage event). All four protection systems now explain the
refusal, with a 2s cooldown per player+action pair. `DamageBlockEvent` (which fires on every
mining tick) shares its cooldown key with `BreakBlockEvent` to avoid duplicates.
- 🔑 **`townsandnations.bypass`** now short-circuits territory protection, alongside
`townsandnations.admin`
- ♻️ **Deduplication** — the three near-identical `canBreak`/`canPlace`/`canInteract` internals
merged into a single method (~120 duplicated lines removed)
### 🔐 Permissions
- ⛓️ **Provider chain** replacing the single LuckPerms lookup (new `permissions/` package)
- `PermissionProvider` returns `Optional<Boolean>`: a provider answering `false` for a player
it has never heard of would shadow every provider behind it
- `LuckPermsPermissionProvider` — maps LuckPerms `Tristate` (`UNDEFINED` → *no opinion*,
not *denied*)
- `HytaleNativePermissionProvider` — since `PermissionsModule` offers no tri-state, it is
probed twice with opposite defaults: same answers ⇒ node explicitly set, differing answers
⇒ the module is just echoing the default
- `PermissionManager` — wildcard resolution from most to least specific: `a.b.c` → `a.b.*` →
`a.*`, so a precise deny beats a broad grant
- 🏷️ **`Permissions.java`** centralises the nodes. The four existing `command.*` nodes remain
authoritative and the new fine-grained nodes fall back onto them by wildcard — **existing
server configurations keep working unchanged**
- 🔒 **Authorization moved into the service** — the GUI checked the mayor *role* but never the
*permission node*, so a mayor whose `townsandnations.command.mayor` had been revoked could
still act through the interface. Both checks now live in `TownService.authorizeTownAction()`,
used by commands and GUI alike.
### 👔 Deputies
Deputies are assistants: they handle day-to-day territory, never what would let them drain or
dismantle the town.
| Action | Mayor | Deputy |
|--------|:-----:|:------:|
| claim / unclaim | ✔ | ✔ **(new)** |
| togglePvp, togglePublic, setcolor | ✔ | ✘ |
| bank withdrawal | ✔ | ✘ |
| add / remove deputy | ✔ | ✘ |
| disband, invite, kick, sethome | ✔ | ✘ |
- Expressed by an explicit `RoleRequirement { MAYOR_ONLY, MAYOR_OR_DEPUTY }` rather than an
implicit boolean
- Deputies can now open `/town mayor gui` for the claim map; the page hides settings and the
danger zone from them. Security still comes from the service — hiding buttons is only comfort.
- ℹ️ Deputies need the `townsandnations.command.mayor` node (or the fine-grained
`...mayor.claim` / `...mayor.unclaim`) for the commands to pass the command-level check.
### 🧩 Public API (new)
Other mods can now query, observe and veto TownsAndNations actions. See [docs/API.md](docs/API.md).
- 📡 **`EventBus`** — `register` / `unregister` / `publish` / `publishCancellable` / `clearAll`.
Listener exceptions are logged and isolated; the listener list is copied before iteration so a
listener may (un)register another without breaking the loop.
- 📨 **7 post-events**: `TownCreateEvent`, `TownDisbandEvent`, `TownClaimEvent`,
`TownUnclaimEvent` (reason `UNCLAIM` / `DISBAND`), `TownMemberEvent`, `NationCreateEvent`,
`NationDisbandEvent`
- 🚫 **3 cancellable pre-events**: `TownCreatePreEvent`, `TownClaimPreEvent`,
`TownDisbandPreEvent`. Published after internal validation but **before any state change** —
cancelling costs the town nothing, notably no bank withdrawal.
- 🔗 **`TownsAndNationsAPI`** — `isAvailable()`, town/nation/territory/plot queries, `canBuild()`
### ⚙️ Typed Results (breaking)
Callers used to **re-run the checks after the fact** to guess why an action failed ("is the
balance too low? is the limit reached?"). That reports the wrong reason as soon as state moves in
between, and could not distinguish a third-party mod cancellation at all.
```java
ClaimResult : SUCCESS, TOWN_NOT_FOUND, NO_PERMISSION, NOT_MAYOR, ALREADY_CLAIMED,
MAX_CHUNKS_REACHED, CITIZEN_LIMIT_REACHED, NOT_ADJACENT,
INSUFFICIENT_FUNDS, CANCELLED
UnclaimResult : SUCCESS, TOWN_NOT_FOUND, NO_PERMISSION, NOT_MAYOR, NOT_OWNED,
IS_HOME_CHUNK, LAST_CHUNK, WOULD_DISCONNECT
```
Changed signatures:
| Before | After |
|--------|-------|
| `claimChunk(townUuid, chunk)` → `Boolean` | `claimChunk(townUuid, chunk, actorUuid)` → `ClaimResult` |
| `unclaimChunk(townUuid, chunk)` → `Boolean` | `unclaimChunk(townUuid, chunk, actorUuid)` → `UnclaimResult` |
| `disbandTown(townUuid)` → `Void` | `disbandTown(townUuid, actorUuid)` → `Boolean` |
| `togglePvp(townUuid)` → `Boolean` | `togglePvp(townUuid, actorUuid)` → `Boolean` (null = denied) |
| `addDeputy(townUuid, playerUuid)` | `addDeputy(townUuid, playerUuid, actorUuid)` |
| `removeDeputy(townUuid, playerUuid)` | `removeDeputy(townUuid, playerUuid, actorUuid)` |
All 12 call sites now `switch` on the result.
### 🏛️ Nation Interface
- 🎨 **NationMenuPage reworked** into a dashboard, with `NationDashboardPage.ui` and a dedicated
`NationNavBar.ui` navigation bar
- 🧭 Navigation added between the nation pages
### 🗺️ Map
- 🎨 **Improved claim rendering** — `ClaimImageBuilder` now accounts for fluid particle colour,
environment water tint and block tint when generating the map image
### 🌐 Internationalization
- 🇬🇧🇫🇷 **12 new keys** in both languages: protection denials, cancellations by a third-party
mod, already-claimed chunk
### 🧹 Code Quality
- ✅ `@Nonnull` annotations enforced across commands and GUI components
- 📦 `manifest.json` reformatted; `ServerVersion` now uses the `^${hytale_build}` placeholder
resolved at build time
- 🏗️ `updatePluginManifest` build task reworked
### 📄 Documentation
- 📘 **[docs/API.md](docs/API.md)** — full public API reference
### 🔜 Not Yet Implemented
Admin SafeZone/WarZone, broader ECS coverage (item drop/pickup, death, respawn, mounts, NPCs),
per-UUID storage locks, GFS backups, versioned migrations, taxes/upkeep/debt, per-town and
per-plot permission matrix, town chat, outposts, town levels, PAPI placeholders.
All Relations
- All Relations
- Embedded Library
- Optional Dependency
- Required Dependency
- Tool
- Incompatible
- Include
