docs: align README, wiki, CHANGELOG with codebase; add gameRooms config template

Author: Arbousier1

CHANGELOG.md

@@ -1,5 +1,25 @@
 # Changelog
 
+## 1.3.0-SNAPSHOT
+
+Game room system with core restrictions, bossbar/text mode adaptation, and documentation alignment.
+
+中文更新日志:
+
+- **棋牌室系统（核心限制）**: 新增 `GameRoom` 领域模型、`GameRoomManager` 管理器、`GameRoomListener` 监听器和 YAML 持久化。当 `gameRooms.enabled=true` 且 `gameRooms.restrictNewTables=true` 时，牌桌只能在棋牌室内创建；玩家进出棋牌室有提醒消息；对局中玩家离开棋牌室后启动倒计时，超时强制结束对局。
+- **倒计时警告节奏**: 前段每 15 秒提醒，最后 10 秒按 10/8/6/5/4/3/2/1 逐秒倒计时。玩家返回棋牌室则取消倒计时。
+- **Bossbar/桌上文字模式适配**: Bossbar 和桌上中心文字根据游戏模式（RIICHI/GB/SICHUAN）显示不同内容，不再统一显示日麻特有的供托/宝牌。
+- **配置模板补全**: 默认配置模板新增 `gameRooms` 配置段，包含 enabled、restrictNewTables、enterExitMessages、leaveCountdownSeconds、defaultRadius、defaultHeight、file 七个配置项。
+- **文档矫正**: README、wiki 和 CHANGELOG 与代码实际行为对齐，包括 botmatch 命令支持 GB/SICHUAN 预设、棋牌室系统说明等。
+
+English Release Notes:
+
+- **Game room system (core restrictions)**: Added `GameRoom` domain model, `GameRoomManager`, `GameRoomListener`, and YAML persistence. When `gameRooms.enabled=true` and `gameRooms.restrictNewTables=true`, tables can only be created inside game rooms; enter/exit messages are shown; active players who leave a game room trigger a countdown that force-ends the match on expiry.
+- **Countdown warning cadence**: Early phase warns every 15 seconds; final 10 seconds count down at 10, 8, 6, 5, 4, 3, 2, 1. Returning to the room cancels the countdown.
+- **Bossbar/table text mode adaptation**: Bossbar and center table text now display mode-appropriate content (RIICHI/GB/SICHUAN) instead of always showing riichi-specific indicators.
+- **Config template completion**: Default config template now includes the `gameRooms` section with enabled, restrictNewTables, enterExitMessages, leaveCountdownSeconds, defaultRadius, defaultHeight, and file settings.
+- **Documentation alignment**: README, wiki, and CHANGELOG corrected to match actual code behavior, including botmatch supporting GB/SICHUAN presets and game room system documentation.
+
 ## 1.2.0 - 2026-06-16
 
 GB/SICHUAN opening procedure and wall management overhaul to match real Chinese Official / Sichuan Mahjong rules.

README.md

@@ -1,4 +1,4 @@
-# MahjongPaper
+# MahjongPaper
 
 > This project was created entirely by AI.
 
@@ -29,12 +29,13 @@ The current branch already supports playable Riichi Mahjong, GB Mahjong, and Sic
 - Mahjong Soul-style rank persistence and per-mode leaderboards when database-backed ranking is enabled
 - CraftEngine-backed seat/table interaction and CraftEngine bundle export
 - 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
 
 ## Command Summary
 
 - `/mahjong help`: show in-game command help
 - `/mahjong create`: create a new empty table at your location
