Release VelocityNavigator 4.4.0

.github/workflows/build.yml

@@ -22,7 +22,9 @@ jobs:
   build:
     runs-on: ubuntu-latest
     permissions:
-      contents: write
+      contents: read
+    outputs:
+      version: ${{ steps.version.outputs.version }}
 
     steps:
       - name: Checkout
@@ -49,17 +51,78 @@ jobs:
           name: VelocityNavigator-${{ steps.version.outputs.version }}
           path: target/VelocityNavigator-*.jar
 
+  velocity4-compatibility:
+    needs: build
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Java 25
+        uses: actions/setup-java@v4
+        with:
+          java-version: '25'
+          distribution: 'temurin'
+          cache: maven
+
+      - name: Verify against Velocity 4 API
+        run: mvn clean verify -Pvelocity4-compat --batch-mode --no-transfer-progress
+
+      - name: Download release-candidate universal JAR
+        uses: actions/download-artifact@v4
+        with:
+          name: VelocityNavigator-${{ needs.build.outputs.version }}
+          path: target/velocity4-smoke/plugins
+
+      - name: Smoke test release-candidate JAR on Velocity 4.0.0
+        shell: bash
+        run: |
+          set -euo pipefail
+          version='${{ needs.build.outputs.version }}'
+          mkdir -p target/velocity4-smoke/plugins
+          curl --fail --location --silent --show-error \
+            'https://fill-data.papermc.io/v1/objects/4540289f48c83e305fc2f2c495a84d1f4d0b7f360830251e169dd5a208740e70/velocity-4.0.0-6.jar' \
+            --output target/velocity4-smoke/velocity.jar
+          echo '4540289f48c83e305fc2f2c495a84d1f4d0b7f360830251e169dd5a208740e70  target/velocity4-smoke/velocity.jar' | sha256sum --check
+          test -f "target/velocity4-smoke/plugins/VelocityNavigator-${version}.jar"
+          cd target/velocity4-smoke
+          { sleep 10; echo 'vn status'; sleep 2; echo 'shutdown'; } | timeout 45s java -Xms128M -Xmx512M -jar velocity.jar > velocity4.log 2>&1
+          cat velocity4.log
+          grep -F 'Booting up Velocity 4.0.0' velocity4.log
+          grep -F "Loaded plugin velocitynavigator ${version}" velocity4.log
+          grep -F "VelocityNavigator v${version} enabled" velocity4.log
+          grep -F 'Done (' velocity4.log
+
+  release:
+    needs: [build, velocity4-compatibility]
+    if: ${{ github.event_name == 'workflow_dispatch' && inputs.create_release }}
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Download verified release JAR
+        uses: actions/download-artifact@v4
+        with:
+          name: VelocityNavigator-${{ needs.build.outputs.version }}
+          path: release-artifacts
+
       - name: Extract Release Notes
         run: |
           awk '/^## \[/{if (p) exit; p=1; print; next} p' CHANGELOG.md > release_notes.md
 
       - name: Create GitHub Release
-        if: ${{ github.event_name == 'workflow_dispatch' && inputs.create_release }}
         uses: softprops/action-gh-release@v2
         with:
-          tag_name: v${{ steps.version.outputs.version }}
-          name: VelocityNavigator v${{ steps.version.outputs.version }}
+          tag_name: v${{ needs.build.outputs.version }}
+          name: VelocityNavigator v${{ needs.build.outputs.version }}
           body_path: release_notes.md
-          files: target/VelocityNavigator-*.jar
+          files: release-artifacts/VelocityNavigator-*.jar
           draft: false
           prerelease: ${{ inputs.prerelease }}

CHANGELOG.md

@@ -5,6 +5,34 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ---
 
