release: prepare 1.3.1

Author: Arbousier1

CHANGELOG.md

@@ -1,5 +1,23 @@
 # Changelog
 
+## 1.3.1 - 2026-06-18
+
+Hotfix and usability release for CI reliability, command help navigation, and game room selection confirmation.
+
+中文更新日志:
+
+- **Java 编译修复**: 修复 `TableEventCoordinator` 对 Caffeine `Cache` 的旧式 `get(key)` 调用，改为 `getIfPresent`，恢复 Java 编译。
+- **Gradle 下载稳定性**: 提高 Gradle Wrapper 下载超时时间并启用重试，降低 GitHub Actions 首次拉取 Gradle 发行包时的超时概率。
+- **命令帮助排版**: `/mahjong help` 改为分页式帮助列表，加入标题、副标题、页码状态以及上一页/下一页点击导航。
+- **棋室选区粒子预览**: 借鉴 Residence 的领地选择可视化思路，使用粒子描出已选择方块或完整长方体边框，方便创建棋室前确认范围。
+
+English Release Notes:
+
+- **Java compilation fix**: Fixed the outdated Caffeine `Cache#get(key)` call in `TableEventCoordinator` by switching to `getIfPresent`, restoring Java compilation.
+- **Gradle download reliability**: Increased the Gradle Wrapper network timeout and enabled retries to reduce first-download timeouts in GitHub Actions.
+- **Command help layout**: `/mahjong help` now renders as a paged command list with header, subtitle, page status, and clickable previous/next navigation.
+- **Game room selection preview**: Added Residence-inspired particle outlines for the selected block or full cuboid, helping admins confirm the room range before creation.
+
 ## 1.3.0 - 2026-06-17
 
 Game room system with core restrictions, wand selection tool, room management commands, bossbar/text mode adaptation, and documentation alignment.

build.gradle.kts

@@ -12,7 +12,7 @@ plugins {
 }
 
 group = "top.ellan"
-version = "1.3.0"
+version = "1.3.1"
 
 val minimumPaperDevBundleVersion = "1.20.1-R0.1-SNAPSHOT"
 val paperDevBundleVersion =

gradle/wrapper/gradle-wrapper.properties

@@ -1,9 +1,9 @@
 distributionBase=GRADLE_USER_HOME
 distributionPath=wrapper/dists
 distributionUrl=https\://services.gradle.org/distributions/gradle-9.5.1-bin.zip
-networkTimeout=10000
-retries=0
-retryBackOffMs=500
+networkTimeout=120000
+retries=3
+retryBackOffMs=1000
 validateDistributionUrl=true
 zipStoreBase=GRADLE_USER_HOME
 zipStorePath=wrapper/dists

src/main/java/top/ellan/mahjong/bootstrap/MahjongPaperPlugin.java

@@ -9,6 +9,7 @@
 import top.ellan.mahjong.db.DatabaseService;
 import top.ellan.mahjong.gb.jni.GbNativeWarmupService;
 import top.ellan.mahjong.gameroom.GameRoomManager;
+import top.ellan.mahjong.gameroom.GameRoomSelectionPreviewService;
 import top.ellan.mahjong.gameroom.GameRoomSelectionService;
 import top.ellan.mahjong.gameroom.GameRoomWandListener;
 import top.ellan.mahjong.i18n.MessageService;