-- `/mahjong botmatch [hanchan|tonpuu]`: create a 4-bot test match and spectate it
+- `/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
 - `/mahjong join <tableId>`: join a table as a player
 - `/mahjong leave`: leave immediately before the hand starts, or queue a leave after the current hand
@@ -196,6 +197,7 @@ The current human-friendly layout is:
 - `database.h2`: local embedded H2 settings
 - `database.pool`: connection pool sizing
 - `tables.persistence`: persistent table restore file
+- `gameRooms`: game room system — spatial containers for tables, creation restriction, enter/exit messages, and leave countdown
 - `ranking`: Mahjong Soul-style room presets and rank persistence
 - `integrations.craftengine`: CraftEngine export and interaction preferences
 - `debug`: debug logging switches

README.zh-CN.md

@@ -27,12 +27,13 @@
 - 观战、私有手牌显示、HUD 覆盖层和本地化提示
 - 基于 CraftEngine 的座位 / 牌桌交互与 bundle 导出
 - 默认使用 H2 持久化对局历史和段位，可选 MariaDB/MySQL
+- 棋牌室系统：牌桌的空间容器，支持牌桌创建限制、进出提醒和对局中离开倒计时
 
 ## 指令概览
 
 - `/mahjong help`：显示游戏内帮助
 - `/mahjong create`：在当前位置创建一个空牌桌
-- `/mahjong botmatch [hanchan|tonpuu]`：创建一桌 4 Bot 测试对局并进入观战
+- `/mahjong botmatch [MAJSOUL_HANCHAN|MAJSOUL_TONPUU|GB|SICHUAN]`：创建一桌 4 Bot 测试对局并进入观战
 - `/mahjong mode <MAJSOUL_TONPUU|MAJSOUL_HANCHAN|GB|SICHUAN>`：桌主/管理员在下一局开始前应用预设规则；默认玩法以 `MAJSOUL_HANCHAN` 为主
 - `/mahjong join <tableId>`：加入牌桌
 - `/mahjong leave`：开局前直接离开；开局后标记为本局结束后离开
@@ -191,6 +192,7 @@
 - `database.h2`：本地 H2 配置
 - `database.pool`：连接池参数
 - `tables.persistence`：持久牌桌文件配置
+- `gameRooms`：棋牌室系统——牌桌的空间容器，支持创建限制、进出提醒和离开倒计时
 - `integrations.craftengine`：CraftEngine 导出与交互偏好
 - `debug`：调试日志
 

docs/wiki.zh-CN.md

@@ -247,6 +247,7 @@
 | `tables.startupRebuildBatchSize` | 启动时分批恢复牌桌展示的批量大小 |
 | `tables.allowFreeMoveDuringRound` | 是否允许牌局中自由移动 |
 | `tables.persistence` | 牌桌持久化文件开关和文件名 |
+| `gameRooms` | 棋牌室系统——牌桌的空间容器，创建限制、进出提醒、离开倒计时 |
 | `ranking` | 雀魂风格段位系统开关和房间档位 |
 | `integrations.craftengine` | CraftEngine bundle 导出、物品、家具和兼容性设置 |
 | `debug` | 调试日志分类 |
@@ -314,7 +315,7 @@ MahjongPaper 使用 CraftEngine 处理以下内容：
 | `/mahjong addbot` | 桌主/管理员 | 开局前添加 Bot |
 | `/mahjong removebot` | 桌主/管理员 | 开局前移除 Bot |
 | `/mahjong create` | 管理员 | 创建牌桌 |
-| `/mahjong botmatch [hanchan|tonpuu]` | 管理员 | 创建 4 Bot 测试桌 |
+| `/mahjong botmatch [MAJSOUL_HANCHAN|MAJSOUL_TONPUU|GB|SICHUAN]` | 管理员 | 创建 4 Bot 测试桌 |
 | `/mahjong list` | 管理员 | 列出活动牌桌 |
 | `/mahjong render` | 管理员 | 强制刷新牌桌展示 |
 | `/mahjong inspect` | 管理员 | 渲染诊断 |
@@ -323,11 +324,42 @@ MahjongPaper 使用 CraftEngine 处理以下内容：
 | `/mahjong deletetable [table_id]` | 管理员 | 删除牌桌 |
 | `/mahjong reload` | 管理员 | 重载配置 |
 
+## 棋牌室系统
+
+棋牌室是牌桌的空间容器，用于限制牌桌的创建位置、提供进出提醒和对局中离开倒计时。
+
+### 核心功能
+
+| 功能 | 说明 |
+| --- | --- |
+| 牌桌创建限制 | `gameRooms.restrictNewTables: true` 时，新牌桌只能在棋牌室内创建；棋牌室外的已有牌桌仍可正常使用 |
+| 进出提醒 | `gameRooms.enterExitMessages: true` 时，玩家进出棋牌室会收到提示消息 |
+| 离开倒计时 | 对局中的玩家离开棋牌室后开始倒计时（默认 60 秒），超时则强制结束对局；玩家返回棋牌室则取消倒计时 |
+
+### 倒计时警告节奏
+
+- 前段：每 15 秒提醒一次（如 60s、45s、30s、15s）
+- 最后 10 秒：10、8、6、5、4、3、2、1 逐秒倒计时
+
+### 配置项
+
+| 配置项 | 默认值 | 说明 |
+| --- | --- | --- |
+| `gameRooms.enabled` | `true` | 启用棋牌室系统 |
+| `gameRooms.restrictNewTables` | `true` | 限制新牌桌只能在棋牌室内创建 |
+| `gameRooms.enterExitMessages` | `true` | 进出棋牌室时显示提示 |
+| `gameRooms.leaveCountdownSeconds` | `60` | 离开倒计时秒数（最小 5） |
+| `gameRooms.defaultRadius` | `10` | 中心点创建棋牌室的默认半径 |
+| `gameRooms.defaultHeight` | `8` | 中心点创建棋牌室的默认高度 |
+| `gameRooms.file` | `game-rooms.yml` | 棋牌室持久化文件 |
+
+棋牌室数据保存在 `plugins/MahjongPaper/game-rooms.yml` 中。
+
 ## 常见问题
 
 ### 为什么我不能创建牌桌？
 
-`/mahjong create` 需要 `mahjongpaper.admin`。普通玩家只能加入、观战和进行牌局操作。
+`/mahjong create` 需要 `mahjongpaper.admin`。普通玩家只能加入、观战和进行牌局操作。此外，如果棋牌室系统已启用且 `gameRooms.restrictNewTables` 为 `true`，则牌桌只能在棋牌室内创建，在棋牌室外尝试创建会提示"必须在棋牌室内"。
 
 ### 为什么国标胡不了？
 

src/main/config-template/config.template.yml

@@ -53,6 +53,29 @@ tables:
     enabled: true
     file: tables.yml
 
+# {{gameroom.summary}}
+gameRooms:
+  # {{gameroom.enabled}}
+  enabled: true
+
+  # {{gameroom.restrict}}
+  restrictNewTables: true
+
+  # {{gameroom.messages}}
+  enterExitMessages: true
+
+  # {{gameroom.countdown}}
+  leaveCountdownSeconds: 60
+
+  # {{gameroom.radius}}
+  defaultRadius: 10
+
+  # {{gameroom.height}}
+  defaultHeight: 8
+
+  # {{gameroom.file}}
+  file: game-rooms.yml
+
 ranking:
   # {{ranking.summary}}
   enabled: true

src/main/config-template/config_comments_en.properties

@@ -15,6 +15,15 @@ tables.batch=How many persistent tables are rebuilt per tick after startup.
 tables.free_move=Allow players to move freely during a round without being treated as leaving.
 tables.persistence=Persistent tables are restored from this file on startup.
 
+gameroom.summary=Game rooms are spatial containers for mahjong tables. When enabled, tables can only be created inside a game room.
+gameroom.enabled=Enable the game room system. When disabled, tables can be created anywhere.
+gameroom.restrict=When true, new tables can only be created inside a game room. Existing tables outside rooms remain functional.
+gameroom.messages=Show enter/exit messages when players cross game room boundaries.
+gameroom.countdown=Seconds before a match is force-ended when an active player leaves the game room. Minimum 5 seconds.
+gameroom.radius=Default radius (blocks) when creating a game room from a center point.
+gameroom.height=Default height (blocks) when creating a game room from a center point.
+gameroom.file=File name for game room persistence, relative to the plugin data folder.
+
 ranking.summary=Mahjong Soul-style rank points and persistence (requires database.enabled=true).
 ranking.rooms=Supported room presets: BRONZE, SILVER, GOLD, JADE, THRONE
 

src/main/config-template/config_comments_zh_CN.properties

@@ -15,6 +15,15 @@ tables.batch=服务器启动后，每 tick 重建的持久化牌桌数量。
 tables.free_move=允许玩家在对局中自由移动且不被视为离桌。
 tables.persistence=启动时从该文件恢复持久化牌桌。
 
+gameroom.summary=棋牌室是牌桌的空间容器。启用后，牌桌只能在棋牌室内创建。
+gameroom.enabled=启用棋牌室系统。禁用后，牌桌可以在任意位置创建。
+gameroom.restrict=为 true 时，新牌桌只能在棋牌室内创建。棋牌室外的已有牌桌仍可正常使用。
+gameroom.messages=玩家进出棋牌室时显示提示消息。
+gameroom.countdown=对局中玩家离开棋牌室后，强制结束对局的倒计时秒数。最小 5 秒。
+gameroom.radius=以中心点创建棋牌室时的默认半径（方块数）。
+gameroom.height=以中心点创建棋牌室时的默认高度（方块数）。
+gameroom.file=棋牌室持久化文件名，相对于插件数据目录。
+
 ranking.summary=雀魂风格段位分与持久化（需要 database.enabled=true）。
 ranking.rooms=支持房间预设: BRONZE, SILVER, GOLD, JADE, THRONE
 

src/main/config-template/config_comments_zh_TW.properties

@@ -15,6 +15,15 @@ tables.batch=伺服器啟動後，每 tick 重建的持久化牌桌數量。
 tables.free_move=允許玩家在對局中自由移動且不視為離桌。
 tables.persistence=啟動時從此檔案還原持久化牌桌。
 
+gameroom.summary=棋牌室是牌桌的空間容器。啟用後，牌桌只能在棋牌室內建立。
+gameroom.enabled=啟用棋牌室系統。停用後，牌桌可以在任意位置建立。
+gameroom.restrict=為 true 時，新牌桌只能在棋牌室內建立。棋牌室外的已有牌桌仍可正常使用。
+gameroom.messages=玩家進出棋牌室時顯示提示訊息。
+gameroom.countdown=對局中玩家離開棋牌室後，強制結束對局的倒數計時秒數。最小 5 秒。
+gameroom.radius=以中心點建立棋牌室時的預設半徑（方塊數）。
+gameroom.height=以中心點建立棋牌室時的預設高度（方塊數）。
+gameroom.file=棋牌室持久化檔案名稱，相對於外掛資料夾。
+
 ranking.summary=雀魂風格段位分與持久化（需 database.enabled=true）。
 ranking.rooms=支援房間預設: BRONZE, SILVER, GOLD, JADE, THRONE