+## [4.4.0] - Unreleased
+
+### Added
+
+- Added verified Velocity 4.0.0 support while retaining the Java 17 bytecode and Velocity 3.4 API baseline used by Velocity 3.4.x and 3.5.x installations. A Java 25/API 4/Adventure 5 compatibility build and a Velocity 4.0.0 startup smoke test now guard the same JAR in CI.
+- Added optional per-server `display_name` values in `gui.toml`. A name such as `lobby1` in `velocity.toml` can now appear as `Main Lobby 1` in the Java inventory, Java chat selector, and Bedrock form.
+- Added optional per-server `description`, `menu_order`, and `show_in_menu` values. Descriptions are available through `{description}`, explicit menu order is shared by all selectors, and hidden entries remain eligible for automatic routing.
+- Added selector placeholders for presentation and diagnostics: `{server}` and `{display_name}` resolve to the configured alias, `{server_id}` exposes the raw Velocity server ID, and `{description}` resolves to the shared menu description.
+- Added `/vn menu validate` to audit selector server IDs, duplicate display names, slots, material-identifier syntax, and curly-brace placeholders before players open a menu.
+- Added global Java inventory styles for `[states.full]`, `[states.draining]`, `[states.offline]`, and `[states.in_game]`, each with optional `material`, `name`, and `lore` overrides.
+
+### Changed
+
+- Inventory navigation controls are now kept in the reserved bottom row for every supported `layout.rows` value. This prevents an automatic server item from occupying a custom control slot and silently hiding that control.
+- Bedrock `sort_mode = "name"` now sorts by the displayed alias instead of the raw server ID.
+- Explicit nonnegative `menu_order` values are the primary order in Java inventory, Java chat, and Bedrock selectors. Unset values keep the existing candidate order; Bedrock uses its configured `sort_mode` to resolve equal ordering values.
+- `show_in_menu = false` removes a server from all three selectors without draining it or removing it from automatic routing.
+- Blank or missing aliases fall back to the raw server ID. Selector changes are applied by `/vn reload`; no proxy restart or `navigator.toml` schema migration is required.
+- Display aliases are presentation-only. Inventory targets, one-time token allowlists, chat callbacks, Bedrock response mapping, health lookups, and connection requests continue to use the raw registered server ID.
+- Java inventory state styles are applied after availability is resolved. A per-server `name` or `lore` remains final; otherwise the matching state template is used before the localized default. For unavailable entries, a per-server `unavailable_material` remains final, followed by the state material and global unavailable fallback. Healthy entries keep their per-server/global normal material.
+- `gui.toml` now uses `config_version = 2`; `navigator.toml` remains at config version 8.
+
+### Not included
+
+- Localized per-language display names are not part of 4.4.0. Existing language packs still control shared selector templates and status text.
+
+---
+
 ## [4.3.0] - 2026-07-14
 
 ### Advanced proxy systems

README.md

@@ -11,10 +11,10 @@
 </p>
 
 <p align="center">
-  <img src="https://img.shields.io/badge/version-4.3.0-cyan?style=for-the-badge" alt="Version">
+  <img src="https://img.shields.io/badge/version-4.4.0-cyan?style=for-the-badge" alt="Version">
   <img src="https://img.shields.io/badge/channel-stable-38d6e0?style=for-the-badge" alt="Stable release channel">
-  <img src="https://img.shields.io/badge/platform-Velocity_3.x-blue?style=for-the-badge" alt="Platform">
-  <img src="https://img.shields.io/badge/java-17+-orange?style=for-the-badge" alt="Java">
+  <img src="https://img.shields.io/badge/platform-Velocity_3.4.x_%2F_3.5.x_%2B_4.0.0-blue?style=for-the-badge" alt="Platform">
+  <img src="https://img.shields.io/badge/java-17_%2F_21_%2F_25-orange?style=for-the-badge" alt="Java">
   <img src="https://img.shields.io/badge/license-Apache_2.0-green?style=for-the-badge" alt="License">
 </p>
 
@@ -28,6 +28,41 @@ The JAR always runs on Velocity. Install the same JAR on Paper or Spigot only wh
 
 ---
 
