ez-plugins · ez-plugins · May 24, 2026 · May 19, 2026 · May 24, 2026 · May 24, 2026
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -20,6 +20,52 @@ Release tags use the `v` prefix (e.g. `v3.0.2`).
 
 ---
 
+## [3.4.0] - 2026-05-24
+
+### Added
+
+- **EzCountdown integration** (optional soft-dependency):
+  - RTP countdown display can now be delegated to [EzCountdown](https://modrinth.com/plugin/ezcountdown) for richer, configurable display channels.
+  - Configurable display types per RTP world: `ACTION_BAR`, `BOSS_BAR`, `TITLE`, `CHAT`, `SCOREBOARD`, `DIALOG`.
+  - Configurable MiniMessage format string with `{formatted}` placeholder for remaining time.
+  - Each teleporting player receives an ephemeral, per-player countdown with permission-scoped visibility.
+  - Falls back to the built-in bossbar/chat countdown automatically when EzCountdown is absent or `ezcountdown.enabled: false`.
+  - New `countdown.ezcountdown.*` config section in `rtp.yml` (disabled by default).
+- `EzCountdown` added as optional soft-dependency in `plugin.yml`.
+- **Factions RTP (TeamsAPI)**:
+  - Added `/rtp faction` to open a claim-selection GUI from all TeamsAPI claims available to the player's team.
+  - Added TeamsAPI subcommand integration for `/f rtp` via the TeamsAPI subcommand API (when provided by the installed TeamsAPI version).
+  - Claim selection now sets the selected claim chunk as RTP center and then applies normal per-world RTP behavior/settings.
+- **New `faction-gui.yml` file** for full claim-GUI configuration.
+- **Heatmap claim overlays** (admin insight):
+  - Added claim border overlay mode for `/rtp heatmap` and `/rtp heatmap save` via `claims-overlay` flag.
+  - Added `rtp.yml` options under `heatmap.claims-overlay.*`:
+    - `enabled`
+    - `style` (`border`)
+    - `color`
+    - `line-width`
+- **Claim-constrained fake RTP simulation**:
+  - Added `/rtp fake <amount> claims [world]` to generate simulated points on faction claims owned by the executor’s team.
+
+### Changed
+
+- **TeamsAPI** dependency bumped from `1.4.1` to `1.8.0`.
+- TeamsAPI `/f rtp` subcommand integration rewritten: replaced the reflection-based `Proxy` approach with a proper `AbstractTeamsSubcommand` subclass (requires TeamsAPI ≥ 1.8.0).
+- TeamsAPI subcommand registration now uses an explicit `isPluginEnabled("TeamsAPI")` guard instead of relying on `NoClassDefFoundError` suppression.
+- Faction claim GUI icons now attempt to use player skulls when claimant/owner identity is available, with configurable fallback material when unavailable.
+- Added configurable title, size, claim item format/lore, skull toggle, and navigation slot/name settings for faction GUI pages.
+- Update checker refactored to use `mc-plugin-update-notifier` with Modrinth as primary source and GitHub Releases as fallback source.
+
+### Fixed
+
+- Heatmap enablement now resolves correctly for inherited/fallback world settings (`heatmap.enabled`) and no longer reads as disabled unexpectedly in world/GUI override paths.
+- `/rtp heatmap` no longer hard-requires biome cache for non-biome heatmaps. Biome cache is only required for biome-filtered heatmap requests.
+- Spigot startup compatibility fixed in update checking (`JavaPlugin#getDescription().getVersion()` used instead of Paper-only metadata calls).
+- Message loading now supports both top-level keys and nested `messages.*` language-file layouts.
+- Language file handling is now non-destructive: startup repair only targets clearly corrupted message files, with automatic backfill of missing message keys while preserving existing translations/customizations.
+
+---
+
 ## [3.3.0] - 2026-05-16
 
 ### Added

diff --git a/README.md b/README.md
@@ -44,8 +44,9 @@ It is designed for **safety-first teleportation**, **cross-platform compatibilit
 - **Queue system** to smooth heavy RTP usage on busy servers.
 - **Biome-aware and cache-assisted searching** with optional rare-biome optimization.
 - **Heatmap/statistics tooling** for operators to inspect RTP distribution and performance.
+- **Release update notifier** using free APIs with Modrinth primary and GitHub Releases fallback.
 - **WorldGuard region command mode** for region-scoped RTP entry points.
-- **TeamsAPI integration** to skip chunk-claimed areas (works with any TeamsAPI-compatible team plugin).
+- **TeamsAPI integration** to skip chunk-claimed areas and power faction-claim RTP selection (works with any TeamsAPI-compatible team plugin).
 - **Optional first-join/on-join teleport flow**.
 - **Optional proxy/network destination menu support** for multi-server setups.
 - **Chunky integration** for pre-generation workflows.
@@ -95,13 +96,17 @@ It is designed for **safety-first teleportation**, **cross-platform compatibilit
 ### Player commands
 
 - `/rtp` - Random teleport (or opens GUI when enabled).
+- `/rtp faction` - Open faction/team claim selection GUI (TeamsAPI), then RTP around the selected claim center.
+- `/f rtp` - TeamsAPI faction subcommand route to the same claim selection GUI.
 
 ### Admin / utility subcommands
 
 - `/rtp reload` - Reload plugin configuration.
 - `/rtp stats` - Show RTP statistics and performance details.
 - `/rtp heatmap` - View heatmap information.
 - `/rtp fake <amount|clear> [world]` - Inject/clear simulated heatmap points.
+- `/rtp heatmap claims-overlay` - Render heatmap with TeamsAPI claim chunk borders (admin-scoped).
+- `/rtp fake <amount> claims [world]` - Inject simulated heatmap points constrained to your faction claims.
 - `/rtp setcenter <x> <z>` or `/rtp setcenter <world> <x> <z>` - Update RTP center.
 - `/rtp pregenerate [world] [radius]` - Trigger Chunky-assisted pre-generation workflow.
 - `/forcertp <player> [world]` - Force teleport a target player.
@@ -118,6 +123,7 @@ It is designed for **safety-first teleportation**, **cross-platform compatibilit
 - `ezrtp.stats` - Access `/rtp stats`.
 - `ezrtp.heatmap` - Access `/rtp heatmap`.
 - `ezrtp.heatmap.fake` - Access `/rtp fake`.
+- `ezrtp.heatmap.claims` - Access claim overlay rendering on heatmaps.
 - `ezrtp.queue.bypass` - Bypass queue restrictions.
 
 ### Permissions Reference
@@ -152,9 +158,12 @@ EzRTP splits configuration into focused files for maintainability:
 - `storage.yml` - Usage/cooldown backend (YAML/MySQL).
 - `queue.yml` - Queue throttling behavior.
 - `gui.yml` - GUI menu layout, world entries, and icons.
+- `faction-gui.yml` - Faction claim GUI layout/icons/navigation for `/rtp faction` and `/f rtp`.
 - `network.yml` - Proxy/server destination entries.
 - `force-rtp.yml` - `/forcertp` command behavior.
 - `messages/*.yml` - Localized messages.
+  - Supports both top-level keys and `messages.*` nested layout.
+  - Missing keys are backfilled automatically on startup without overwriting existing translations.
 
 ---
 
@@ -210,6 +219,7 @@ Configuration and message references in this repository:
 - Limits and cooldowns: [`limits.yml`](src/main/resources/limits.yml)
 - Queue settings: [`queue.yml`](src/main/resources/queue.yml)
 - GUI settings: [`gui.yml`](src/main/resources/gui.yml)
+- Faction GUI settings: [`faction-gui.yml`](src/main/resources/faction-gui.yml)
 - Network/proxy settings: [`network.yml`](src/main/resources/network.yml)
 - Storage backend config: [`storage.yml`](src/main/resources/storage.yml)
 - Force RTP behavior: [`force-rtp.yml`](src/main/resources/force-rtp.yml)
@@ -220,6 +230,7 @@ Configuration documentation files:
 
 - Main config documentation: [`docs/config/config.md`](docs/config/config.md)
 - Core configuration reference (`config.yml`, `rtp.yml`, `limits.yml`, `storage.yml`, `force-rtp.yml`): [`docs/config-core-reference.md`](docs/config-core-reference.md)
+- Faction GUI config reference: [`docs/config/faction-gui.md`](docs/config/faction-gui.md)
 - GUI/queue/network reference (`gui.yml`, `queue.yml`, `network.yml`): [`docs/config-gui-queue-network-reference.md`](docs/config-gui-queue-network-reference.md)
 
 - Integration docs:

diff --git a/docs/commands.md b/docs/commands.md
@@ -10,6 +10,12 @@ nav_order: 3
 - `/rtp`
   - Opens GUI when GUI is enabled.
   - Falls back to direct teleport when GUI is disabled or unavailable.
+- `/rtp faction`
+  - Opens a faction/team claim GUI using TeamsAPI claims.
+  - Selecting a claim uses that claim chunk center and then applies normal configured RTP behavior for that world.
+  - GUI layout and item rendering are configured in `faction-gui.yml`.
+- `/f rtp`
+  - TeamsAPI subcommand integration that opens the same faction/team claim GUI as `/rtp faction`.
 - `/rtp <centerName>`
   - Teleports using the named center configured under `centers.named` in `rtp.yml`.
   - Named center is applied as a center override only; the world's normal RTP settings still apply.
@@ -25,8 +31,11 @@ nav_order: 3
 - `/rtp stats rare-biomes [page]`
 - `/rtp heatmap [biome]`
 - `/rtp heatmap save`
+- `/rtp heatmap claims-overlay`
+- `/rtp heatmap save claims-overlay`
 - `/rtp fake <amount> [world]`
 - `/rtp fake clear [world]`
+- `/rtp fake <amount> claims [world]`
 - `/rtp setcenter <x> <z>`
 - `/rtp setcenter <world> <x> <z>`
 - `/rtp addcenter <name>`
@@ -53,8 +62,11 @@ This centers RTP around the specified WorldGuard region and can apply per-region
 - Stats: `/rtp stats`
 - Biome stats: `/rtp stats biomes`
 - Heatmap map item: `/rtp heatmap`
+- Heatmap map + claim overlay: `/rtp heatmap claims-overlay`
 - Save heatmap image: `/rtp heatmap save`
+- Save heatmap with claim overlay: `/rtp heatmap save claims-overlay`
 - Add fake points: `/rtp fake 100 world`
+- Add fake points on your faction claims: `/rtp fake 100 claims`
 - Clear fake points: `/rtp fake clear world`
 - Set RTP center (current world): `/rtp setcenter 0 0`
 - Save a named center from your current position: `/rtp addcenter spawn`
diff --git a/docs/config-core-reference.md b/docs/config-core-reference.md
@@ -45,6 +45,12 @@ This file documents `config.yml` and `force-rtp.yml`.
 - `countdown.particles.secondary-offset`
 - `countdown.chat-messages`
 
+### EzCountdown integration
+
+- `countdown.ezcountdown.enabled`
+- `countdown.ezcountdown.display-types`
+- `countdown.ezcountdown.format`
+
 ### Safety
 
 - `unsafe-blocks`

diff --git a/docs/config/faction-gui.md b/docs/config/faction-gui.md
@@ -0,0 +1,44 @@
+---
+title: faction-gui.yml
+nav_order: 5
+parent: Config Reference
+---
+
+# faction-gui.yml
+
+Configures the faction/team claim selection GUI used by `/rtp faction` and `/f rtp`.
+
+## Top-level settings
+
+| Key | Default | Description |
+| :--- | :--- | :--- |
+| `enabled` | `true` | Enables faction claim GUI routing. |
+| `title` | `Faction RTP Claims (<page>/<pages>)` | GUI title. Supports `<page>` and `<pages>`. |
+| `size` | `54` | Inventory size (multiple of 9, up to 54). |
+
+## Claim item settings
+
+| Key | Default | Description |
+| :--- | :--- | :--- |
+| `items.claim.use-player-skulls` | `true` | Uses player skulls for claim owner/claimer when identity is available. |
+| `items.claim.fallback-material` | `GRASS_BLOCK` | Used when skull identity is unavailable. |
+| `items.claim.name` | `Claim #<index>` | Item display name. |
+| `items.claim.lore` | *(see default file)* | Lore lines with placeholders. |
+
+Supported placeholders:
+
+- `<index>`
+- `<world>`
+- `<chunk_x>`
+- `<chunk_z>`
+- `<center_x>`
+- `<center_z>`
+
+## Navigation settings
+
+| Key | Default | Description |
+| :--- | :--- | :--- |
+| `navigation.previous.slot` | `45` | Previous page button slot. |
+| `navigation.previous.name` | `Previous Page` | Previous page button name. |
+| `navigation.next.slot` | `53` | Next page button slot. |
+| `navigation.next.name` | `Next Page` | Next page button name. |
diff --git a/docs/config/index.md b/docs/config/index.md
@@ -8,3 +8,18 @@ has_children: true
 
 EzRTP uses a set of focused configuration files. Browse the pages below for
 full details on each file.
+
+- `config.yml`
+- `rtp.yml`
+- `limits.yml`
+- `storage.yml`
+- `gui.yml`
+- `faction-gui.yml`
+- `queue.yml`
+- `network.yml`
+- `messages/*.yml` (top-level keys and nested `messages.*` keys are both supported)
+
+Notes:
+
+- Missing message keys in language files are backfilled automatically on startup.
+- Existing translated/customized message values are preserved during backfill.
diff --git a/docs/config/rtp.md b/docs/config/rtp.md
@@ -94,6 +94,27 @@ countdown:
   chat-messages: false
 ```
 
+### EzCountdown display (optional)
+
+When [EzCountdown](../integrations/ezcountdown) is installed, EzRTP can delegate
+the countdown display to it for richer, configurable channels.
+
+| Key | Default | Description |
+| :--- | :--- | :--- |
+| `countdown.ezcountdown.enabled` | `false` | Hand countdown display off to EzCountdown. Falls back to the built-in display when `false` or when EzCountdown is absent. |
+| `countdown.ezcountdown.display-types` | `[ACTION_BAR, BOSS_BAR]` | Display channels EzCountdown renders. Accepted values: `ACTION_BAR`, `BOSS_BAR`, `TITLE`, `CHAT`, `SCOREBOARD`, `DIALOG`. |
+| `countdown.ezcountdown.format` | `<yellow>Teleporting in <white>{formatted}</white>...</yellow>` | MiniMessage string shown by each active display channel. `{formatted}` is replaced with the remaining time. |
+
+```yml
+countdown:
+  ezcountdown:
+    enabled: false
+    display-types:
+      - ACTION_BAR
+      - BOSS_BAR
+    format: "<yellow>Teleporting in <white>{formatted}</white>...</yellow>"
+```
+
 ---
 
 ## Safety

diff --git a/docs/integrations/ezcountdown.md b/docs/integrations/ezcountdown.md
@@ -0,0 +1,112 @@
+---
+title: EzCountdown
+nav_order: 6
+parent: Integrations
+---
+
+# EzCountdown Integration
+
+Use this integration when you want to show the RTP countdown using
+[EzCountdown](https://modrinth.com/plugin/ezcountdown) display effects instead
+of (or alongside) the built-in bossbar. EzCountdown supports more display
+channels and richer formatting.
+
+## What this integration does
+
+When EzCountdown is installed and the integration is enabled in `rtp.yml`,
+EzRTP delegates its per-player countdown display to EzCountdown rather than
+rendering a bossbar/chat message itself. Each teleporting player receives an
+ephemeral, private countdown that expires when the teleport fires or is
+cancelled.
+
+- Movement detection and PvP cancellation still apply exactly as with the
+  built-in countdown.
+- If EzCountdown is absent or `ezcountdown.enabled: false`, EzRTP falls back to
+  its own bossbar/chat countdown automatically.
+- The integration is activated once per server start when EzCountdown is
+  detected; a `/rtp reload` restarts the display settings but does not
+  re-initialize the bridge.
+
+## Requirements
+
+| Plugin | Where to get it |
+| :--- | :--- |
+| [EzCountdown](https://modrinth.com/plugin/ezcountdown) | Modrinth · [GitHub](https://github.com/ez-plugins/EzCountdown) |
+
+EzCountdown is a soft dependency — servers without it work normally with the
+built-in display.
+
+## Where to configure it
+
+File: `plugins/EzRTP/rtp.yml`, nested under `countdown:`
+
+```yml
+countdown:
+  # ... existing built-in countdown settings ...
+  ezcountdown:
+    enabled: false
+    display-types:
+      - ACTION_BAR
+      - BOSS_BAR
+    format: "<yellow>Teleporting in <white>{formatted}</white>...</yellow>"
+```
+
+### Key settings
+
+- `enabled`
+  - `true`: hand countdown display off to EzCountdown (built-in display is
+    skipped for players where EzCountdown starts successfully).
+  - `false`: use the built-in bossbar/chat display (default).
+- `display-types`
+  - One or more display channels EzCountdown renders simultaneously.
+  - See [Display types](#display-types) below for all valid values.
+- `format`
+  - MiniMessage string shown by each active display channel.
+  - `{formatted}` is replaced with the remaining time in human-readable form
+    (e.g. `5s`, `1m 30s`).
+
+## Display types
+
+The following values are accepted in the `display-types` list:
+
+| Value | Where it appears |
+| :--- | :--- |
+| `ACTION_BAR` | Above the hotbar |
+| `BOSS_BAR` | Bar across the top of the screen |
+| `TITLE` | Large centre-screen overlay |
+| `CHAT` | Chat messages |
+| `SCOREBOARD` | Sidebar scoreboard |
+| `DIALOG` | Dialogue box (requires server support) |
+
+You can combine any number of them. Example showing three at once:
+
+```yml
+display-types:
+  - ACTION_BAR
+  - BOSS_BAR
+  - TITLE
+```
+
+## Startup log
+
+When EzCountdown is detected, EzRTP prints one line during enable:
+
+```text
+[EzRTP] EzCountdown integration enabled.
+```
+
+If EzCountdown is not installed, nothing is printed and the built-in countdown
+is used without any configuration change.
+
+## Interaction with the built-in countdown
+
+The built-in countdown settings (`countdown.bossbar`, `countdown.chat-messages`,
+`countdown.particles`, etc.) remain active for all display that does **not** go
+through EzCountdown. When `ezcountdown.enabled: true`:
+
+- The EzCountdown display replaces the EzRTP bossbar for that player.
+- Particle effects (if configured) still run independently.
+- Movement cancellation and warn-distance checks still apply.
+
+If EzCountdown fails to start a countdown for a player for any reason, EzRTP
+falls back to its built-in display for that player.
diff --git a/docs/integrations/index.md b/docs/integrations/index.md
@@ -16,4 +16,5 @@ set up each one.
 | [Chunky](chunky) | Chunky (world pre-generation) |
 | [Protection](protection-worldguard-griefprevention) | WorldGuard, GriefPrevention, TeamsAPI |
 | [PvP Tag](pvp-tag) | CombatLogX, PvPManager, Simple Combat Log |
+| [EzCountdown](ezcountdown) | EzCountdown (countdown display) |
 | [Network / Proxy](network-proxy) | BungeeCord / Velocity proxy destinations |