release: prepare 1.3.2

Author: Arbousier1

CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## 1.3.2 - 2026-06-18
+
+Maintenance release for release-build formatting and clearer game room documentation.
+
+中文更新日志:
+
+- **发布构建修复**: 格式化 UI 测试文件，修复 Release 工作流在 Windows 平台执行 `spotlessKotlinCheck` 时失败的问题。
+- **棋牌室教程强化**: README 和中文 wiki 新增“先创建棋牌室，再创建牌桌”的开服推荐流程，补充魔棒选区、青色粒子范围确认、主厅创建和快速测试示例。
+
+English Release Notes:
+
+- **Release build fix**: Formatted UI test sources so the Windows Release build no longer fails in `spotlessKotlinCheck`.
+- **Game room documentation**: README and the Chinese wiki now emphasize creating a game room before placing tables, with wand selection, particle-outline confirmation, main-hall setup, and quick-test examples.
+
 ## 1.3.1 - 2026-06-18
 
 Hotfix and usability release for CI reliability, command help navigation, and game room selection confirmation.

README.md

@@ -31,9 +31,31 @@ The current branch already supports playable Riichi Mahjong, GB Mahjong, and Sic
 - round history persistence through H2 by default, with optional MariaDB/MySQL
 - game room system: spatial containers for tables, with optional table creation restriction, enter/exit messages, and leave countdown for active matches
 