+## What's New in v4.4
+
+| Feature | Description |
+|---------|-------------|
+| **Cross-selector display names** | Give a raw Velocity ID such as `lobby1` a player-facing `display_name` such as `Main Lobby 1` across Java inventory, Java chat, and Bedrock selectors |
+| **Descriptions and safe placeholders** | Share `{description}` across selector templates; `{server}`/`{display_name}` show the alias, while `{server_id}` exposes the raw routing ID |
+| **Shared ordering and visibility** | `menu_order` controls selector order and `show_in_menu = false` hides internal servers from menus without removing them from automatic routing |
+| **State-aware inventory presentation** | Give full, draining, offline, and in-game servers their own Java inventory material, item name, and lore |
+| **Menu validator** | `/vn menu validate` checks server IDs, duplicate labels, slots, material identifiers, and `{...}` placeholders before players encounter a broken selector |
+| **Alias-aware Bedrock sorting** | `sort_mode = "name"` orders buttons by their displayed names; blank aliases fall back to the registered ID |
+
+Selector metadata lives under `[servers]` in `gui.toml`, while reusable Java inventory state styles live under `[states.*]`. Changes apply after `/vn reload`. Raw Velocity IDs remain the only routing and connection targets.
+
+Set Java inventory size in the proxy's `plugins/velocitynavigator/gui.toml`. `rows` accepts `2` through `6` (18 through 54 slots); the bottom row is reserved for controls. For a 36-slot menu:
+
+```toml
+[layout]
+rows = 4
+
+[controls]
+previous_slot = 27
+refresh_slot = 31
+next_slot = 35
+```
+
+Run `/vn reload`, then `/vn menu validate`. See the [Java and Bedrock Selectors guide](https://github.com/DemonZ-Development/VelocityNavigator/wiki/Java-and-Bedrock-Selectors#inventory-size-and-slots) for every size.
+
+Per-language display names are not included in v4.4; language packs continue to translate the surrounding selector templates and status text.
+
+See the [Selector Customization guide](https://github.com/DemonZ-Development/VelocityNavigator/wiki/Server-Display-Names) for complete examples and troubleshooting.
+
+See the [CHANGELOG](CHANGELOG.md) for the full list of changes.
+
+---
+
 ## What's New in v4.3
 
 | Feature | Description |
@@ -76,7 +111,7 @@ See the [CHANGELOG](CHANGELOG.md) for the full list of changes.
 | **Per-group selection mode** | Contextual groups can override the global selection algorithm |
 | **Fallback priority chain** | Ordered fallback groups when a group's servers are unavailable |
 | **Graceful degradation** | Fall back to random selection when all health checks fail |
-| **Geo routing placeholder** | Compatibility config remains, but MaxMind/GeoIP routing is intentionally deferred beyond 4.3.0 |
+| **Geo routing placeholder** | Compatibility config remains, but MaxMind/GeoIP routing is intentionally deferred beyond 4.4.0 |
 | **Admin update notifications** | In-game notification for admins when updates are available |
 
   See [Migration Guide](https://github.com/DemonZ-Development/VelocityNavigator/wiki/Migration-Guide-v3-to-v4) for upgrade instructions.
@@ -97,7 +132,7 @@ See the [CHANGELOG](CHANGELOG.md) for the full list of changes.
 | **Server drain mode** | `/vn drain` and `/vn undrain` for maintenance |
 | **bStats telemetry** | Anonymous usage metrics via [bStats](https://bstats.org/plugin/velocity/Velocity%20Navigator/28341) |
 | **Self-documenting config** | `navigator.toml` generates with inline docs explaining every setting |
-| **Admin suite** | `/vn status`, `/vn health`, `/vn bridge status`, `/vn reload`, `/vn debug`, `/vn drain`, `/vn updatecheck` with tab-completion |
+| **Admin suite** | `/vn status`, `/vn health`, `/vn bridge status`, `/vn menu validate`, `/vn reload`, `/vn debug`, `/vn drain`, `/vn updatecheck` with tab-completion |
 | **Native parties** | `/party` lifecycle commands, `/p` chat, and automatic online-member follow when the leader changes server |
 | **Virtual capacity queue** | Full pools place players in a live position queue and connect them as soon as slots open |
 | **Multi-proxy Redis sync** | Dynamic backend registration plus circuit-breaker, health-cache, and affinity synchronization |
@@ -107,15 +142,15 @@ See the [CHANGELOG](CHANGELOG.md) for the full list of changes.
 
 ## Installation
 
-1. Download `VelocityNavigator-4.3.0.jar` from the [VelocityNavigator Modrinth page](https://modrinth.com/plugin/velocitynavigator)
+1. Download `VelocityNavigator-4.4.0.jar` from the [VelocityNavigator Modrinth page](https://modrinth.com/plugin/velocitynavigator)
 2. Place it in your Velocity proxy's `plugins/` folder
 3. Start (or restart) the proxy
 4. Edit `navigator.toml` for systems, `messages.toml` for language, `gui.toml` for Java/Bedrock menus, and `servers.toml` for command-managed lobbies
 5. Optional: place the same JAR in each backend Paper/Spigot server's `plugins/` folder to enable the Java inventory selector
 
 The universal JAR prints `VELOCITY PROXY mode` or `BACKEND GUI BRIDGE mode` at startup.
 
-**Requirements**: Velocity 3.x • Java 17+ • Minecraft 1.7.2 through 26.2 via Velocity • Paper/Spigot 1.16.5+ for the optional backend inventory bridge
+**Requirements**: Velocity 3.4.x, Velocity 3.5.x, or Velocity 4.0.0 with the same JAR • Java 17 for Velocity 3.4.x, Java 21 for Velocity 3.5.x, or Java 25 for Velocity 4.0.0 • Minecraft 1.7.2 through 26.2 via Velocity • Paper/Spigot 1.16.5+ with Java 17+ for the optional backend inventory bridge
 
 The optional backend bridge is built against Spigot API 1.16.5 and uses no version-specific NMS. Proxy-only installations do not need the JAR on game or lobby backends.
 
@@ -206,6 +241,7 @@ Configurable text supports MiniMessage, classic `&`/`§` codes, `&#RRGGBB`, and
 | `/vn server remove <name>` | `velocitynavigator.admin` | Remove a server from managed Velocity/plugin configuration |
 | `/vn server list` | `velocitynavigator.admin` | List plugin-managed lobby entries and the Velocity config path |
 | `/vn config validate` | `velocitynavigator.admin` | Check command collisions, Redis/HTTP safety, queue holding server, and managed files |
+| `/vn menu validate` | `velocitynavigator.admin` | Audit GUI server IDs, duplicate labels, slots, material identifiers, and placeholders |
 | `/vn reload` | `velocitynavigator.admin` | Hot-reload navigator.toml, messages.toml, gui.toml, and servers.toml |
 | `/vn status` | `velocitynavigator.admin` | View runtime status, distribution, circuit breakers |
 | `/vn health` | `velocitynavigator.admin` | Consolidated one-shot diagnostics screen |
@@ -259,6 +295,7 @@ See the [HTML Dashboard guide](https://github.com/DemonZ-Development/VelocityNav
 |----------|-------------|
 | [Quick Start Guide](https://github.com/DemonZ-Development/VelocityNavigator/wiki/Quick-Start-Guide) | Get running in under 10 minutes |
 | [Configuration Guide](https://github.com/DemonZ-Development/VelocityNavigator/wiki/Configuration-Guide) | Every `navigator.toml`, `messages.toml`, `gui.toml`, and `servers.toml` setting explained |
+| [Selector Customization](https://github.com/DemonZ-Development/VelocityNavigator/wiki/Server-Display-Names) | Display names, descriptions, ordering, visibility, state styles, precedence, and menu validation |
 | [Commands and Permissions](https://github.com/DemonZ-Development/VelocityNavigator/wiki/Commands-and-Permissions) | Complete player, admin, party, queue, managed-server, and integration command reference |
 | [Routing Algorithms](https://github.com/DemonZ-Development/VelocityNavigator/wiki/Routing-Algorithms) | Deep dive into all 8 routing modes |
 | [Algorithm Visualizations](https://github.com/DemonZ-Development/VelocityNavigator/wiki/Algorithm-Visualizations) | Distribution patterns at different load levels |
@@ -280,7 +317,7 @@ See the [HTML Dashboard guide](https://github.com/DemonZ-Development/VelocityNav
 git clone https://github.com/DemonZ-Development/VelocityNavigator.git
 cd VelocityNavigator
 mvn clean verify
-# JAR output: target/VelocityNavigator-4.3.0.jar
+# JAR output: target/VelocityNavigator-4.4.0.jar
 ```
 
 ---