@@ -47,6 +48,7 @@ public final class MahjongPaperPlugin extends JavaPlugin {
     private MahjongTableManager tableManager;
     private GameRoomManager gameRoomManager;
     private GameRoomSelectionService gameRoomSelectionService;
+    private GameRoomSelectionPreviewService gameRoomSelectionPreviewService;
     private PluginTask gameRoomTickTask;
 
     @Override
@@ -85,6 +87,7 @@ public void onEnable() {
         this.tableManager.loadPersistentTables();
 
         this.gameRoomSelectionService = new GameRoomSelectionService();
+        this.gameRoomSelectionPreviewService = new GameRoomSelectionPreviewService(this.gameRoomSelectionService, this.scheduler);
         this.gameRoomManager = new GameRoomManager(
             this.tableManager,
             () -> this.debug,
@@ -112,7 +115,7 @@ public void onEnable() {
 
         this.getServer().getPluginManager().registerEvents(this.tableManager, this);
         this.getServer().getPluginManager().registerEvents(new top.ellan.mahjong.gameroom.GameRoomListener(() -> this.gameRoomManager, this.messages, () -> this.settings), this);
-        this.getServer().getPluginManager().registerEvents(new GameRoomWandListener(this.gameRoomSelectionService, this.messages, () -> this.settings), this);
+        this.getServer().getPluginManager().registerEvents(new GameRoomWandListener(this.gameRoomSelectionService, this.gameRoomSelectionPreviewService, this.messages, () -> this.settings), this);
         this.gameRoomTickTask = this.scheduler.runGlobalTimer(() -> {
             if (this.gameRoomManager != null) {
                 this.gameRoomManager.tick();
@@ -138,6 +141,10 @@ public void onDisable() {
             this.gameRoomTickTask.cancel();
             this.gameRoomTickTask = null;
         }
+        if (this.gameRoomSelectionPreviewService != null) {
+            this.gameRoomSelectionPreviewService.cancelAll();
+            this.gameRoomSelectionPreviewService = null;
+        }
         if (this.tableManager != null) {
             this.tableManager.shutdown();
         }
@@ -372,6 +379,9 @@ public String reloadMahjongConfiguration() {
         if (this.gameRoomSelectionService != null && !reloadedSettings.gameRooms().enabled()) {
             this.gameRoomSelectionService.clearAll();
         }
+        if (this.gameRoomSelectionPreviewService != null && !reloadedSettings.gameRooms().enabled()) {
+            this.gameRoomSelectionPreviewService.cancelAll();
+        }
         this.debug.log("lifecycle", "Debug logging enabled.");
         this.notifySettingsListeners(previousSettings, reloadedSettings);
 
@@ -458,5 +468,3 @@ private java.nio.file.Path gameRoomStoragePath(PluginSettings settings) {
         return this.getDataFolder().toPath().resolve(file);
     }
 }
-
-

src/main/java/top/ellan/mahjong/command/MahjongCommandContext.java

@@ -11,6 +11,10 @@
 import java.util.function.Supplier;
 import kotlin.Pair;
 import net.kyori.adventure.text.Component;
+import net.kyori.adventure.text.TextComponent;
+import net.kyori.adventure.text.event.ClickEvent;
+import net.kyori.adventure.text.event.HoverEvent;
+import net.kyori.adventure.text.format.NamedTextColor;
 import org.bukkit.command.CommandSender;
 import org.bukkit.entity.Player;
 import top.ellan.mahjong.debug.DebugService;
@@ -37,7 +41,9 @@
 
 public final class MahjongCommandContext {
     public static final String ADMIN_PERMISSION = "mahjongpaper.admin";
+    private static final int HELP_PAGE_SIZE = 10;
     static final java.util.List<String> HELP_KEY_ORDER = java.util.List.of(
+        "command.help.help",
         "command.help.create",
         "command.help.botmatch",
         "command.help.mode",
@@ -147,14 +153,40 @@ public MahjongTableSession requireViewedTable(Player player) {
     }
 
     public void sendHelp(Player player) {
+        this.sendHelp(player, 1);
+    }
+
+    public void sendHelp(Player player, int requestedPage) {
         Locale locale = this.messages.resolveLocale(player);
-        this.messages.send(player, "command.usage");
-        for (String key : HELP_KEYS) {
-            if (ADMIN_HELP_KEYS.contains(key) && !player.hasPermission(ADMIN_PERMISSION)) {
-                continue;
-            }
-            player.sendMessage(this.messages.render(locale, key));
+        List<String> visibleKeys = this.visibleHelpKeys(player);
+        int pageCount = Math.max(1, (int) Math.ceil((double) visibleKeys.size() / HELP_PAGE_SIZE));
+        int page = Math.max(1, Math.min(requestedPage, pageCount));
+        int start = (page - 1) * HELP_PAGE_SIZE;
+        int end = Math.min(start + HELP_PAGE_SIZE, visibleKeys.size());
+
+        player.sendMessage(this.messages.render(locale, "command.help.header"));
+        player.sendMessage(this.messages.render(locale, "command.help.subtitle"));
+        player.sendMessage(this.messages.render(
+            locale,
+            "command.help.page_status",
+            this.messages.number(locale, "page", page),
+            this.messages.number(locale, "pages", pageCount),
+            this.messages.number(locale, "count", visibleKeys.size())
+        ));
+        for (int index = start; index < end; index++) {
+            player.sendMessage(Component.text("  - ", NamedTextColor.DARK_AQUA).append(this.messages.render(locale, visibleKeys.get(index))));
         }
+        player.sendMessage(this.helpNavigation(locale, page, pageCount));
+        player.sendMessage(this.messages.render(locale, "command.help.footer"));
+    }
+
+    public List<String> suggestedHelpPages(Player player, String rawPrefix) {
+        int pageCount = this.helpPageCount(player);
+        List<String> pages = new ArrayList<>(pageCount);
+        for (int page = 1; page <= pageCount; page++) {
+            pages.add(String.valueOf(page));
+        }
+        return this.matchPrefix(rawPrefix, pages);
     }
 
     public void sendReaction(Player player, ReactionType type, Pair<MahjongTile, MahjongTile> pair, String actionKey) {
@@ -439,6 +471,51 @@ private String rankLabel(Locale locale, MahjongSoulRankProfile profile) {
         return this.messages.plain(locale, tierKey) + " " + profile.level();
     }
 
+    private List<String> visibleHelpKeys(Player player) {
+        List<String> keys = new ArrayList<>();
+        for (String key : HELP_KEYS) {
+            if (ADMIN_HELP_KEYS.contains(key) && !player.hasPermission(ADMIN_PERMISSION)) {
+                continue;
+            }
+            keys.add(key);
+        }
+        return List.copyOf(keys);
+    }
+
+    private int helpPageCount(Player player) {
+        return Math.max(1, (int) Math.ceil((double) this.visibleHelpKeys(player).size() / HELP_PAGE_SIZE));
+    }
+
+    private Component helpNavigation(Locale locale, int page, int pageCount) {
+        TextComponent.Builder builder = Component.text();
+        builder.append(Component.text("  "));
+        builder.append(this.helpPageButton(locale, "command.help.previous", page - 1, page > 1));
+        builder.append(Component.text(" "));
+        builder.append(this.messages.render(
+            locale,
+            "command.help.page_compact",
+            this.messages.number(locale, "page", page),
+            this.messages.number(locale, "pages", pageCount)
+        ));
+        builder.append(Component.text(" "));
+        builder.append(this.helpPageButton(locale, "command.help.next", page + 1, page < pageCount));
+        return builder.build();
+    }
+
+    private Component helpPageButton(Locale locale, String labelKey, int targetPage, boolean enabled) {
+        String label = this.messages.plain(locale, labelKey);
+        Component button = Component.text("[", NamedTextColor.DARK_GRAY)
+            .append(Component.text(label, enabled ? NamedTextColor.YELLOW : NamedTextColor.DARK_GRAY))
+            .append(Component.text("]", NamedTextColor.DARK_GRAY));
+        if (!enabled) {
+            return button;
+        }
+        String command = "/mahjong help " + targetPage;
+        return button
+            .clickEvent(ClickEvent.runCommand(command))
+            .hoverEvent(HoverEvent.showText(Component.text(command, NamedTextColor.GRAY)));
+    }
+
     public void showLeaderboard(Player player, MahjongVariant requestedMode) {
         DatabaseService database = this.database();
         if (database == null || !database.rankingEnabled()) {

src/main/java/top/ellan/mahjong/command/subcommand/HelpSubcommand.java

@@ -1,5 +1,6 @@
 package top.ellan.mahjong.command.subcommand;
 
+import java.util.List;
 import org.bukkit.command.CommandSender;
 import org.bukkit.entity.Player;
 import top.ellan.mahjong.command.MahjongCommandContext;
@@ -8,5 +9,23 @@
 public final class HelpSubcommand extends AbstractMahjongSubcommand {
     public HelpSubcommand(MahjongCommandContext context) { super(context); }
     public MahjongSubcommand create() { return this.subcommand("help"); }
-    @Override protected void execute(CommandSender sender, Player player, String[] args) { this.context.sendHelp(player); }
-}
+    @Override protected void execute(CommandSender sender, Player player, String[] args) {
+        if (args.length < 2) {
+            this.context.sendHelp(player);
+            return;
+        }
+        this.context.sendHelp(player, this.parsePage(args[1]));
+    }
+
+    @Override protected List<String> suggest(Player player, String[] args) {
+        return args.length == 2 ? this.context.suggestedHelpPages(player, args[1]) : List.of();
+    }
+
+    private int parsePage(String raw) {
+        try {
+            return Integer.parseInt(raw);
+        } catch (NumberFormatException exception) {
+            return 1;
+        }
+    }
+}

src/main/java/top/ellan/mahjong/gameroom/GameRoomSelectionPreviewService.java

@@ -0,0 +1,120 @@
+package top.ellan.mahjong.gameroom;
+
+import java.util.List;
+import java.util.Map;
+import java.util.UUID;
+import java.util.concurrent.ConcurrentHashMap;
+import org.bukkit.Color;
+import org.bukkit.Location;
+import org.bukkit.Particle;
+import org.bukkit.entity.Player;
+import top.ellan.mahjong.compat.PaperCompatibility;
+import top.ellan.mahjong.runtime.PluginTask;
+import top.ellan.mahjong.runtime.ServerScheduler;
+
+public final class GameRoomSelectionPreviewService {
+    private static final int PREVIEW_PULSES = 8;
+    private static final long PREVIEW_PERIOD_TICKS = 10L;
+    private static final Particle.DustOptions OUTLINE_DUST = new Particle.DustOptions(Color.fromRGB(60, 220, 255), 1.15F);
+
+    private final GameRoomSelectionService selectionService;
+    private final ServerScheduler scheduler;
+    private final Map<UUID, PreviewSession> sessions = new ConcurrentHashMap<>();
+
+    public GameRoomSelectionPreviewService(GameRoomSelectionService selectionService, ServerScheduler scheduler) {
+        this.selectionService = selectionService;
+        this.scheduler = scheduler;
+    }
+
+    public void showSelection(Player player) {
+        if (player == null || this.selectionService == null || this.scheduler == null) {
+            return;
+        }
+        this.showSelection(player, this.selectionService.selection(player.getUniqueId()));
+    }
+
+    public void showSelection(Player player, GameRoomSelectionService.Selection selection) {
+        if (player == null || selection == null || this.scheduler == null) {
+            return;
+        }
+        UUID playerId = player.getUniqueId();
+        this.cancel(playerId);
+
+        List<Location> points = this.selectionService.previewPoints(selection, player.getLocation());
+        if (points.isEmpty()) {
+            return;
+        }
+        PreviewSession session = new PreviewSession(points, PREVIEW_PULSES);
+        this.sessions.put(playerId, session);
+        this.schedule(player, session, 1L);
+    }
+
+    public void cancel(UUID playerId) {
+        if (playerId == null) {
+            return;
+        }
+        PreviewSession session = this.sessions.remove(playerId);
+        if (session != null) {
+            session.cancel();
+        }
+    }
+
+    public void cancelAll() {
+        for (UUID playerId : List.copyOf(this.sessions.keySet())) {
+            this.cancel(playerId);
+        }
+    }
+
+    private void schedule(Player player, PreviewSession session, long delayTicks) {
+        session.task = this.scheduler.runEntityDelayed(player, () -> this.pulse(player, session), delayTicks);
+    }
+
+    private void pulse(Player player, PreviewSession session) {
+        if (player == null || this.sessions.get(player.getUniqueId()) != session) {
+            return;
+        }
+        if (!player.isOnline()) {
+            this.cancel(player.getUniqueId());
+            return;
+        }
+        for (Location point : session.points()) {
+            player.spawnParticle(
+                PaperCompatibility.dustParticle(),
+                point,
+                1,
+                0.0D,
+                0.0D,
+                0.0D,
+                0.0D,
+                OUTLINE_DUST
+            );
+        }
+        session.remainingPulses--;
+        if (session.remainingPulses <= 0) {
+            this.sessions.remove(player.getUniqueId(), session);
+            return;
+        }
+        this.schedule(player, session, PREVIEW_PERIOD_TICKS);
+    }
+
+    private static final class PreviewSession {
+        private final List<Location> points;
+        private int remainingPulses;
+        private PluginTask task;
+
+        private PreviewSession(List<Location> points, int remainingPulses) {
+            this.points = List.copyOf(points);
+            this.remainingPulses = remainingPulses;
+        }
+
+        private List<Location> points() {
+            return this.points;
+        }
+
+        private void cancel() {
+            if (this.task != null && !this.task.isCancelled()) {
+                this.task.cancel();
+            }
+        }
+    }
+}