Gomoku — 英文版
Gomoku(五子棋)是一款适用于 Paper 1.20.4 的 Minecraft 小游戏插件。玩家将在自定义构建的棋盘上,于每个房间专属的虚空世界中体验经典的五子棋对弈。
当前版本:1.1.4
功能特性
- 基于异步批量生成的棋盘构建系统,拥有独立的虚空房间世界 —— 无需占用主线程
- 羊毛边框预览系统(异步操作,区块安全)
- 五子连珠胜负判定机制,配备统一的每回合计时器(默认 60 秒,可配置)
- 为当前行动的玩家显示绿色的“你的回合”标题及动作栏中的实时倒计时
- 超时判负 —— 本局不计分
- 比赛中死亡时,玩家将在配置的重生点复活
- 玩家统计数据:胜/负/平局次数 / 积分 / 胜率 / 等级
- 双语支持:简体中文 (zh_cn) 和英文 (en),提供带版本号的自刷新语言文件
- 侧边计分板,包含独立的大厅与游戏内布局,完全可配置且由占位符驱动
- PlaceholderAPI 扩展支持 TAB 列表、计分板、全息图等功能
- 兼容 Multiverse-Core 进行世界管理
- 红石物品用于取消匹配或切换观战模式
设置流程
所有房间管理命令均位于 /gomoku admin 之下。
/gomoku setlobby —— 设置主重生点。同时将该位置同步为该世界的原版重生点。此步骤为执行其他命令的前置条件。
/gomoku admin add <room> —— 创建一个虚空世界并将其注册为一个房间(传送你进入该世界,并切换至创造模式)
/gomoku admin playerspawn —— 站在玩家应开始的位置并运行此命令(必须在房间世界内)
/gomoku admin dish <size> —— 在棋盘将构建的位置显示羊毛边框预览(尺寸范围 15–64,间距 3)
/gomoku admin fill <line> <fill> <border> —— 在预览边框内部生成棋盘。每次构建都会缓存其 XYZ 坐标及创建序号(1, 2, 3, …),因此如果棋盘放置错误,可通过 /gomoku admin delete <no> 移除 —— 即使之前的序号被删除,剩余序号依然保持稳定。
/gomoku admin check <black> <white> —— 设置棋子名称,并从快捷栏第 1-2 槽读取方块材质
/gomoku admin save <room> —— 启用该房间供玩家使用(必须在房间世界内)。保存操作会保留最后一次构建的棋盘并清除其余缓存 —— 坐标仅在内存中保留至此时为止。
自动检测手工建造的棋盘(木斧头)
执行 /gomoku admin add 和 /gomoku admin build 会清空你的物品栏,并交给你一把木斧头(位于第 1 槽)。任何木斧头均可使用 —— 包括从创造模式菜单中获取的;当你手持它时,使用说明会自动显示。
| 输入 |
效果 |
| 手持斧头 |
动作栏显示使用说明;禁用方块破坏和方块交互 |
| 左键点击单元格的中间填充方块 |
检测棋盘并将其写入房间数据 |
| 右键点击 |
取消操作(同时取消活跃的 admin dish 预览) |
检测过程会从棋盘层向外遍历直至遇到空气,然后测量网格线之间的间距,并将其转换为房间的 size(尺寸)、interval(间距)、line(行数)、fill(填充)、center(中心)和 boardY(棋盘高度)。扫描成功后,只需设置玩家重生点并保存即可。
此第一版的功能限制:棋盘必须是虚空中孤立的、正方形的、单层的结构,并且具有每个单元格均匀的 3×3 填充区域以及单元格之间的网格线 —— 即单元格宽度 ≥ 3(interval 为 3 或 5)。由 admin fill 使用 interval 1(1 格单元格)生成的棋盘无法通过此方式检测。
命令
管理员 (gomoku.admin)
| 命令 |
描述 |
/gomoku setlobby |
在你当前位置设置大厅重生点(同时同步该世界的重生点) |
/gomoku admin add <room> |
创建带有独立虚空世界的新房间 |
/gomoku admin build <room> |
进入房间编辑模式(清空物品栏,获得木斧头,传送进入,禁用该房间)并打印就绪报告 |
/gomoku admin dish <size> |
羊毛边框预览(间距=3,异步区块安全) |
/gomoku admin fill <line> <fill> <border> |
在预览边框内部构建棋盘(异步批量处理) |
/gomoku admin check <black> <white> |
设置棋子名称 + 从快捷栏第 1-2 槽读取材质 |
/gomoku admin delete [no|list] |
移除缓存的棋盘构建记录(默认最新的一条);list 显示所有记录 |
/gomoku admin playerspawn |
设置玩家重生点(必须在房间世界内) |
/gomoku admin save <room> |
启用房间供玩家使用(必须在房间世界内),并将整个房间世界备份至 plugins/Gomoku/backups/<room> |
/gomoku admin clear <room> |
删除房间及其世界备份 |
/gomoku admin reload |
热重载语言、房间、大厅、统计数据和配置文件(包括注释语言) |
玩家 (gomoku.use, 默认开启)
| 命令 |
描述 |
/gomoku join <room> |
加入指定房间 |
/gomoku join auto |
自动匹配(优先级:等待中的房间 > 空闲房间) |
/gomoku spectate <room> |
观看正在进行比赛的房间(若比赛未开始则报错) |
/gomoku leave |
离开当前游戏或停止观战 |
/gomoku stats [player] |
查看统计数据 |
/gomoku gui |
打开房间列表 GUI(所有玩家可用) |
/gomoku pieceshop |
打开棋子商店 GUI(所有玩家可用) |
/gomoku help |
显示帮助信息(仅 gomoku.admin 权限可见管理员部分)—— 输出内容与直接输入 /gomoku 相同 |
规则守卫
| 规则 |
描述 |
| 必须设置大厅 |
除 setlobby 和 help 外的所有命令都要求先设置大厅 |
| 禁止在大厅建造 |
add 和 build 不能针对大厅世界执行 |
| 禁止在大厅编辑棋盘 |
dish / fill / check / delete 不能在大厅世界中执行 |
| 禁止在大厅设置重生点 |
playerspawn 不能在大厅世界中执行 |
| 禁止清除大厅 |
clear 不能删除大厅世界 |
| 必须在房间内保存 |
save 必须在房间自身的世界中执行 |
| 先保存再添加 |
如果身处未保存的房间世界中,需在 add 另一个房间前先对其执行 save |
游戏玩法
- 通过瞄准棋盘格子并左键点击来放置棋子。
- 两名玩家出生时均处于创造模式,且各自的物品快捷栏中装满其所属颜色的棋子方块。
- 每一步都有相同的时间预算(
turn-seconds,默认 60)。轮到的玩家会在标题栏看到绿色的**“你的回合”**字样,并在物品快捷栏上方的动作栏中看到倒计时。
- 超时则该局作废:双方均不得分(不分胜负,也不平局)。
- 前 5 步跳过胜利检测(早期不可能形成五连珠)。
- 棋盘填满即为平局。得分计算公式为
wins × 3 + draws。
- 观察者使用
/gomoku spectate <room> 加入观战 —— 只有实际处于对局中的房间才接受观察者,否则你会收到“not in a match”提示。观察者会被放入该房间的旁观者模式中。
- 当一局结束,房间内所有人 —— 包括两名玩家、所有观察者以及房间内其他任何仍站在世界里的玩家 —— 都会被传送回大厅。
- 快捷栏中的红石物品用于取消匹配。
- 在房间世界内或大厅世界内死亡,玩家会在配置的大厅处重生。
配置
plugins/Gomoku/config.yml:
locale: "zh_cn" # "zh_cn" 或 "en"
turn-seconds: 60 # 每步的时间预算
lobby:
set: true # 由 /gomoku setlobby 自动写入
world: world
x: -36.5
y: 76.0
z: -23.5
yaw: 0.0
pitch: 0.0
两个大厅快捷栏物品可以独立切换开关:
hotbar:
menu:
enabled: true # false = 隐藏房间菜单物品(现有物品也会被移除)
slot: 0
shop:
enabled: true # false = 隐藏棋子商店物品(现有物品也会被移除)
slot: 7
turn-seconds 会在每一回合开始时重新读取,因此编辑后甚至不需要执行 /gomoku admin reload。
计分板布局不在这里 —— 它们位于语言文件中(见下文)。
计分板
一个按玩家显示的侧边栏,包含三种布局:lobby(玩家在非对局状态时)、game(玩家正在游戏时)和 spectator(玩家正在观看对局时)。这些布局位于语言文件 (languages/zh_cn.yml, languages/en.yml) 下的 scoreboard: 部分,因此每种语言环境都可以拥有自己的文本,并且内容会随着 lang-version 的刷新而更新。
scoreboard.enabled — 设为 false 将完全禁用侧边栏(玩家将恢复原版计分板)
scoreboard.update-interval — 刷新的刻度数,默认为 20(1 秒)
scoreboard.<layout>.title — 侧边栏标题(最多 32 个字符);<layout> 可以是 lobby、game 或 spectator
scoreboard.<layout>.lines — 各行,从上到下;"" 渲染为空行(每行最多 64 个字符)
缺失的键会回退到内置默认值,因此手动精简的语言文件仍然有效。仍在 config.yml 中保留旧版 scoreboard: 部分的服务器也能正常工作,但一旦语言文件中定义了这些键,配置文件中的副本将被忽略,并在启动时记录警告日志。
存在 spectator 布局是因为观察者没有对手 —— %gomoku_opponent% 对他们返回 —。请改用 %gomoku_black_player% / %gomoku_white_player% 来列出双方。
每一行都会经过 %player% 和所有 %gomoku_xxx% 占位符的处理。不需要 PlaceholderAPI —— 我们自己的令牌会在内部解析。当安装了 PlaceholderAPI 时,也会解析来自其他插件(如 TAB、Vault 等)的占位符。
更改布局只需执行 /gomoku admin reload;它会重新读取配置并重绘所有在线玩家的界面。
棋子商店
玩家可以花费积分购买成对的黑白棋子外观。配置位于单独的 pieces.yml 文件中(首次启动时提取)。
menu:
slot: 7 # 倒数第二格快捷栏
material: CHEST
name: "&e&l棋子商店"
lore:
- "&7可用积分: &e{points}"
size: 27
title: "&8棋子商店 &7可用: &e{points}"
pieces:
concrete:
cost: 20 # 0 = 所有人都拥有
black:
material: BLACK_CONCRETE
name: "&0墨石"
white:
material: WHITE_CONCRETE
name: "&f白瓷"
- 一个箱子物品位于配置的快捷栏槽位(默认为
7 = 倒数第二格),点击时会打开商店 GUI。该物品带有标签,无法移动或丢弃,每当玩家返回大厅时会重新发放。
- 每个条目代表一对:必须同时包含
black 和 white,且必须使用不同的材质 —— 如果某条目重复使用了相同的方块,将被跳过并在控制台发出警告。
- 购买需要消耗积分 =
wins × 3 + draws − already spent。已消耗的积分按玩家单独追踪,因此终身 %gomoku_score% 永远不会减少;%gomoku_points% 显示剩余可用积分。
- 点击已拥有的条目可免费装备;点击锁定的条目会一次性购买并装备。
- 选择的一对仅在该玩家所在的未固定自身棋子的房间中使用。
/gomoku admin check 可将房间标记为固定,固定房间始终覆盖商店设置。在此功能之前配置的房间会通过其非默认的材质/名称被检测到。
- 从所选对中获取的棋子名称是游戏中在回合消息、
%gomoku_turn_piece% 占位符以及玩家快捷栏物品中显示的内容。
- 玩家的选择存储在
pieces-data.json 中;/gomoku admin reload 会重新读取这两个文件。
语言文件
文件位于 plugins/Gomoku/languages/ 目录下 —— zh_cn.yml 和 en.yml。除了所有的聊天消息外,它们还携带侧边栏计分板布局。每个文件都有一个 lang-version:
- 在启动时(以及执行
/gomoku admin reload 时),插件会将内置的 lang-version 与磁盘上的版本进行比较。
- 如果服务器副本较旧,它会被备份到
languages/backup/<name>-v<old>-<timestamp>.yml,然后被替换 —— 这样升级后的消息就能到达那些提取了旧修订版的服务器。
- 若要保留本地编辑,请将你文件中的
lang-version 提高到高于内置值的水平。
权限
| 权限 |
默认值 |
描述 |
gomoku.admin |
OP |
所有管理命令 |
gomoku.use |
true |
玩家命令 |
PlaceholderAPI
玩家占位符
| 占位符 |
示例 |
描述 |
%gomoku_room% |
a / — |
当前房间名称 |
%gomoku_state% |
WAITING PLAYING ENDED |
游戏状态 |
%gomoku_opponent% |
player1 / — |
对手名称( spectators 显示为 — ) |
%gomoku_color% |
黑子 白子 观战 / — |
你的角色(硬编码中文) |
%gomoku_black_player% |
player1 / — |
当前对局的黑方 |
%gomoku_white_player% |
player2 / — |
当前对局的白方 |
%gomoku_turn% |
player1 / — |
轮到谁行动 |
%gomoku_turn_piece% |
黑子 / 白子 / — |
当前行动方的棋子名称 |
%gomoku_timer% |
43 / — |
当前回合剩余秒数 |
%gomoku_countdown% |
黑子 player1 剩余43s |
单行摘要:棋子 + 玩家 + 秒数(格式在 papi-countdown 中定义) |
%gomoku_board_size% |
15 / — |
棋盘尺寸 |
%gomoku_move_count% |
12 / — |
已落子数量 |
%gomoku_wins% |
5 |
总胜场数 |
%gomoku_losses% |
2 |
总负场数 |
%gomoku_draws% |
1 |
总平局数 |
%gomoku_total_games% |
8 |
总局数 |
%gomoku_winrate% |
62.5% |
胜率 |
%gomoku_score% |
16 |
积分(胜+3,平+1) |
%gomoku_points% |
6 |
在棋子商店中仍可花费的点数 |
%gomoku_level% |
1 |
玩家等级 |
服务器占位符
| 占位符 |
示例 |
描述 |
%gomoku_room_count% |
3 |
房间总数 |
%gomoku_playing_room_count% |
2 |
正在进行对局的房间数 |
%gomoku_enabled_room_count% |
2 |
相同数值 — playing_room_count 的遗留别名 |
%gomoku_player_count% |
4 |
游戏中的玩家数 |
从源代码构建
需要 JDK 17(在 gradle.properties 中配置)。
./gradlew build # -> build/libs/Gomoku.jar
./gradlew proguard # -> build/libs/Gomoku-obf.jar (先运行 build)
./gradlew clean build proguard
将 jar 文件复制到服务器的 plugins/ 文件夹并重启即可部署。只能存在一个 Gomoku jar 文件——否则插件名称会发生冲突。
依赖项
- 必需: Paper 1.20.4+
- 可选: Multiverse-Core(世界管理)
- 可选: PlaceholderAPI(TAB / HUD / 记分板集成)
链接
许可证
本项目遵循 MIT 许可证。请参阅仓库根目录下的 LICENSE 文件。
1.1.3 — 功能概览 (English)
中文版在上面的章节;下面是同样的内容英文版。
The Chinese section above is followed by this English translation.
大厅
加入服务器会清空整个背包和盔甲栏,然后只发放两样物品(槽位可在 config.yml 中配置):
hotbar:
menu: # 下界之星:打开房间菜单
enabled: true
slot: 0
material: NETHER_STAR
name: "&b&l房间菜单"
lore:
- "&7左键 / 右键打开房间列表"
shop: # 箱子:棋子商店
enabled: true
slot: 7
- 左键或右键点击下界之星 → 54格房间菜单
- 空闲房间 = 合成台,点击加入(开始匹配)
- 进行中的房间 = 红石块,点击旁观
- 底部中间的铁砧 = 自动匹配
- 每个房间显示其棋盘尺寸和当前玩家数量
- 右键点击房间 = 与 AI 开始游戏,这会打开一行9个槽位:
空 绿 空 黄 空 橙 空 红 空
AI 难度
| 颜色 |
难度 |
后端 |
| 绿色 |
简单 |
内置 Java AI:40% 几率错过你的五连珠,55% 随机移动 |
| 黄色 |
普通 |
内置 AI,25% 几率从 Top 5 候选中挑选 |
| 橙色 |
困难 |
内置 AI,总是选择最佳移动 |
| 红色 |
地狱 |
RapFi 引擎(需要 pbrain-rapfi-windows-*.exe,仅限 15×15);不可用时显示为灰色羊毛 |
内置 AI 仅考虑现有棋子周围 2 格内的空格,并对五连珠/活四/冲四/活三/眠三/活二进行评分,攻击权重高于防御。
RapFi 使用标准的 Gomocup 协议(START / BOARD…DONE / INFO timeout_turn / END),每步限时 3 秒,超时保护 20 秒,并在不可用时自动回退到内置 AI。
匹配机制
- 左击房间开始匹配;如果 5 分钟内没有人类对手加入,则游戏将与 AI 开始(仅左击有效)
- 一旦有真实对手加入,倒计时立即取消
- 等待期间你手持一块标记为 “Leave match” 的红石——手持该红石时右键以取消匹配
对局过程中
- 第9个槽位始终持有带标签
gomoku:exit_item 的红石:第一次右键询问确认,第二次右键在 5 秒后离开;5 秒内的点击将被拒绝;10 秒后计时器重置
- 手持该红石时会禁用准星放置和方块放置
- 通过瞄准格子并左击来落子(射线距离520格,命中点必须至少深入格子0.3格内部)
- 最后一步用红色羊毛在其四个侧面高亮显示(保持在同一格子内)
- 结果个性化显示:赢家看到绿色的“你赢了”,输家看到红色的“你输了”,旁观者得到中性总结
- 当游戏结束(或服务器停止)时,整个石子层会被清除,但棋盘本身保留
音效
sounds:
start:
sound: BLOCK_WOODEN_DOOR_OPEN
volume: 1.0
pitch: 1.0
place:
sound: BLOCK_STONE_PLACE
volume: 1.0
pitch: 0.8 # 0.5 = deeper and slower, 2.0 = higher and faster; volume 0 = silent
创建棋盘(顺序很重要)
/gomoku admin add <room> 创建虚空世界并进入编辑模式
/gomoku admin dish 15 显示预览(此位置将成为棋盘位置)
/gomoku admin fill <line> <fill> <periphery> 在预览处构建;第三个参数是边界
/gomoku admin playerspawn 站在棋盘外并设置玩家出生点
/gomoku admin save <room> 保存并启用(房间名称为必填项)
fill 需要预览;如果没有预览,它将拒绝执行并要求你先运行 dish
- 每次
fill 都会先移除该世界中之前的棋盘,因此你永远不会拥有两个棋盘
- 在游戏开始时,插件会重新扫描世界中的网格以校准大小/中心/高度(日志行:
Board calibrated for 'x': 15x15 int=3 center=0,6 y=6),这样过时的坐标就不会再导致棋子偏移
木斧检测(编辑模式)
admin add / admin build 会清空你的物品栏并在第 1 格放入一把木斧:
- 左击网格线 → 检测整个棋盘(边界框、线间距、单元格数量),填充缺失的线段,并将结果写入房间
- 右击取消(也会取消正在运行的
dish 预览)
- 手持期间无法破坏或交互任何方块;任何木斧(包括创造模式下的)都会自动获得使用提示文本
- 扫描仅读取已加载的区块(不会卡住服务器),半径 240 格,每个棋盘最多 15 万格
命令
| 命令 |
描述 |
/gomoku help |
帮助 |
/gomoku setlobby |
设置大厅 |
/gomoku join <room|auto> |
加入房间 / 自动匹配 |
/gomoku spectate <room> |
观战(当房间未开始时发出警告) |
/gomoku leave |
离开对局 / 取消匹配 |
/gomoku stats [player] |
查看统计信息 |
/gomoku gui |
打开房间列表 GUI(所有玩家) |
/gomoku pieceshop |
打开棋子商店 GUI(所有玩家) |
/gomoku admin add <room> |
创建房间世界并进入编辑模式 |
/gomoku admin build <room> |
进入现有房间的编辑模式 |
/gomoku admin dish <size> |
显示棋盘预览 |
/gomoku admin fill <line> <fill> <periphery> |
在预览位置构建棋盘 |
/gomoku admin check <black> <white> |
设置此房间的棋子外观 |
/gomoku admin delete [no|list] |
删除缓存的棋盘坐标 |
/gomoku admin playerspawn |
设置房间出生点 |
/gomoku admin save <room> |
保存并启用房间 |
/gomoku admin clear <room> |
删除房间 |
/gomoku admin reload |
重新加载语言 / 棋子 / 配置 |
/gomoku admin debug |
打印当前状态(区域设置、文本、房间参数、会话、脚下的单元格) |
权限
| 权限 |
默认值 |
描述 |
gomoku.play |
everyone |
玩家命令 |
gomoku.admin |
OP |
管理员命令和木斧 |
占位符(PlaceholderAPI 可选)
%gomoku_wins% %gomoku_losses% %gomoku_draws% %gomoku_score% %gomoku_points%
%gomoku_room% %gomoku_state% %gomoku_turn% %gomoku_opponent% %gomoku_black_player% %gomoku_white_player%
%gomoku_black_score% %gomoku_white_score% %gomoku_timer% %gomoku_countdown% %gomoku_turn_piece%
%gomoku_spectator% %gomoku_spectator_count% %gomoku_room_count% %gomoku_playing_room_count%
记分板布局位于语言文件中(scoreboard:),包含独立的大厅 / 游戏 / 观战组。
1.1.4 更新日志
新增
/gomoku gui 和 /gomoku pieceshop 允许所有玩家打开房间列表和棋子商店。
- 大厅快捷栏物品可以独立切换:
hotbar.menu.enabled, hotbar.shop.enabled;禁用还会移除已给予的物品。
config.yml / pieces.yml 注释通过 locale 在中英文之间切换,无需更改值;旧文件将备份为 config.yml.bak / pieces.yml.bak。
- 启动时和
/gomoku admin reload 时的配置验证:缺失或类型错误的键将使用默认值并发出警告。
- 整房间世界备份/重置:
/gomoku admin save 将世界存储在 plugins/Gomoku/backups/<room> 下;对局结束后世界将被还原,移除 TNT、庆祝方块、烟花和棋子。
- 胜利庆祝间隔:
win-celebration.interval-ticks 和 win-celebration.corner-fireworks.interval-ticks。
- 语言感知的房间棋子名称:中文“黑子/白子”,英文“Black Stone/White Stone”。
lobby-protect:只有创造模式下的管理员才能在大厅中破坏或交互;房间保持其原始保护状态。
- 本地 SQLite 存储(
storage.type: sqlite),附带驱动程序。
gomoku admin reload 的英文控制台输出,避免 Windows 控制台的乱码问题。
- 中英文配置模板
config.yml / config_en.yml 和棋子模板 pieces.yml / pieces_en.yml。
修复
- 快捷栏“棋子商店 / 房间菜单”物品名称不遵循
locale;现有物品将在加入和重载时重新渲染。
- 在
admin save 期间因 session.lock 导致的世界备份失败。
- 当玩家仍在房间中时跳过世界重置;现在剩余玩家首先会被传送到大厅。
- 遗留的
hotbar.menu.name / pieces.yml menu.name 覆盖语言文本。
- 切换配置注释语言时合并了中英文注释行。
语言
lang-version: 36;新增 gui-in-game;帮助文本现在列出 /gomoku gui 和 /gomoku pieceshop。
Gomoku — 中文
Gomoku(五子棋)是一款面向 Paper 1.20.4 的 Minecraft 小游戏插件。玩家在各自房间的虚空世界中、在自定义搭建的棋盘上进行经典的五子连珠对弈。
当前版本:1.1.4
功能特性
- 每个房间拥有独立的虚空世界,棋盘异步分批生成 —— 不会造成主线程卡顿
- 羊毛边框预览系统(异步、区块安全)
- 五连获胜判定,每手统一计时(默认 60 秒,可配置)
- 轮到的玩家会看到绿色「该你了」标题,以及动作栏中的实时倒计时
- 超时则该局作废 —— 双方都不得分
- 对局中死亡会在配置的大厅处重生
- 玩家战绩:胜场 / 负场 / 平局 / 积分 / 胜率 / 等级
- 双语支持:中文(zh_cn)与英文(en),语言文件带版本号并可自动刷新
- 侧边栏计分板,大厅与对局使用不同布局,完全可配置且由占位符驱动
- 提供 PlaceholderAPI 扩展,可用于 TAB、计分板、全息影像等
- 兼容 Multiverse-Core,便于世界管理
- 红石物品用于取消匹配,支持观战模式
配置流程
所有房间相关命令都位于 /gomoku admin 之下。
/gomoku setlobby —— 设置主大厅。同时会把该位置同步为所在世界的原版重生点。执行其他任何命令前必须先完成此步。
/gomoku admin add <room> —— 创建一个虚空世界并将其注册为房间(会将你传送进去,并切换到创造模式)
/gomoku admin playerspawn —— 站在玩家应当出生的位置执行此命令(必须在房间世界内)
/gomoku admin dish <size> —— 在将要建造棋盘的位置显示羊毛边框预览(15–64,间隔 3)
/gomoku admin fill <line> <fill> <border> —— 在预览边框内生成棋盘。每次建造都会连同 XYZ 坐标和一个创建编号(1、2、3……)一起缓存,因此放错位置的棋盘可以用 /gomoku admin delete <no> 删除 —— 即使删除了前面的编号,其余编号也保持稳定。
/gomoku admin check <black> <white> —— 设置棋子名称,并从快捷栏第 1–2 格读取材质
/gomoku admin save <room> —— 对玩家开放该房间(必须在房间世界内)。保存会保留最后一次建造的棋盘,并丢弃其余缓存 —— 在此之前,坐标只存在于内存中。
自动识别手动搭建的棋盘(木斧)
/gomoku admin add 与 /gomoku admin build 会清空你的背包,并给你一把木斧(第 1 格)。任意木斧都可以 —— 包括从创造模式物品栏中拿出的;当你手持它时,会自动打上用法说明。
| 输入 |
效果 |
| 手持木斧 |
动作栏显示用法;禁止破坏方块和方块交互 |
| 左键点击某格中间的填充方块 |
识别整块棋盘并写入房间 |
| 右键 |
取消(同时取消进行中的 admin dish 预览) |
识别会从棋盘层向外逐层搜索,直到遇到空气,然后测量网格线之间的间距,并将其换算为房间的 size / interval / line / fill / center / boardY。扫描成功后,只需设置玩家出生点并保存即可。
这个最初版本的限制:棋盘必须是虚空中独立、正方形、单层的结构,每格为统一的 3×3 填充,且格子之间有网格线 —— 即格子宽度 ≥ 3(interval 为 3 或 5)。用 admin fill 且 interval 1(1 格宽的格子)生成的棋盘无法通过这种方式识别。
命令
管理员(gomoku.admin)
| 命令 |
说明 |
/gomoku setlobby |
将大厅出生点设置在你当前的位置(同时同步该世界的重生点) |
/gomoku admin add <room> |
新建一个带独立虚空世界的房间 |
/gomoku admin build <room> |
进入房间编辑模式(清空背包、发放木斧、传送进入、停用该房间),并打印就绪报告 |
/gomoku admin dish <size> |
羊毛边框预览(gap=3,异步且区块安全) |
/gomoku admin fill <line> <fill> <border> |
在预览边框内建造棋盘(异步分批) |
/gomoku admin check <black> <white> |
设置棋子名称 + 从快捷栏第 1–2 格读取材质 |
/gomoku admin delete [no|list] |
删除缓存的棋盘建造记录(默认删除最新的);list 列出全部记录 |
/gomoku admin playerspawn |
设置玩家出生点(必须在房间世界内) |
/gomoku admin save <room> |
对玩家开放该房间(必须在房间世界内),并把整个世界备份到 plugins/Gomoku/backups/<room> |
/gomoku admin clear <room> |
删除房间及其世界备份 |
/gomoku admin reload |
热重载语言、房间、大厅、战绩与配置(含注释语言) |
玩家(gomoku.use,默认 true)
| 命令 |
说明 |
/gomoku join <room> |
加入房间 |
/gomoku join auto |
自动匹配(优先级:等待中的房间 > 空闲房间) |
/gomoku spectate <room> |
观战当前正在对局的房间(若尚未开局则报错) |
/gomoku leave |
退出当前对局或停止观战 |
/gomoku stats [player] |
查看战绩 |
/gomoku gui |
打开房间列表界面(所有玩家可用) |
/gomoku pieceshop |
打开棋子商店界面(所有玩家可用) |
/gomoku help |
显示帮助(管理员部分仅对 gomoku.admin 可见)—— 输出与直接输入 /gomoku 相同 |
限制规则
| 规则 |
说明 |
| 必须先设大厅 |
除 setlobby 和 help 外,所有命令都要求先设置大厅 |
| 禁止在大厅建造 |
add 与 build 不能以大厅世界为目标 |
| 禁止在大厅编辑棋盘 |
dish / fill / check / delete 不能在大厅世界中使用 |
| 禁止在大厅设出生点 |
playerspawn 不能在大厅世界中使用 |
| 禁止删除大厅 |
clear 不能删除大厅世界 |
| 在房间内保存 |
save 必须在房间自己的世界中使用 |
| 先保存再新建 |
如果正站在一个未保存的房间世界中,需先 save 该房间,再 add 新房间 |
玩法
- 瞄准棋盘格子并左键点击即可落子。
- 双方玩家在出生点都会被设为创造模式,快捷栏装满各自棋子的方块。
- 每一手都有相同的思考时间(
turn-seconds,默认 60 秒)。轮到的玩家会看到绿色**「该你了」**标题,以及快捷栏上方动作栏中不断减少的倒计时。
- 时间耗尽则该局作废:双方都不计分(不算胜、不算负、也不算平局)。
- 前 5 手不进行胜负判定(这么早不可能出现五连)。
- 棋盘下满则为平局。积分为
胜场 × 3 + 平局。
- 观战者通过
/gomoku spectate <room> 加入 —— 只有真正处于对局中的房间才接受观战,否则会提示「未在对局中」。观战者会以旁观模式进入该房间。
- 一局结束时,房间内的所有人 —— 包括双方玩家、所有观战者,以及仍站在该房间世界中的其他人 —— 都会被传送回大厅。
- 快捷栏中的红石物品可取消匹配。
- 在房间世界或大厅世界中死亡,都会在配置的大厅处重生。
配置
plugins/Gomoku/config.yml:
locale: "zh_cn" # "zh_cn" 或 "en"
turn-seconds: 60 # 每一手的时间预算
lobby:
set: true # 由 /gomoku setlobby 自动写入
world: world
x: -36.5
y: 76.0
z: -23.5
yaw: 0.0
pitch: 0.0
大厅快捷栏物品可以分别开关:
hotbar:
menu:
enabled: true # false = 不显示房间菜单物品(已发放的也会移除)
slot: 0
shop:
enabled: true # false = 不显示棋子商店物品(已发放的也会移除)
slot: 7
turn-seconds 会在每一手开始时重新读取,因此修改后甚至不需要执行 /gomoku admin reload。
config.yml 的注释会随 locale 自动在中文/英文之间切换,配置值保持不变;启动和 /gomoku admin reload 时会检查缺失或类型错误的配置项并尝试补默认值。
计分板布局不在这里 —— 它们位于语言文件中(见下文)。
计分板
为每位玩家显示侧边栏,共三套布局:未在对局中时使用 lobby,对局进行中使用 game,观战时使用 spectator。这些布局位于语言文件(languages/zh_cn.yml、languages/en.yml)的 scoreboard: 段下,因此每种语言都可以带自己的文案,内容也会随 lang-version 刷新一起更新。
scoreboard.enabled —— 设为 false 将完全禁用侧边栏(玩家恢复使用原版计分板)
scoreboard.update-interval —— 刷新间隔(单位:tick),默认 20(1 秒)
scoreboard.<layout>.title —— 侧边栏标题(最多 32 个字符);<layout> 为 lobby、game 或 spectator
scoreboard.<layout>.lines —— 各行内容,自上而下;"" 渲染为空白行(每行最多 64 个字符)
缺失的键会回退到内置默认值,因此手工精简过的语言文件依然可用。仍在 config.yml 中保留旧 scoreboard: 段的服务器也能继续工作,但一旦语言文件定义了这些键,配置中的副本就会被忽略,并在启动时记录一条警告。
之所以需要观战布局,是因为观战者没有对手 —— 对他们而言 %gomoku_opponent% 会返回 —。可以改用 %gomoku_black_player% / %gomoku_white_player% 来列出双方。
每一行都会经过 %player% 以及所有 %gomoku_xxx% 占位符的替换。PlaceholderAPI 不是必需的 —— 插件自有的占位符由内部解析。如果确实安装了 PlaceholderAPI,其他插件(TAB、Vault……)的占位符也会一并解析。
修改布局后只需执行 /gomoku admin reload;它会重新读取配置并刷新所有在线玩家。
棋子商店
玩家可以花费积分购买黑/白棋子外观的成对组合。配置位于单独的 pieces.yml(首次启动时生成)。
menu:
slot: 7 # 快捷栏倒数第二格
material: CHEST
name: "&e&l棋子商店"
lore:
- "&7可用积分: &e{points}"
size: 27
title: "&8棋子商店 &7可用: &e{points}"
pieces:
concrete:
cost: 20 # 0 = 所有人已拥有
black:
material: BLACK_CONCRETE
name: "&0墨石"
white:
material: WHITE_CONCRETE
name: "&f白瓷"
- 一个箱子物品会放在配置的快捷栏格位(默认
7 = 倒数第二格),点击即可打开商店界面。该物品带有标签,无法移动或丢弃,并且玩家每次回到大厅时都会重新发放。
- 每个条目都是一对:
black 与 white 必须同时存在,且必须使用不同材质 —— 重复使用同一种方块的条目会被跳过,并在控制台输出警告。
- 购买需要消耗积分 =
胜场 × 3 + 平局 − 已花费。已花费积分按玩家单独记录,因此历史累计的 %gomoku_score% 永远不会减少;%gomoku_points% 显示当前仍可用的积分。
- 点击已拥有的条目即可免费装备;点击未解锁的条目会一次性完成购买并装备。
- 选定的组合只会在未固定自身棋子的房间中用于该玩家的棋子。
/gomoku admin check 会将房间标记为已固定,而固定过的房间始终优先于商店设置。在此功能之前配置过的房间,会通过其非默认的材质/名称被识别出来。
- 游戏在轮次提示、
%gomoku_turn_piece% 占位符以及玩家快捷栏物品中显示的,是所选组合的棋子名称。
- 玩家的选择保存在
pieces-data.json 中;/gomoku admin reload 会重新读取这两个文件。
语言文件
文件位于 plugins/Gomoku/languages/ —— 即 zh_cn.yml 与 en.yml。除所有聊天消息外,它们还包含侧边栏计分板布局。每个文件都有一个 lang-version:
- 启动时(以及执行
/gomoku admin reload 时),插件会将内置的 lang-version 与磁盘上的版本进行比较。
- 如果服务器上的副本较旧,会先备份到
languages/backup/<name>-v<old>-<timestamp>.yml,然后替换 —— 这样升级后的文案也能送达那些曾解压过旧版本的服务器。
- 若要保留本地修改,请把你文件中的
lang-version 提高到内置值之上。
权限
| 权限 |
默认 |
说明 |
gomoku.admin |
OP |
所有管理员命令 |
gomoku.use |
true |
玩家命令 |
PlaceholderAPI
玩家占位符
| 占位符 |
示例 |
说明 |
%gomoku_room% |
a / — |
当前房间名称 |
%gomoku_state% |
WAITING PLAYING ENDED |
对局状态 |
%gomoku_opponent% |
player1 / — |
对手名称(观战者为 —) |
%gomoku_color% |
黑子 白子 观战 / — |
你的身份(硬编码中文) |
%gomoku_black_player% |
player1 / — |
当前对局的黑方 |
%gomoku_white_player% |
player2 / — |
当前对局的白方 |
%gomoku_turn% |
player1 / — |
当前轮到的玩家 |
%gomoku_turn_piece% |
黑子 / 白子 / — |
当前落子方的棋子名称 |
%gomoku_timer% |
43 / — |
当前这一手剩余的秒数 |
%gomoku_countdown% |
黑子 player1 剩余43s |
单行摘要:棋子 + 玩家 + 秒数(格式在 papi-countdown 中配置) |
%gomoku_board_size% |
15 / — |
棋盘尺寸 |
%gomoku_move_count% |
12 / — |
已落子数 |
%gomoku_wins% |
5 |
总胜场 |
%gomoku_losses% |
2 |
总负场 |
%gomoku_draws% |
1 |
总平局 |
%gomoku_total_games% |
8 |
对局总数 |
%gomoku_winrate% |
62.5% |
胜率 |
%gomoku_score% |
16 |
积分(胜 +3,平 +1) |
%gomoku_points% |
6 |
棋子商店中仍可消费的积分 |
%gomoku_level% |
1 |
玩家等级 |
服务器占位符
| 占位符 |
示例 |
说明 |
%gomoku_room_count% |
3 |
房间总数 |
%gomoku_playing_room_count% |
2 |
当前正在对局的房间数 |
%gomoku_enabled_room_count% |
2 |
数值相同 —— playing_room_count 的旧别名 |
%gomoku_player_count% |
4 |
对局中的玩家数 |
从源码构建
需要 JDK 17(在 gradle.properties 中配置)。
./gradlew build # -> build/libs/Gomoku.jar
./gradlew proguard # -> build/libs/Gomoku-obf.jar(会先执行 build)
./gradlew clean build proguard
部署时把 jar 复制到服务器的 plugins/ 目录并重启即可。只能存在一个 Gomoku jar —— 否则插件名称会冲突。
依赖
- 必需: Paper 1.20.4+
- 可选: Multiverse-Core(世界管理)
- 可选: PlaceholderAPI(TAB / HUD / 计分板集成)
链接
许可证
本项目使用 MIT License,详见仓库根目录的 LICENSE。
1.1.3 — 功能总览
大厅
进服时强制清空背包和盔甲,然后只发两件物品(位置可在 config.yml 调):
hotbar:
menu: # 下界之星: 打开房间菜单
enabled: true
slot: 0
material: NETHER_STAR
name: "&b&l房间菜单"
lore:
- "&7左键 / 右键 打开房间列表"
shop: # 箱子: 棋子商店
enabled: true
slot: 7
- 左键或右键下界之星 → 54 格房间菜单
- 空闲房间 = 工作台,点击加入(开始匹配)
- 对局中房间 = 红石块,点击观战
- 底部中间铁砧 = 自动匹配
- 每个房间显示棋盘尺寸和当前人数
- 右键房间 = 直接和 AI 开局,弹出 9 格等级选择:
空 绿 空 黄 空 橙 空 红 空
AI 等级
| 颜色 |
等级 |
后端 |
| 绿 |
简单 |
内置 Java AI,40% 不堵你的成五、55% 随机落子 |
| 黄 |
普通 |
内置 AI,25% 从前 5 名候选随机 |
| 橙 |
困难 |
内置 AI,始终最优 |
| 红 |
地狱 |
RapFi 引擎(需 pbrain-rapfi-windows-*.exe,仅 15×15);未接入时显示灰色羊毛 |
内置 AI 只算已有棋子周围 2 格,按五连/活四/冲四/活三/眠三/活二评分,进攻权重高于防守。
RapFi 走标准 Gomocup 协议(START / BOARD…DONE / INFO timeout_turn / END),单步 3 秒上限、20 秒看门狗,失败自动回退内置 AI。
匹配
- 左键房间开始匹配,5 分钟未等到真人 → 自动转 AI 对局(只对左键生效)
- 匹配中或开局时匹配到真人,计时立刻作废
- 等待匹配时手上有一颗「退出对局」红石,手持右键取消匹配
对局中
- 第 8 格固定发放带
gomoku:exit_item 标签的红石:右键第一次提示确认,5 秒后再右键退出;5 秒内点击无效;超过 10 秒重新计时
- 手持该红石时不触发射线落子、不能放置方块
- 落子方式:瞄准格子左键(520 格射线,命中点需在格子内 0.3 格以上)
- 最近一步棋子四周用红色羊毛高亮(同格子内,不会越界)
- 胜负只告诉本人:赢家看到绿色「你赢了」,输家看到红色「你输了」,观战者看中立总结
- 对局结束 / 停服时棋子层整片清成空气,棋盘本体保留
音效
sounds:
start:
sound: BLOCK_WOODEN_DOOR_OPEN
volume: 1.0
pitch: 1.0
place:
sound: BLOCK_STONE_PLACE
volume: 1.0
pitch: 0.8 # 0.5 更沉更慢, 2.0 更尖更快; volume 0 = 静音
建棋盘流程(严格顺序)
/gomoku admin add <房间> 建虚空世界并进入编辑模式
/gomoku admin dish 15 生成预览(位置就是最终棋盘位置)
/gomoku admin fill 线 填充 外围 按预览位置铺板,第三个参数是边界,边界及之外不能落子
/gomoku admin playerspawn 站在棋盘外侧设置出生点
/gomoku admin save <房间> 保存并启用(必须带房间名)
fill 必须在有预览时执行,否则提示先 dish
- 每次
fill 会先清掉这个世界里上一次的棋盘,避免出现多块板
- 开局时插件会从世界重新扫描井字格校准尺寸/中心/高度(日志:
Board calibrated for 'x': 15x15 int=3 center=0,6 y=6),所以配置里的坐标不会影响落子准确性
木斧识别(编辑模式)
admin add / admin build 会清空背包并在第 1 格给一把木斧:
- 左键点井字线 → 自动扫描整块棋盘(外接框、线间距、网格数),缺失的线自动补齐,结果直接写入房间
- 右键取消(同时取消
dish 预览)
- 手持时不破坏方块、不触发方块交互;任意木斧(含创造模式取的)都会被自动打上用法
- 扫描只读已加载区块(不会卡服),半径 240 格,单块棋盘最多 15 万方块
命令
| 命令 |
说明 |
/gomoku help |
帮助 |
/gomoku setlobby |
设置大厅 |
/gomoku join <房间|auto> |
加入房间 / 自动匹配 |
/gomoku spectate <房间> |
观战(房间未开始会提示) |
/gomoku leave |
退出对局 / 取消匹配 |
/gomoku stats [玩家] |
战绩查询 |
/gomoku gui |
打开房间列表界面(所有玩家可用) |
/gomoku pieceshop |
打开棋子商店界面(所有玩家可用) |
/gomoku admin add <房间> |
新建房间世界并进入编辑模式 |
/gomoku admin build <房间> |
进入已有房间的编辑模式 |
/gomoku admin dish <大小> |
生成棋盘预览 |
/gomoku admin fill <线> <填充> <外围> |
按预览位置生成棋盘 |
/gomoku admin check <黑子名> <白子名> |
设置本房间棋子外观 |
/gomoku admin delete [编号|list] |
删除缓存的棋盘坐标 |
/gomoku admin playerspawn |
设置房间出生点 |
/gomoku admin save <房间> |
保存并启用房间 |
/gomoku admin clear <房间> |
删除房间 |
/gomoku admin reload |
重载语言/棋子/配置 |
/gomoku admin debug |
打印当前状态(locale、文案、房间参数、会话、脚下格子) |
权限
| 权限 |
默认 |
说明 |
gomoku.play |
所有玩家 |
使用玩家命令 |
gomoku.admin |
OP |
管理员命令、木斧识别 |
占位符(PlaceholderAPI 可选)
%gomoku_wins% %gomoku_losses% %gomoku_draws% %gomoku_score% %gomoku_points%
%gomoku_room% %gomoku_state% %gomoku_turn% %gomoku_opponent% %gomoku_black_player% %gomoku_white_player%
%gomoku_black_score% %gomoku_white_score% %gomoku_timer% %gomoku_countdown% %gomoku_turn_piece%
%gomoku_spectator% %gomoku_spectator_count% %gomoku_room_count% %gomoku_playing_room_count%
计分板布局写在语言文件里(scoreboard: 段),支持大厅 / 对局 / 观战三套。
1.1.4 更新日志
新增
- 新增
/gomoku gui 与 /gomoku pieceshop,所有玩家可打开房间列表和棋子商店界面。
- 大厅快捷栏物品可独立开关显示:
hotbar.menu.enabled、hotbar.shop.enabled;关闭时已发放的物品也会被移除。
config.yml / pieces.yml 的注释随 locale 自动切换中英文,配置值保持不变;切换前备份为 config.yml.bak / pieces.yml.bak。
- 启动和
/gomoku admin reload 时自动检查配置:缺失或类型错误的键会补默认值并提示。
- 房间世界整世界备份与重置:
/gomoku admin save 备份到 plugins/Gomoku/backups/<room>,对局结束后自动恢复,清除 TNT、庆祝方块、烟花与棋子。
- 赢家庆祝生成间隔:
win-celebration.interval-ticks 与 win-celebration.corner-fireworks.interval-ticks。
- 房间棋子默认名随语言:中文“黑子/白子”,英文“Black Stone/White Stone”。
- 大厅保护
lobby-protect:仅管理员+创造模式可破坏/交互;房间沿用原保护逻辑。
- SQLite 本地存储(
storage.type: sqlite),驱动已内置,无需额外下载。
- 控制台支持英文
gomoku admin reload,避免中文乱码。
- 中文/英文配置模板:
config.yml / config_en.yml;棋子模板:pieces.yml / pieces_en.yml。
修复
- 快捷栏“棋子商店 / 房间菜单”物品名不随
locale 更新的问题;进服和 reload 会原地重绘已有物品。
admin save 因 session.lock 导致整世界备份失败。
- 重置世界时房间内仍有玩家会跳过;现在先把剩余玩家传回大厅再重置。
- 旧配置
hotbar.menu.name / pieces.yml menu.name 覆盖语言文本的问题。
- 配置注释切换时中英文注释行被错误合并的问题。
语言
lang-version: 36,新增 gui-in-game,帮助文本加入 /gomoku gui、/gomoku pieceshop。
Gomoku — English
Gomoku (五子棋) is a Minecraft minigame plugin for Paper 1.20.4. Players compete in a classic five-in-a-row board game on custom-built boards inside per-room void worlds.
Current version: 1.1.4
Features
- Per-room void worlds with async batched board generation — no main-thread stalls
- Wool border preview system (async, chunk-safe)
- 5-in-a-row win detection with a uniform per-move clock (default 60s, configurable)
- Green "your turn" title plus a live countdown in the action bar, for the player on move
- Timeouts void the round — neither player scores
- Dying during a match respawns the player at the configured lobby
- Player stats: wins / losses / draws / score / win rate / level
- Bilingual: Chinese (zh_cn) and English (en), with versioned language files that refresh themselves
- Sidebar scoreboard with separate lobby and in-game layouts, fully configurable and placeholder-driven
- PlaceholderAPI expansion for TAB, scoreboards, holograms, etc.
- Multiverse-Core compatible for world management
- Redstone item to cancel matchmaking, spectator mode
Setup Flow
Every room command lives under /gomoku admin.
/gomoku setlobby — Set the main lobby. Also mirrors the location into that world's vanilla respawn point. Required before any other command.
/gomoku admin add <room> — Create a void world and register it as a room (teleports you in, creative mode)
/gomoku admin playerspawn — Stand where players should start and run this (must be inside the room world)
/gomoku admin dish <size> — Show the wool border preview where the board will be built (15–64, gap 3)
/gomoku admin fill <line> <fill> <border> — Generate the board inside the preview border. Every build is cached with its XYZ coordinates and a creation number (1, 2, 3, …), so a misplaced board can be removed with /gomoku admin delete <no> — the numbers stay stable even after earlier ones are deleted.
/gomoku admin check <black> <white> — Set piece names and read the materials from hotbar slots 1–2
/gomoku admin save <room> — Enable the room for players (must be inside the room world). Saving keeps the last built board and drops the rest of the cache — the coordinates only live in memory until then.
Auto-detecting a hand-built board (wooden axe)
/gomoku admin add and /gomoku admin build empty your inventory and hand you a wooden axe (slot 1). Any wooden axe works — including one pulled from the creative menu; the usage text is stamped on automatically when you hold it.
| Input |
Effect |
| Hold the axe |
usage shown in the action bar; block breaking and block interaction are disabled |
| Left-click the middle fill block of a cell |
detects the board and writes it into the room |
| Right-click |
cancels (also cancels an active admin dish preview) |
Detection walks the board layer outward until it hits air, then measures the spacing between grid lines and converts that into size / interval / line / fill / center / boardY for the room. After a successful scan just set the player spawn and save.
Limitations of this first version: the board has to be an isolated, square, single-layer structure in the void with a uniform 3×3 fill per cell and grid lines between cells — i.e. cell width ≥ 3 (interval 3 or 5). Boards generated by admin fill with interval 1 (1-block cells) are not detectable this way.
Commands
Admin (gomoku.admin)
| Command |
Description |
/gomoku setlobby |
Set lobby spawn at your location (also syncs that world's respawn point) |
/gomoku admin add <room> |
Create a new room with its own void world |
/gomoku admin build <room> |
Enter room edit mode (empty inventory, wooden axe, teleport in, disable the room) and print a readiness report |
/gomoku admin dish <size> |
Wool border preview (gap=3, async chunk-safe) |
/gomoku admin fill <line> <fill> <border> |
Build board inside the preview border (async batched) |
/gomoku admin check <black> <white> |
Set piece names + read materials from hotbar slots 1–2 |
/gomoku admin delete [no|list] |
Remove a cached board build (newest by default); list shows them |
/gomoku admin playerspawn |
Set player spawn point (must be in a room world) |
/gomoku admin save <room> |
Enable the room for players (must be in the room world) and back up its whole world to plugins/Gomoku/backups/<room> |
/gomoku admin clear <room> |
Delete room and its world backup |
/gomoku admin reload |
Hot-reload language, rooms, lobby, stats and config (including comment language) |
Player (gomoku.use, default true)
| Command |
Description |
/gomoku join <room> |
Join a room |
/gomoku join auto |
Auto-match (priority: waiting rooms > idle rooms) |
/gomoku spectate <room> |
Watch a room that is currently in a match (error if it hasn't started) |
/gomoku leave |
Leave current game or stop spectating |
/gomoku stats [player] |
View stats |
/gomoku gui |
Open the room list GUI (all players) |
/gomoku pieceshop |
Open the piece shop GUI (all players) |
/gomoku help |
Show help (admin section only for gomoku.admin) — same output as bare /gomoku |
Guards
| Rule |
Description |
| Lobby required |
All commands except setlobby and help require the lobby to be set first |
| No lobby build |
add and build cannot target the lobby world |
| No lobby board edit |
dish / fill / check / delete cannot be used in the lobby world |
| No lobby spawn |
playerspawn cannot be used in the lobby world |
| No lobby clear |
clear cannot delete the lobby world |
| Save in-room |
save must be used inside the room's own world |
| Add after save |
If standing in an unsaved room world, save it before adding another |
Gameplay
- Stones are placed by aiming at a board cell and left-clicking.
- Both players are put in creative mode at their spawn with a full hotbar of their own piece block.
- Every move has the same time budget (
turn-seconds, default 60). The player on move sees a green "your turn" title and a countdown ticking down in the action bar above the hotbar.
- Running out of time voids the round: neither player is awarded points (no win, no loss, no draw).
- The first 5 moves skip win detection (a five-in-a-row is impossible that early).
- A full board is a draw. Score is
wins × 3 + draws.
- Spectators join with
/gomoku spectate <room> — only rooms that are actually in a match accept spectators, otherwise you get "not in a match". Spectators are dropped into the room in spectator mode.
- When a round ends, everyone in the room — both players and all spectators, plus anyone else still standing in the room world — is teleported back to the lobby.
- A redstone item in the hotbar cancels matchmaking.
- Dying inside a room world — or inside the lobby world — respawns the player at the configured lobby.
Configuration
plugins/Gomoku/config.yml:
locale: "zh_cn" # "zh_cn" or "en"
turn-seconds: 60 # time budget for every move
lobby:
set: true # written automatically by /gomoku setlobby
world: world
x: -36.5
y: 76.0
z: -23.5
yaw: 0.0
pitch: 0.0
The two lobby hotbar items can be toggled independently:
hotbar:
menu:
enabled: true # false = hide the room menu item (existing items are removed too)
slot: 0
shop:
enabled: true # false = hide the piece shop item (existing items are removed too)
slot: 7
turn-seconds is re-read at the start of every turn, so /gomoku admin reload is not even required after editing it.
Scoreboard layouts are not here — they live in the language files (see below).
Scoreboard
A per-player sidebar with three layouts: lobby while the player is not in a match, game while they are playing, and spectator while they are watching a match. The layouts live under scoreboard: in the language files (languages/zh_cn.yml, languages/en.yml), so each locale can carry its own text and the content travels with lang-version refreshes.
scoreboard.enabled — false disables the sidebar entirely (players get the vanilla scoreboard back)
scoreboard.update-interval — refresh in ticks, default 20 (1 second)
scoreboard.<layout>.title — sidebar title (32 chars max); <layout> is lobby, game or spectator
scoreboard.<layout>.lines — the rows, top to bottom; "" renders a blank row (64 chars max per row)
Missing keys fall back to built-in defaults, so a hand-trimmed language file still works. Servers that still keep an old scoreboard: section in config.yml keep working too, but once the language file defines the keys the config copy is ignored and a warning is logged on startup.
The spectator layout exists because a spectator has no opponent — %gomoku_opponent% returns — for them. Use %gomoku_black_player% / %gomoku_white_player% to list both sides instead.
Every row goes through %player% and all %gomoku_xxx% placeholders. PlaceholderAPI is not required — our own tokens are resolved internally. When PlaceholderAPI is installed, placeholders from other plugins (TAB, Vault, …) are resolved as well.
Changing the layout only needs /gomoku admin reload; it re-reads the config and repaints every online player.
Piece Shop
Players can spend points on pairs of black/white piece looks. Config lives in a separate pieces.yml (extracted on first start).
menu:
slot: 7 # second-to-last hotbar slot
material: CHEST
name: "&e&l棋子商店"
lore:
- "&7可用积分: &e{points}"
size: 27
title: "&8棋子商店 &7可用: &e{points}"
pieces:
concrete:
cost: 20 # 0 = owned by everyone
black:
material: BLACK_CONCRETE
name: "&0墨石"
white:
material: WHITE_CONCRETE
name: "&f白瓷"
- A chest item sits in the configured hotbar slot (default
7 = 倒数第二格) and opens the shop GUI when clicked. The item is tagged, cannot be moved or dropped, and is re-issued whenever a player returns to the lobby.
- Each entry is one pair:
black and white must both be present and must use different materials — an entry that repeats the same block is skipped with a console warning.
- Buying costs points =
wins × 3 + draws − already spent. Spent points are tracked per player, so the lifetime %gomoku_score% is never reduced; %gomoku_points% shows what is still available.
- Clicking an owned entry equips it for free; clicking a locked entry buys and equips it in one go.
- The chosen pair is used for that player's stones only in rooms that did not pin their own pieces.
/gomoku admin check marks a room as pinned, and a pinned room always overrides the shop. Rooms that were configured before this feature are detected by their non-default materials/names.
- The piece names from the chosen pair are what the game shows in the turn message, the
%gomoku_turn_piece% placeholder and the item in the player's hotbar.
- Player selections are stored in
pieces-data.json; /gomoku admin reload re-reads both files.
Language Files
Files live in plugins/Gomoku/languages/ — zh_cn.yml and en.yml. Besides all chat messages they also carry the sidebar scoreboard layouts. Each file has a lang-version:
- On startup (and on
/gomoku admin reload) the plugin compares the bundled lang-version with the one on disk.
- If the server copy is older it is backed up to
languages/backup/<name>-v<old>-<timestamp>.yml, then replaced — so upgraded messages reach servers that extracted an older revision.
- To keep local edits, raise
lang-version in your file above the bundled value.
Permissions
| Permission |
Default |
Description |
gomoku.admin |
OP |
All admin commands |
gomoku.use |
true |
Player commands |
PlaceholderAPI
Player placeholders
| Placeholder |
Example |
Description |
%gomoku_room% |
a / — |
Current room name |
%gomoku_state% |
WAITING PLAYING ENDED |
Game state |
%gomoku_opponent% |
player1 / — |
Opponent name (— for spectators) |
%gomoku_color% |
黑子 白子 观战 / — |
Your role (hardcoded Chinese) |
%gomoku_black_player% |
player1 / — |
Black side of the current match |
%gomoku_white_player% |
player2 / — |
White side of the current match |
%gomoku_turn% |
player1 / — |
Player whose turn it is |
%gomoku_turn_piece% |
黑子 / 白子 / — |
Piece name of the side on move |
%gomoku_timer% |
43 / — |
Seconds left in the current turn |
%gomoku_countdown% |
黑子 player1 剩余43s |
One-line summary: piece + player + seconds (format in papi-countdown) |
%gomoku_board_size% |
15 / — |
Board dimensions |
%gomoku_move_count% |
12 / — |
Stones placed |
%gomoku_wins% |
5 |
Total wins |
%gomoku_losses% |
2 |
Total losses |
%gomoku_draws% |
1 |
Total draws |
%gomoku_total_games% |
8 |
Total games played |
%gomoku_winrate% |
62.5% |
Win rate |
%gomoku_score% |
16 |
Score (win +3, draw +1) |
%gomoku_points% |
6 |
Points still spendable in the piece shop |
%gomoku_level% |
1 |
Player level |
Server placeholders
| Placeholder |
Example |
Description |
%gomoku_room_count% |
3 |
Total rooms |
%gomoku_playing_room_count% |
2 |
Rooms currently in a match |
%gomoku_enabled_room_count% |
2 |
Same value — legacy alias of playing_room_count |
%gomoku_player_count% |
4 |
Players in games |
Building from source
Requires JDK 17 (configured in gradle.properties).
./gradlew build # -> build/libs/Gomoku.jar
./gradlew proguard # -> build/libs/Gomoku-obf.jar (runs build first)
./gradlew clean build proguard
Deploy by copying the jar into the server's plugins/ folder and restarting. Only one Gomoku jar may be present — the plugin name would otherwise collide.
Dependencies
- Required: Paper 1.20.4+
- Optional: Multiverse-Core (world management)
- Optional: PlaceholderAPI (TAB / HUD / scoreboard integration)
Links
License
This project is licensed under the MIT License. See LICENSE in the repository root.
1.1.3 — Feature Overview (English)
中文版在上面的章节;下面是同样的内容英文版。
The Chinese section above is followed by this English translation.
Lobby
Joining the server clears the whole inventory and armour, then only two items are handed out (slots are configurable in config.yml):
hotbar:
menu: # Nether star: opens the room menu
enabled: true
slot: 0
material: NETHER_STAR
name: "&b&lRoom Menu"
lore:
- "&7Left / right click to open the room list"
shop: # Chest: piece shop
enabled: true
slot: 7
- Left or right click the nether star → 54-slot room menu
- free room = crafting table, click to join (starts matchmaking)
- running room = redstone block, click to spectate
- anvil in the bottom middle = auto match
- each room shows its board size and current player count
- Right-click a room = start a game against the AI, which opens a 9-slot row:
empty green empty yellow empty orange empty red empty
AI levels
| Colour |
Level |
Backend |
| Green |
Easy |
Built-in Java AI: 40% chance to miss your five-in-a-row, 55% random moves |
| Yellow |
Normal |
Built-in AI, 25% chance to pick from the top 5 candidates |
| Orange |
Hard |
Built-in AI, always the best move |
| Red |
Hell |
RapFi engine (needs pbrain-rapfi-windows-*.exe, 15×15 only); shows as grey wool when unavailable |
The built-in AI only considers empty cells within 2 blocks of an existing stone and scores five / open four / four / open three / blocked three / open two, weighting attack above defence.
RapFi speaks the standard Gomocup protocol (START / BOARD…DONE / INFO timeout_turn / END) with a 3 second per-move budget, a 20 second watchdog and an automatic fallback to the built-in AI.
Matchmaking
- Left-clicking a room starts matchmaking; if no human opponent joins within 5 minutes the game is started against the AI (left-click only)
- The countdown is cancelled as soon as a real opponent joins
- While waiting you hold a "Leave match" redstone — right-click while holding it to cancel matchmaking
During a match
- Slot 9 always holds a redstone tagged with
gomoku:exit_item: first right-click asks for confirmation, a second right-click 5 seconds later leaves; clicks within 5 seconds are rejected; after 10 seconds the timer restarts
- Holding that redstone disables crosshair placement and block placing
- Place a stone by aiming at a cell and left-clicking (520-block ray, hit point must be at least 0.3 blocks inside the cell)
- The last move is highlighted with red wool on its four sides (kept inside the same cell)
- Results are personalised: the winner sees a green "You win", the loser a red "You lost", spectators get a neutral summary
- When the game ends (or the server stops) the whole stone layer is cleared while the board itself is kept
Sounds
sounds:
start:
sound: BLOCK_WOODEN_DOOR_OPEN
volume: 1.0
pitch: 1.0
place:
sound: BLOCK_STONE_PLACE
volume: 1.0
pitch: 0.8 # 0.5 = deeper and slower, 2.0 = higher and faster; volume 0 = silent
Creating a board (order matters)
/gomoku admin add <room> create a void world and enter edit mode
/gomoku admin dish 15 show the preview (this position becomes the board position)
/gomoku admin fill <line> <fill> <periphery> build at the preview; the third argument is the boundary
/gomoku admin playerspawn stand outside the board and set the player spawn
/gomoku admin save <room> save and enable (the room name is required)
fill requires a preview; without one it refuses and asks you to run dish first
- every
fill first removes the previous board in that world, so you never end up with two boards
- at game start the plugin re-scans the grid in the world to calibrate size / centre / height (log line:
Board calibrated for 'x': 15x15 int=3 center=0,6 y=6), so stale coordinates can no longer shift the stones
Wooden axe detection (edit mode)
admin add / admin build clear your inventory and put a wooden axe in slot 1:
- left-click a grid line → the whole board is detected (bounding box, line spacing, cell count), missing line blocks are filled in, and the result is written into the room
- right-click cancels (also cancels a running
dish preview)
- while held no blocks can be broken or interacted with; any wooden axe (including creative ones) gets the usage lore automatically
- the scan only reads loaded chunks (it can never hang the server), radius 240 blocks, up to 150k blocks per board
Commands
| Command |
Description |
/gomoku help |
help |
/gomoku setlobby |
set the lobby |
/gomoku join <room|auto> |
join a room / auto match |
/gomoku spectate <room> |
spectate (warns when the room has not started) |
/gomoku leave |
leave a match / cancel matchmaking |
/gomoku stats [player] |
stats lookup |
/gomoku gui |
Open the room list GUI (all players) |
/gomoku pieceshop |
Open the piece shop GUI (all players) |
/gomoku admin add <room> |
create a room world and enter edit mode |
/gomoku admin build <room> |
enter edit mode for an existing room |
/gomoku admin dish <size> |
show a board preview |
/gomoku admin fill <line> <fill> <periphery> |
build the board at the preview position |
/gomoku admin check <black> <white> |
set this room's piece appearance |
/gomoku admin delete [no|list] |
delete cached board coordinates |
/gomoku admin playerspawn |
set the room spawn |
/gomoku admin save <room> |
save and enable a room |
/gomoku admin clear <room> |
delete a room |
/gomoku admin reload |
reload language / pieces / config |
/gomoku admin debug |
print the current state (locale, texts, room params, session, cell under you) |
Permissions
| Permission |
Default |
Description |
gomoku.play |
everyone |
player commands |
gomoku.admin |
OP |
admin commands and the wooden axe |
Placeholders (PlaceholderAPI optional)
%gomoku_wins% %gomoku_losses% %gomoku_draws% %gomoku_score% %gomoku_points%
%gomoku_room% %gomoku_state% %gomoku_turn% %gomoku_opponent% %gomoku_black_player% %gomoku_white_player%
%gomoku_black_score% %gomoku_white_score% %gomoku_timer% %gomoku_countdown% %gomoku_turn_piece%
%gomoku_spectator% %gomoku_spectator_count% %gomoku_room_count% %gomoku_playing_room_count%
Scoreboard layouts live in the language files (scoreboard:) with separate lobby / game / spectator sets.
1.1.4 Changelog
Added
/gomoku gui and /gomoku pieceshop for all players to open the room list and piece shop.
- Lobby hotbar items can be toggled independently:
hotbar.menu.enabled, hotbar.shop.enabled; disabling also removes items already given.
config.yml / pieces.yml comments switch between Chinese and English with locale, without changing values; the old file is backed up as config.yml.bak / pieces.yml.bak.
- Config validation on startup and
/gomoku admin reload: missing or wrongly typed keys get defaults and a warning.
- Whole-room-world backup/reset:
/gomoku admin save stores the world under plugins/Gomoku/backups/<room>; after a match the world is restored, removing TNT, celebration blocks, fireworks and stones.
- Win celebration intervals:
win-celebration.interval-ticks and win-celebration.corner-fireworks.interval-ticks.
- Language-aware room piece names: Chinese “黑子/白子”, English “Black Stone/White Stone”.
lobby-protect: only admins in creative can break/interact in the lobby; rooms keep their original protection.
- Local SQLite storage (
storage.type: sqlite) with the driver bundled.
- English console output for
gomoku admin reload, avoiding Windows console mojibake.
- Chinese/English config templates
config.yml / config_en.yml and piece templates pieces.yml / pieces_en.yml.
Fixed
- Hotbar “Piece Shop / Room Menu” item names not following
locale; existing items are re-rendered on join and reload.
- Whole-world backup failing on
session.lock during admin save.
- World reset being skipped when players were still in the room; remaining players are now teleported to the lobby first.
- Legacy
hotbar.menu.name / pieces.yml menu.name overriding language text.
- Merged Chinese/English comment lines when switching config comment language.
Language
lang-version: 36; added gui-in-game; help text now lists /gomoku gui and /gomoku pieceshop.
Gomoku — 中文
Gomoku(五子棋)是一款面向 Paper 1.20.4 的 Minecraft 小游戏插件。玩家在各自房间的虚空世界中、在自定义搭建的棋盘上进行经典的五子连珠对弈。
当前版本:1.1.4
功能特性
- 每个房间拥有独立的虚空世界,棋盘异步分批生成 —— 不会造成主线程卡顿
- 羊毛边框预览系统(异步、区块安全)
- 五连获胜判定,每手统一计时(默认 60 秒,可配置)
- 轮到的玩家会看到绿色「该你了」标题,以及动作栏中的实时倒计时
- 超时则该局作废 —— 双方都不得分
- 对局中死亡会在配置的大厅处重生
- 玩家战绩:胜场 / 负场 / 平局 / 积分 / 胜率 / 等级
- 双语支持:中文(zh_cn)与英文(en),语言文件带版本号并可自动刷新
- 侧边栏计分板,大厅与对局使用不同布局,完全可配置且由占位符驱动
- 提供 PlaceholderAPI 扩展,可用于 TAB、计分板、全息影像等
- 兼容 Multiverse-Core,便于世界管理
- 红石物品用于取消匹配,支持观战模式
配置流程
所有房间相关命令都位于 /gomoku admin 之下。
/gomoku setlobby —— 设置主大厅。同时会把该位置同步为所在世界的原版重生点。执行其他任何命令前必须先完成此步。
/gomoku admin add <room> —— 创建一个虚空世界并将其注册为房间(会将你传送进去,并切换到创造模式)
/gomoku admin playerspawn —— 站在玩家应当出生的位置执行此命令(必须在房间世界内)
/gomoku admin dish <size> —— 在将要建造棋盘的位置显示羊毛边框预览(15–64,间隔 3)
/gomoku admin fill <line> <fill> <border> —— 在预览边框内生成棋盘。每次建造都会连同 XYZ 坐标和一个创建编号(1、2、3……)一起缓存,因此放错位置的棋盘可以用 /gomoku admin delete <no> 删除 —— 即使删除了前面的编号,其余编号也保持稳定。
/gomoku admin check <black> <white> —— 设置棋子名称,并从快捷栏第 1–2 格读取材质
/gomoku admin save <room> —— 对玩家开放该房间(必须在房间世界内)。保存会保留最后一次建造的棋盘,并丢弃其余缓存 —— 在此之前,坐标只存在于内存中。
自动识别手动搭建的棋盘(木斧)
/gomoku admin add 与 /gomoku admin build 会清空你的背包,并给你一把木斧(第 1 格)。任意木斧都可以 —— 包括从创造模式物品栏中拿出的;当你手持它时,会自动打上用法说明。
| 输入 |
效果 |
| 手持木斧 |
动作栏显示用法;禁止破坏方块和方块交互 |
| 左键点击某格中间的填充方块 |
识别整块棋盘并写入房间 |
| 右键 |
取消(同时取消进行中的 admin dish 预览) |
识别会从棋盘层向外逐层搜索,直到遇到空气,然后测量网格线之间的间距,并将其换算为房间的 size / interval / line / fill / center / boardY。扫描成功后,只需设置玩家出生点并保存即可。
这个最初版本的限制:棋盘必须是虚空中独立、正方形、单层的结构,每格为统一的 3×3 填充,且格子之间有网格线 —— 即格子宽度 ≥ 3(interval 为 3 或 5)。用 admin fill 且 interval 1(1 格宽的格子)生成的棋盘无法通过这种方式识别。
命令
管理员(gomoku.admin)
| 命令 |
说明 |
/gomoku setlobby |
将大厅出生点设置在你当前的位置(同时同步该世界的重生点) |
/gomoku admin add <room> |
新建一个带独立虚空世界的房间 |
/gomoku admin build <room> |
进入房间编辑模式(清空背包、发放木斧、传送进入、停用该房间),并打印就绪报告 |
/gomoku admin dish <size> |
羊毛边框预览(gap=3,异步且区块安全) |
/gomoku admin fill <line> <fill> <border> |
在预览边框内建造棋盘(异步分批) |
/gomoku admin check <black> <white> |
设置棋子名称 + 从快捷栏第 1–2 格读取材质 |
/gomoku admin delete [no|list] |
删除缓存的棋盘建造记录(默认删除最新的);list 列出全部记录 |
/gomoku admin playerspawn |
设置玩家出生点(必须在房间世界内) |
/gomoku admin save <room> |
对玩家开放该房间(必须在房间世界内),并把整个世界备份到 plugins/Gomoku/backups/<room> |
/gomoku admin clear <room> |
删除房间及其世界备份 |
/gomoku admin reload |
热重载语言、房间、大厅、战绩与配置(含注释语言) |
玩家(gomoku.use,默认 true)
| 命令 |
说明 |
/gomoku join <room> |
加入房间 |
/gomoku join auto |
自动匹配(优先级:等待中的房间 > 空闲房间) |
/gomoku spectate <room> |
观战当前正在对局的房间(若尚未开局则报错) |
/gomoku leave |
退出当前对局或停止观战 |
/gomoku stats [player] |
查看战绩 |
/gomoku gui |
打开房间列表界面(所有玩家可用) |
/gomoku pieceshop |
打开棋子商店界面(所有玩家可用) |
/gomoku help |
显示帮助(管理员部分仅对 gomoku.admin 可见)—— 输出与直接输入 /gomoku 相同 |
限制规则
| 规则 |
说明 |
| 必须先设大厅 |
除 setlobby 和 help 外,所有命令都要求先设置大厅 |
| 禁止在大厅建造 |
add 与 build 不能以大厅世界为目标 |
| 禁止在大厅编辑棋盘 |
dish / fill / check / delete 不能在大厅世界中使用 |
| 禁止在大厅设出生点 |
playerspawn 不能在大厅世界中使用 |
| 禁止删除大厅 |
clear 不能删除大厅世界 |
| 在房间内保存 |
save 必须在房间自己的世界中使用 |
| 先保存再新建 |
如果正站在一个未保存的房间世界中,需先 save 该房间,再 add 新房间 |
玩法
- 瞄准棋盘格子并左键点击即可落子。
- 双方玩家在出生点都会被设为创造模式,快捷栏装满各自棋子的方块。
- 每一手都有相同的思考时间(
turn-seconds,默认 60 秒)。轮到的玩家会看到绿色**「该你了」**标题,以及快捷栏上方动作栏中不断减少的倒计时。
- 时间耗尽则该局作废:双方都不计分(不算胜、不算负、也不算平局)。
- 前 5 手不进行胜负判定(这么早不可能出现五连)。
- 棋盘下满则为平局。积分为
胜场 × 3 + 平局。
- 观战者通过
/gomoku spectate <room> 加入 —— 只有真正处于对局中的房间才接受观战,否则会提示「未在对局中」。观战者会以旁观模式进入该房间。
- 一局结束时,房间内的所有人 —— 包括双方玩家、所有观战者,以及仍站在该房间世界中的其他人 —— 都会被传送回大厅。
- 快捷栏中的红石物品可取消匹配。
- 在房间世界或大厅世界中死亡,都会在配置的大厅处重生。
配置
plugins/Gomoku/config.yml:
locale: "zh_cn" # "zh_cn" 或 "en"
turn-seconds: 60 # 每一手的时间预算
lobby:
set: true # 由 /gomoku setlobby 自动写入
world: world
x: -36.5
y: 76.0
z: -23.5
yaw: 0.0
pitch: 0.0
大厅快捷栏物品可以分别开关:
hotbar:
menu:
enabled: true # false = 不显示房间菜单物品(已发放的也会移除)
slot: 0
shop:
enabled: true # false = 不显示棋子商店物品(已发放的也会移除)
slot: 7
turn-seconds 会在每一手开始时重新读取,因此修改后甚至不需要执行 /gomoku admin reload。
config.yml 的注释会随 locale 自动在中文/英文之间切换,配置值保持不变;启动和 /gomoku admin reload 时会检查缺失或类型错误的配置项并尝试补默认值。
计分板布局不在这里 —— 它们位于语言文件中(见下文)。
计分板
为每位玩家显示侧边栏,共三套布局:未在对局中时使用 lobby,对局进行中使用 game,观战时使用 spectator。这些布局位于语言文件(languages/zh_cn.yml、languages/en.yml)的 scoreboard: 段下,因此每种语言都可以带自己的文案,内容也会随 lang-version 刷新一起更新。
scoreboard.enabled —— 设为 false 将完全禁用侧边栏(玩家恢复使用原版计分板)
scoreboard.update-interval —— 刷新间隔(单位:tick),默认 20(1 秒)
scoreboard.<layout>.title —— 侧边栏标题(最多 32 个字符);<layout> 为 lobby、game 或 spectator
scoreboard.<layout>.lines —— 各行内容,自上而下;"" 渲染为空白行(每行最多 64 个字符)
缺失的键会回退到内置默认值,因此手工精简过的语言文件依然可用。仍在 config.yml 中保留旧 scoreboard: 段的服务器也能继续工作,但一旦语言文件定义了这些键,配置中的副本就会被忽略,并在启动时记录一条警告。
之所以需要观战布局,是因为观战者没有对手 —— 对他们而言 %gomoku_opponent% 会返回 —。可以改用 %gomoku_black_player% / %gomoku_white_player% 来列出双方。
每一行都会经过 %player% 以及所有 %gomoku_xxx% 占位符的替换。PlaceholderAPI 不是必需的 —— 插件自有的占位符由内部解析。如果确实安装了 PlaceholderAPI,其他插件(TAB、Vault……)的占位符也会一并解析。
修改布局后只需执行 /gomoku admin reload;它会重新读取配置并刷新所有在线玩家。
棋子商店
玩家可以花费积分购买黑/白棋子外观的成对组合。配置位于单独的 pieces.yml(首次启动时生成)。
menu:
slot: 7 # 快捷栏倒数第二格
material: CHEST
name: "&e&l棋子商店"
lore:
- "&7可用积分: &e{points}"
size: 27
title: "&8棋子商店 &7可用: &e{points}"
pieces:
concrete:
cost: 20 # 0 = 所有人已拥有
black:
material: BLACK_CONCRETE
name: "&0墨石"
white:
material: WHITE_CONCRETE
name: "&f白瓷"
- 一个箱子物品会放在配置的快捷栏格位(默认
7 = 倒数第二格),点击即可打开商店界面。该物品带有标签,无法移动或丢弃,并且玩家每次回到大厅时都会重新发放。
- 每个条目都是一对:
black 与 white 必须同时存在,且必须使用不同材质 —— 重复使用同一种方块的条目会被跳过,并在控制台输出警告。
- 购买需要消耗积分 =
胜场 × 3 + 平局 − 已花费。已花费积分按玩家单独记录,因此历史累计的 %gomoku_score% 永远不会减少;%gomoku_points% 显示当前仍可用的积分。
- 点击已拥有的条目即可免费装备;点击未解锁的条目会一次性完成购买并装备。
- 选定的组合只会在未固定自身棋子的房间中用于该玩家的棋子。
/gomoku admin check 会将房间标记为已固定,而固定过的房间始终优先于商店设置。在此功能之前配置过的房间,会通过其非默认的材质/名称被识别出来。
- 游戏在轮次提示、
%gomoku_turn_piece% 占位符以及玩家快捷栏物品中显示的,是所选组合的棋子名称。
- 玩家的选择保存在
pieces-data.json 中;/gomoku admin reload 会重新读取这两个文件。
语言文件
文件位于 plugins/Gomoku/languages/ —— 即 zh_cn.yml 与 en.yml。除所有聊天消息外,它们还包含侧边栏计分板布局。每个文件都有一个 lang-version:
- 启动时(以及执行
/gomoku admin reload 时),插件会将内置的 lang-version 与磁盘上的版本进行比较。
- 如果服务器上的副本较旧,会先备份到
languages/backup/<name>-v<old>-<timestamp>.yml,然后替换 —— 这样升级后的文案也能送达那些曾解压过旧版本的服务器。
- 若要保留本地修改,请把你文件中的
lang-version 提高到内置值之上。
权限
| 权限 |
默认 |
说明 |
gomoku.admin |
OP |
所有管理员命令 |
gomoku.use |
true |
玩家命令 |
PlaceholderAPI
玩家占位符
| 占位符 |
示例 |
说明 |
%gomoku_room% |
a / — |
当前房间名称 |
%gomoku_state% |
WAITING PLAYING ENDED |
对局状态 |
%gomoku_opponent% |
player1 / — |
对手名称(观战者为 —) |
%gomoku_color% |
黑子 白子 观战 / — |
你的身份(硬编码中文) |
%gomoku_black_player% |
player1 / — |
当前对局的黑方 |
%gomoku_white_player% |
player2 / — |
当前对局的白方 |
%gomoku_turn% |
player1 / — |
当前轮到的玩家 |
%gomoku_turn_piece% |
黑子 / 白子 / — |
当前落子方的棋子名称 |
%gomoku_timer% |
43 / — |
当前这一手剩余的秒数 |
%gomoku_countdown% |
黑子 player1 剩余43s |
单行摘要:棋子 + 玩家 + 秒数(格式在 papi-countdown 中配置) |
%gomoku_board_size% |
15 / — |
棋盘尺寸 |
%gomoku_move_count% |
12 / — |
已落子数 |
%gomoku_wins% |
5 |
总胜场 |
%gomoku_losses% |
2 |
总负场 |
%gomoku_draws% |
1 |
总平局 |
%gomoku_total_games% |
8 |
对局总数 |
%gomoku_winrate% |
62.5% |
胜率 |
%gomoku_score% |
16 |
积分(胜 +3,平 +1) |
%gomoku_points% |
6 |
棋子商店中仍可消费的积分 |
%gomoku_level% |
1 |
玩家等级 |
服务器占位符
| 占位符 |
示例 |
说明 |
%gomoku_room_count% |
3 |
房间总数 |
%gomoku_playing_room_count% |
2 |
当前正在对局的房间数 |
%gomoku_enabled_room_count% |
2 |
数值相同 —— playing_room_count 的旧别名 |
%gomoku_player_count% |
4 |
对局中的玩家数 |
从源码构建
需要 JDK 17(在 gradle.properties 中配置)。
./gradlew build # -> build/libs/Gomoku.jar
./gradlew proguard # -> build/libs/Gomoku-obf.jar(会先执行 build)
./gradlew clean build proguard
部署时把 jar 复制到服务器的 plugins/ 目录并重启即可。只能存在一个 Gomoku jar —— 否则插件名称会冲突。
依赖
- 必需: Paper 1.20.4+
- 可选: Multiverse-Core(世界管理)
- 可选: PlaceholderAPI(TAB / HUD / 计分板集成)
链接
许可证
本项目使用 MIT License,详见仓库根目录的 LICENSE。
1.1.3 — 功能总览
大厅
进服时强制清空背包和盔甲,然后只发两件物品(位置可在 config.yml 调):
hotbar:
menu: # 下界之星: 打开房间菜单
enabled: true
slot: 0
material: NETHER_STAR
name: "&b&l房间菜单"
lore:
- "&7左键 / 右键 打开房间列表"
shop: # 箱子: 棋子商店
enabled: true
slot: 7
- 左键或右键下界之星 → 54 格房间菜单
- 空闲房间 = 工作台,点击加入(开始匹配)
- 对局中房间 = 红石块,点击观战
- 底部中间铁砧 = 自动匹配
- 每个房间显示棋盘尺寸和当前人数
- 右键房间 = 直接和 AI 开局,弹出 9 格等级选择:
空 绿 空 黄 空 橙 空 红 空
AI 等级
| 颜色 |
等级 |
后端 |
| 绿 |
简单 |
内置 Java AI,40% 不堵你的成五、55% 随机落子 |
| 黄 |
普通 |
内置 AI,25% 从前 5 名候选随机 |
| 橙 |
困难 |
内置 AI,始终最优 |
| 红 |
地狱 |
RapFi 引擎(需 pbrain-rapfi-windows-*.exe,仅 15×15);未接入时显示灰色羊毛 |
内置 AI 只算已有棋子周围 2 格,按五连/活四/冲四/活三/眠三/活二评分,进攻权重高于防守。
RapFi 走标准 Gomocup 协议(START / BOARD…DONE / INFO timeout_turn / END),单步 3 秒上限、20 秒看门狗,失败自动回退内置 AI。
匹配
- 左键房间开始匹配,5 分钟未等到真人 → 自动转 AI 对局(只对左键生效)
- 匹配中或开局时匹配到真人,计时立刻作废
- 等待匹配时手上有一颗「退出对局」红石,手持右键取消匹配
对局中
- 第 8 格固定发放带
gomoku:exit_item 标签的红石:右键第一次提示确认,5 秒后再右键退出;5 秒内点击无效;超过 10 秒重新计时
- 手持该红石时不触发射线落子、不能放置方块
- 落子方式:瞄准格子左键(520 格射线,命中点需在格子内 0.3 格以上)
- 最近一步棋子四周用红色羊毛高亮(同格子内,不会越界)
- 胜负只告诉本人:赢家看到绿色「你赢了」,输家看到红色「你输了」,观战者看中立总结
- 对局结束 / 停服时棋子层整片清成空气,棋盘本体保留
音效
sounds:
start:
sound: BLOCK_WOODEN_DOOR_OPEN
volume: 1.0
pitch: 1.0
place:
sound: BLOCK_STONE_PLACE
volume: 1.0
pitch: 0.8 # 0.5 更沉更慢, 2.0 更尖更快; volume 0 = 静音
建棋盘流程(严格顺序)
/gomoku admin add <房间> 建虚空世界并进入编辑模式
/gomoku admin dish 15 生成预览(位置就是最终棋盘位置)
/gomoku admin fill 线 填充 外围 按预览位置铺板,第三个参数是边界,边界及之外不能落子
/gomoku admin playerspawn 站在棋盘外侧设置出生点
/gomoku admin save <房间> 保存并启用(必须带房间名)
fill 必须在有预览时执行,否则提示先 dish
- 每次
fill 会先清掉这个世界里上一次的棋盘,避免出现多块板
- 开局时插件会从世界重新扫描井字格校准尺寸/中心/高度(日志:
Board calibrated for 'x': 15x15 int=3 center=0,6 y=6),所以配置里的坐标不会影响落子准确性
木斧识别(编辑模式)
admin add / admin build 会清空背包并在第 1 格给一把木斧:
- 左键点井字线 → 自动扫描整块棋盘(外接框、线间距、网格数),缺失的线自动补齐,结果直接写入房间
- 右键取消(同时取消
dish 预览)
- 手持时不破坏方块、不触发方块交互;任意木斧(含创造模式取的)都会被自动打上用法
- 扫描只读已加载区块(不会卡服),半径 240 格,单块棋盘最多 15 万方块
命令
| 命令 |
说明 |
/gomoku help |
帮助 |
/gomoku setlobby |
设置大厅 |
/gomoku join <房间|auto> |
加入房间 / 自动匹配 |
/gomoku spectate <房间> |
观战(房间未开始会提示) |
/gomoku leave |
退出对局 / 取消匹配 |
/gomoku stats [玩家] |
战绩查询 |
/gomoku gui |
打开房间列表界面(所有玩家可用) |
/gomoku pieceshop |
打开棋子商店界面(所有玩家可用) |
/gomoku admin add <房间> |
新建房间世界并进入编辑模式 |
/gomoku admin build <房间> |
进入已有房间的编辑模式 |
/gomoku admin dish <大小> |
生成棋盘预览 |
/gomoku admin fill <线> <填充> <外围> |
按预览位置生成棋盘 |
/gomoku admin check <黑子名> <白子名> |
设置本房间棋子外观 |
/gomoku admin delete [编号|list] |
删除缓存的棋盘坐标 |
/gomoku admin playerspawn |
设置房间出生点 |
/gomoku admin save <房间> |
保存并启用房间 |
/gomoku admin clear <房间> |
删除房间 |
/gomoku admin reload |
重载语言/棋子/配置 |
/gomoku admin debug |
打印当前状态(locale、文案、房间参数、会话、脚下格子) |
权限
| 权限 |
默认 |
说明 |
gomoku.play |
所有玩家 |
使用玩家命令 |
gomoku.admin |
OP |
管理员命令、木斧识别 |
占位符(PlaceholderAPI 可选)
%gomoku_wins% %gomoku_losses% %gomoku_draws% %gomoku_score% %gomoku_points%
%gomoku_room% %gomoku_state% %gomoku_turn% %gomoku_opponent% %gomoku_black_player% %gomoku_white_player%
%gomoku_black_score% %gomoku_white_score% %gomoku_timer% %gomoku_countdown% %gomoku_turn_piece%
%gomoku_spectator% %gomoku_spectator_count% %gomoku_room_count% %gomoku_playing_room_count%
计分板布局写在语言文件里(scoreboard: 段),支持大厅 / 对局 / 观战三套。
1.1.4 更新日志
新增
- 新增
/gomoku gui 与 /gomoku pieceshop,所有玩家可打开房间列表和棋子商店界面。
- 大厅快捷栏物品可独立开关显示:
hotbar.menu.enabled、hotbar.shop.enabled;关闭时已发放的物品也会被移除。
config.yml / pieces.yml 的注释随 locale 自动切换中英文,配置值保持不变;切换前备份为 config.yml.bak / pieces.yml.bak。
- 启动和
/gomoku admin reload 时自动检查配置:缺失或类型错误的键会补默认值并提示。
- 房间世界整世界备份与重置:
/gomoku admin save 备份到 plugins/Gomoku/backups/<room>,对局结束后自动恢复,清除 TNT、庆祝方块、烟花与棋子。
- 赢家庆祝生成间隔:
win-celebration.interval-ticks 与 win-celebration.corner-fireworks.interval-ticks。
- 房间棋子默认名随语言:中文“黑子/白子”,英文“Black Stone/White Stone”。
- 大厅保护
lobby-protect:仅管理员+创造模式可破坏/交互;房间沿用原保护逻辑。
- SQLite 本地存储(
storage.type: sqlite),驱动已内置,无需额外下载。
- 控制台支持英文
gomoku admin reload,避免中文乱码。
- 中文/英文配置模板:
config.yml / config_en.yml;棋子模板:pieces.yml / pieces_en.yml。
修复
- 快捷栏“棋子商店 / 房间菜单”物品名不随
locale 更新的问题;进服和 reload 会原地重绘已有物品。
admin save 因 session.lock 导致整世界备份失败。
- 重置世界时房间内仍有玩家会跳过;现在先把剩余玩家传回大厅再重置。
- 旧配置
hotbar.menu.name / pieces.yml menu.name 覆盖语言文本的问题。
- 配置注释切换时中英文注释行被错误合并的问题。
语言
lang-version: 36,新增 gui-in-game,帮助文本加入 /gomoku gui、/gomoku pieceshop。
评论 0
登录后参与评分
还没有评论,来抢沙发吧