+## Recommended Setup: Create a Game Room First
+
+For normal server operation, create at least one game room before opening public tables. A game room is the allowed play area for Mahjong tables; when `gameRooms.restrictNewTables` is enabled, `/mahjong create` only works while the admin is standing inside a game room.
+
+Quick tutorial:
+
+1. Give yourself admin permission: `mahjongpaper.admin`.
+2. Run `/mahjong room wand` to get the selection wand.
+3. Left-click one corner of the room, then right-click the opposite corner.
+4. Check the cyan particle outline and make sure the entire play area is inside the cuboid.
+5. Run `/mahjong room create main-hall Main Hall`.
+6. Stand inside that room and run `/mahjong create` to place a Mahjong table.
+7. Use `/mahjong room list` and `/mahjong room info main-hall` to confirm the saved room.
+
+If you only need a quick test room, stand at the room center and run `/mahjong room create quick-room`; without a wand selection, the plugin uses `gameRooms.defaultRadius` and `gameRooms.defaultHeight`.
+
+For the longer operations guide, see [Game room system](./docs/wiki.zh-CN.md#棋牌室系统) in the Chinese wiki.
+
 ## Command Summary
 
 - `/mahjong help`: show in-game command help
+- `/mahjong room wand`: get the game-room selection wand
+- `/mahjong room create <id> [name]`: create a game room from the current wand selection, or around your current position
+- `/mahjong room list`: list saved game rooms
+- `/mahjong room info <id>`: show a game room's world, bounds, size, and owner
 - `/mahjong create`: create a new empty table at your location
 - `/mahjong botmatch [MAJSOUL_HANCHAN|MAJSOUL_TONPUU|GB|SICHUAN]`: create a 4-bot test match and spectate it
 - `/mahjong mode <MAJSOUL_TONPUU|MAJSOUL_HANCHAN|GB|SICHUAN>`: apply a preset before the next start
@@ -67,6 +89,7 @@ Admin targeting details:
 
 ## Lobby Flow
 
+- On production servers, create the game room first, then stand inside it before running `/mahjong create`.
 - `/mahjong create` creates an empty table only; it does not auto-seat the creator
 - the creator becomes the table owner and can manage rules, bots, refresh, start, and delete from `/mahjong table`
 - the table owner/admin can transfer ownership with `/mahjong table owner <player> [tableId]`
@@ -96,7 +119,7 @@ The plugin ships three independent rulesets. Switch between them before a hand s
 
 Every mode uses the same play loop:
 
-1. `/mahjong create`: create an empty table at your feet.
+1. Create a game room first on production servers; then stand inside it and run `/mahjong create` to create an empty table.
 2. Click one of the east/south/west/north floating seat labels to sit down, or use `/mahjong join <tableId>`.
 3. Fill empty seats with `/mahjong addbot` (bots count as ready).
 4. `/mahjong start` toggles ready; the hand auto-starts once all 4 seats are filled and ready.

README.zh-CN.md

@@ -29,9 +29,31 @@
 - 默认使用 H2 持久化对局历史和段位，可选 MariaDB/MySQL
 - 棋牌室系统：牌桌的空间容器，支持牌桌创建限制、进出提醒和对局中离开倒计时
 
+## 推荐开服流程：先创建棋牌室
+
+正式开服时，建议先创建至少一个棋牌室，再在棋牌室内创建牌桌。棋牌室是牌桌的允许摆放区域；当 `gameRooms.restrictNewTables` 开启时，管理员只有站在棋牌室内才能使用 `/mahjong create` 创建新牌桌。
+
+快速教程：
+
+1. 确认你拥有管理员权限：`mahjongpaper.admin`。
+2. 执行 `/mahjong room wand` 获取棋牌室选区魔棒。
+3. 左键点击房间的一个角，右键点击对角线另一角。
+4. 观察青色粒子边框，确认整个游玩区域都被框住。
+5. 执行 `/mahjong room create main-hall 主厅` 创建棋牌室。
+6. 站在这个棋牌室内，执行 `/mahjong create` 创建牌桌。
+7. 用 `/mahjong room list` 和 `/mahjong room info main-hall` 检查保存结果。
+
+如果只是快速测试，也可以站在房间中心直接执行 `/mahjong room create quick-room`；没有魔棒选区时，插件会按 `gameRooms.defaultRadius` 和 `gameRooms.defaultHeight` 自动生成一个区域。
+
+更完整的操作说明见中文 wiki 的 [棋牌室系统](./docs/wiki.zh-CN.md#棋牌室系统)。
+
 ## 指令概览
 
 - `/mahjong help`：显示游戏内帮助
+- `/mahjong room wand`：获取棋牌室选区魔棒
+- `/mahjong room create <id> [名称]`：用当前选区创建棋牌室；没有选区时以当前位置为中心创建
+- `/mahjong room list`：列出已保存的棋牌室
+- `/mahjong room info <id>`：查看棋牌室世界、边界、大小和所有者
 - `/mahjong create`：在当前位置创建一个空牌桌
 - `/mahjong botmatch [MAJSOUL_HANCHAN|MAJSOUL_TONPUU|GB|SICHUAN]`：创建一桌 4 Bot 测试对局并进入观战
 - `/mahjong mode <MAJSOUL_TONPUU|MAJSOUL_HANCHAN|GB|SICHUAN>`：桌主/管理员在下一局开始前应用预设规则；默认玩法以 `MAJSOUL_HANCHAN` 为主
@@ -62,6 +84,7 @@
 
 ## 大厅与准备流程
 
+- 正式服建议先建棋牌室，再站在棋牌室内使用 `/mahjong create` 创建牌桌。
 - `/mahjong create` 只会创建空桌，不会自动把创建者加入牌局
 - 创建者会成为桌主，可通过 `/mahjong table` 管理规则、Bot、刷新、开局和删除
 - 桌主/管理员可用 `/mahjong table owner <玩家名> [tableId]` 把桌主转让给已经入座的在线玩家
@@ -86,7 +109,7 @@
 
 无论哪种模式，一局的操作流程都一样：
 
-1. `/mahjong create`：在你脚下创建一张空牌桌。
+1. 正式服先创建棋牌室；然后站在棋牌室内执行 `/mahjong create` 创建一张空牌桌。
 2. 走到东/南/西/北四个悬浮座位牌前点击入座，或用 `/mahjong join <牌桌ID>`。
 3. 缺人时由桌主/管理员用 `/mahjong table` 或 `/mahjong addbot` 补 Bot（Bot 默认视为已准备）。
 4. `/mahjong start` 切换准备状态；4 个座位都坐满且全部准备后自动开局。

build.gradle.kts

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

docs/wiki.zh-CN.md

@@ -17,6 +17,22 @@
 | 配置文件 | `plugins/MahjongPaper/config.yml` |
 | CraftEngine 导出目录 | `plugins/CraftEngine/resources/mahjongpaper` |
 
+## 开服推荐路径：先建棋牌室
+
+正式服建议把“创建棋牌室”作为开桌前的第一步。棋牌室是牌桌的空间容器，用来规定牌桌能放在哪里，并提供进出提醒和对局中离开倒计时。默认配置下，`gameRooms.enabled: true` 且 `gameRooms.restrictNewTables: true`，因此管理员需要站在棋牌室内才能创建新牌桌。
+
+推荐流程：
+
+1. 确认管理员拥有 `mahjongpaper.admin`。
+2. 使用 `/mahjong room wand` 获取选区魔棒。
+3. 左键点击房间一个角，右键点击对角。
+4. 观察青色粒子边框，确认棋牌室范围覆盖整个游玩区域。
+5. 使用 `/mahjong room create main-hall 主厅` 保存棋牌室。
+6. 站在棋牌室内执行 `/mahjong create` 创建牌桌。
+7. 用 `/mahjong room info main-hall` 检查世界、坐标和大小。
+
+这个流程适合大厅、包间、活动区等固定场地。临时测试时，可以不使用魔棒，直接站在中心点执行 `/mahjong room create test-room`，插件会按 `gameRooms.defaultRadius` 和 `gameRooms.defaultHeight` 自动生成一个区域。
+
 ## 安装与首次启动
 
 1. 准备 Paper 或 Folia 服务端，并确保运行环境是 Java 21。
@@ -30,7 +46,7 @@
 
 一张牌桌从创建到结束大致是这个流程：
 
-1. 管理员使用 `/mahjong create` 在当前位置创建空牌桌。
+1. 管理员先创建棋牌室；如果启用了创建限制，则站在棋牌室内使用 `/mahjong create` 创建空牌桌。
 2. 玩家点击东、南、西、北四个座位悬浮标签入座，也可以使用 `/mahjong join <table_id>` 加入。
 3. 开局前可使用 `/mahjong mode <mode>` 切换玩法，或用 `/mahjong rule <key> <value>` 调整部分规则。
 4. 缺人时可用 `/mahjong addbot` 补 Bot。Bot 默认视为已准备。
@@ -208,7 +224,7 @@
 
 | 命令 | 用途 |
 | --- | --- |
-| `/mahjong create` | 在当前位置创建牌桌 |
+| `/mahjong create` | 在当前位置创建牌桌；开启棋牌室限制时必须站在棋牌室内 |
 | `/mahjong botmatch [hanchan|tonpuu]` | 创建 4 Bot 立直测试桌并进入观战 |
 | `/mahjong render` | 重新渲染当前牌桌 |
 | `/mahjong inspect` | 显示渲染锚点和方向诊断 |
@@ -314,7 +330,7 @@ MahjongPaper 使用 CraftEngine 处理以下内容：
 | `/mahjong leaderboard [mode]` | 玩家 | 查看分模式排行榜 |
 | `/mahjong addbot` | 桌主/管理员 | 开局前添加 Bot |
 | `/mahjong removebot` | 桌主/管理员 | 开局前移除 Bot |
-| `/mahjong create` | 管理员 | 创建牌桌 |
+| `/mahjong create` | 管理员 | 创建牌桌；开启棋牌室限制时必须站在棋牌室内 |
 | `/mahjong botmatch [MAJSOUL_HANCHAN|MAJSOUL_TONPUU|GB|SICHUAN]` | 管理员 | 创建 4 Bot 测试桌 |
 | `/mahjong list` | 管理员 | 列出活动牌桌 |
 | `/mahjong render` | 管理员 | 强制刷新牌桌展示 |
@@ -362,7 +378,7 @@ MahjongPaper 使用 CraftEngine 处理以下内容：
 
 ### 创建棋牌室
 
-有两种方式创建棋牌室：使用游戏内魔棒工具（推荐）或手动编辑配置文件。
+有两种方式创建棋牌室：使用游戏内魔棒工具（推荐）或手动编辑配置文件。推荐优先使用魔棒，因为它能即时显示粒子边框，方便确认区域是否覆盖完整。
 
 #### 方式一：魔棒工具（推荐）
 
@@ -383,7 +399,14 @@ MahjongPaper 使用 CraftEngine 处理以下内容：
 | 左键点击方块 | 设置选区第一点（最小角） |
 | 右键点击方块 | 设置选区第二点（最大角） |
 
-两点确定一个长方体（AABB）区域。设置成功后会收到提示消息，显示当前选区坐标。
+两点确定一个长方体（AABB）区域。设置成功后会收到提示消息，显示当前选区坐标；同时会出现青色粒子边框，用来确认棋牌室的实际范围。粒子边框只会显示给当前管理员，不会影响其他玩家。
+
+选区建议：
+
+- 第一、第二点可以任意先后点击，插件会自动计算最小/最大坐标。
+- 选区高度要覆盖玩家活动高度和牌桌展示高度，不要只框地面一层。
+- 如果棋牌室是大厅，建议比墙体内侧略大一圈，避免牌桌中心点贴边时被判定在区域外。
+- 如果右键后发现粒子边框不对，重新左键/右键选择即可，旧预览会被刷新。
 
 **创建棋牌室**：
 
@@ -398,13 +421,23 @@ MahjongPaper 使用 CraftEngine 处理以下内容：
 
 如果已有选区，会使用选区坐标创建；如果没有选区，则以玩家当前位置为中心，按配置中的 `defaultRadius` 和 `defaultHeight` 创建。
 
-**示例**：
+**完整示例：创建一个主厅棋牌室**：
 
 ```
 /mahjong room wand                          # 获取魔棒
-# 左键点击房间一个角，右键点击对角
+# 左键点击主厅地面一角
+# 右键点击主厅对角的上方或地面方块
+# 确认青色粒子边框覆盖整个主厅
 /mahjong room create main-hall 主厅          # 用选区创建棋牌室
+/mahjong room info main-hall                # 检查保存后的范围
+/mahjong create                             # 站在主厅内创建牌桌
+```
+
+**快速测试示例**：
+
+```
 /mahjong room create quick-room             # 无选区时以玩家位置为中心创建
+/mahjong create                             # 在 quick-room 内创建牌桌
 ```
 
 **其他棋牌室命令**：

src/test/kotlin/top/ellan/mahjong/ui/SettlementUiIntegrationTest.kt

@@ -1,8 +1,11 @@
 package top.ellan.mahjong.ui
 
-import top.ellan.mahjong.table.core.TableRuntimeServices
+import net.kyori.adventure.text.serializer.plain.PlainTextComponentSerializer
+import org.mockito.Mockito.mock
+import org.mockito.Mockito.`when`
 import top.ellan.mahjong.compat.CraftEngineService
 import top.ellan.mahjong.i18n.MessageService
+import top.ellan.mahjong.model.MahjongVariant
 import top.ellan.mahjong.riichi.RoundResolution
 import top.ellan.mahjong.riichi.model.DoubleYakuman
 import top.ellan.mahjong.riichi.model.ExhaustiveDraw
@@ -13,10 +16,7 @@ import top.ellan.mahjong.riichi.model.SettlementPayment
 import top.ellan.mahjong.riichi.model.SettlementPaymentType
 import top.ellan.mahjong.riichi.model.YakuSettlement
 import top.ellan.mahjong.table.core.MahjongTableSession
-import top.ellan.mahjong.model.MahjongVariant
-import net.kyori.adventure.text.serializer.plain.PlainTextComponentSerializer
-import org.mockito.Mockito.mock
-import org.mockito.Mockito.`when`
+import top.ellan.mahjong.table.core.TableRuntimeServices
 import java.util.Locale
 import java.util.UUID
 import kotlin.test.Test
@@ -28,35 +28,38 @@ class SettlementUiIntegrationTest {
     @Test
     fun `summary lore includes round dealer draw type and settled players`() {
         val session = mockSession()
-        val resolution = RoundResolution(
-            title = "Ron",
-            yakuSettlements = listOf(
-                YakuSettlement(
-                    displayName = "Alice",
-                    uuid = UUID.randomUUID().toString(),
-                    yakuList = listOf("reach"),
-                    yakumanList = emptyList(),
-                    doubleYakumanList = emptyList(),
-                    riichi = true,
-                    winningTile = MahjongTile.M1,
-                    hands = listOf(MahjongTile.M1, MahjongTile.M2, MahjongTile.M3),
-                    fuuroList = emptyList(),
-                    doraIndicators = emptyList(),
-                    uraDoraIndicators = emptyList(),
-                    fu = 30,
-                    han = 1,
-                    score = 1000
-                )
-            ),
-            scoreSettlement = ScoreSettlement(
-                "Ron",
-                listOf(
-                    ScoreItem("Alice", UUID.randomUUID().toString(), 25000, 12000),
-                    ScoreItem("Bob", UUID.randomUUID().toString(), 25000, -12000)
-                )
-            ),
-            draw = ExhaustiveDraw.NORMAL
-        )
+        val resolution =
+            RoundResolution(
+                title = "Ron",
+                yakuSettlements =
+                    listOf(
+                        YakuSettlement(
+                            displayName = "Alice",
+                            uuid = UUID.randomUUID().toString(),
+                            yakuList = listOf("reach"),
+                            yakumanList = emptyList(),
+                            doubleYakumanList = emptyList(),
+                            riichi = true,
+                            winningTile = MahjongTile.M1,
+                            hands = listOf(MahjongTile.M1, MahjongTile.M2, MahjongTile.M3),
+                            fuuroList = emptyList(),
+                            doraIndicators = emptyList(),
+                            uraDoraIndicators = emptyList(),
+                            fu = 30,
+                            han = 1,
+                            score = 1000,
+                        ),
+                    ),
+                scoreSettlement =
+                    ScoreSettlement(
+                        "Ron",
+                        listOf(
+                            ScoreItem("Alice", UUID.randomUUID().toString(), 25000, 12000),
+                            ScoreItem("Bob", UUID.randomUUID().toString(), 25000, -12000),
+                        ),
+                    ),
+                draw = ExhaustiveDraw.NORMAL,
+            )
 
         val rendered = SettlementUi.summaryLore(session, resolution, Locale.ENGLISH).map(plain::serialize)
 
@@ -71,29 +74,31 @@ class SettlementUiIntegrationTest {
         val session = mockSession()
         val ronPayer = UUID.randomUUID().toString()
         val paoPayer = UUID.randomUUID().toString()
-        val settlement = YakuSettlement(
-            displayName = "Alice",
-            uuid = UUID.randomUUID().toString(),
-            yakuList = listOf("reach"),
-            yakumanList = listOf("kokushimuso"),
-            doubleYakumanList = listOf(DoubleYakuman.SUANKO_TANKI),
-            riichi = true,
-            winningTile = MahjongTile.M1,
-            hands = listOf(MahjongTile.M1, MahjongTile.M2, MahjongTile.M3),
-            fuuroList = listOf(true to listOf(MahjongTile.P1, MahjongTile.P2, MahjongTile.P3)),
-            doraIndicators = listOf(MahjongTile.S1),
-            uraDoraIndicators = listOf(MahjongTile.S2),
-            fu = 40,
-            han = 3,
-            score = 7700,
-            paymentBreakdown = listOf(
-                SettlementPayment(ronPayer, 3900, SettlementPaymentType.RON),
-                SettlementPayment(paoPayer, 3900, SettlementPaymentType.PAO, "DAISANGEN"),
-                SettlementPayment("", 1000, SettlementPaymentType.RIICHI_POOL)
-            ),
-            redFiveCount = 1,
-            nagashiMangan = true
-        )
+        val settlement =
+            YakuSettlement(
+                displayName = "Alice",
+                uuid = UUID.randomUUID().toString(),
+                yakuList = listOf("reach"),
+                yakumanList = listOf("kokushimuso"),
+                doubleYakumanList = listOf(DoubleYakuman.SUANKO_TANKI),
+                riichi = true,
+                winningTile = MahjongTile.M1,
+                hands = listOf(MahjongTile.M1, MahjongTile.M2, MahjongTile.M3),
+                fuuroList = listOf(true to listOf(MahjongTile.P1, MahjongTile.P2, MahjongTile.P3)),
+                doraIndicators = listOf(MahjongTile.S1),
+                uraDoraIndicators = listOf(MahjongTile.S2),
+                fu = 40,
+                han = 3,
+                score = 7700,
+                paymentBreakdown =
+                    listOf(
+                        SettlementPayment(ronPayer, 3900, SettlementPaymentType.RON),
+                        SettlementPayment(paoPayer, 3900, SettlementPaymentType.PAO, "DAISANGEN"),
+                        SettlementPayment("", 1000, SettlementPaymentType.RIICHI_POOL),
+                    ),
+                redFiveCount = 1,
+                nagashiMangan = true,
+            )
 
         val rendered = SettlementUi.settlementLore(Locale.ENGLISH, session, settlement).map(plain::serialize)
 
@@ -122,4 +127,3 @@ class SettlementUiIntegrationTest {
         return session
     }
 }
-

src/test/kotlin/top/ellan/mahjong/ui/StaticUiSafetyTest.kt

@@ -7,7 +7,6 @@ import org.mockito.Mockito.lenient
 import org.mockito.Mockito.mock
 import top.ellan.mahjong.table.core.MahjongTableSession
 import java.util.UUID
-import kotlin.test.assertEquals
 import kotlin.test.assertFalse
 
 /**