更新记录
1.0.0(2026-11-22)
- 新增松月棋室和 Cocos 十五路棋盘,支持人机陪练、同屏双人和本地续局。
- 新增自由五子棋 UTS 接口,提供落子、四向判胜、满盘和棋、提示、悔棋、读谱与会话释放。
- 新增 uni-app x 完整棋室、传统 uni-app 选项式示例和宿主联机服务适配器。
平台兼容性
uni-app(5.34)
| Vue2 | Vue3 | Chrome | Safari | app-vue | app-nvue | Android | iOS | 鸿蒙 |
|---|---|---|---|---|---|---|---|---|
| × | √ | √ | - | - | × | √ | √ | √ |
| 微信小程序 | 支付宝小程序 | 抖音小程序 | 百度小程序 | 快手小程序 | 京东小程序 | 鸿蒙元服务 | QQ小程序 | 飞书小程序 | 小红书小程序 | 快应用-华为 | 快应用-联盟 |
|---|---|---|---|---|---|---|---|---|---|---|---|
| - | - | - | - | - | - | - | - | - | - | - | - |
uni-app x(5.34)
| Chrome | Safari | Android | iOS | 鸿蒙 | 微信小程序 |
|---|---|---|---|---|---|
| √ | - | √ | √ | √ | × |
其他
| 多语言 | 暗黑模式 | 宽屏模式 | 蒸汽模式 |
|---|---|---|---|
| × | × | √ | √ |
松月棋室 · Cocos 五子棋|人机对弈、同屏双人、好友约局
介绍
国风十五路五子棋 UTS 插件,内置 Cocos 立体棋盘,支持离线人机、同屏双人、提示、悔棋与续局。接入自有服务后,可匹配棋友或通过聊天邀请卡约局。
松月棋室提供两种接入方式。要把整款游戏放进应用,使用 uni-app x 的 Cocos 棋室页面。要在已有棋盘上判胜、悔棋或续局,从插件根入口调用本地规则 API。两种方式都可以离线开始第一局。
功能特色
| 功能 | 玩家可以做什么 | 接入条件 |
|---|---|---|
| 十五路自由棋 | 黑先,在空交点轮流落子;横、竖或斜向五子及以上获胜,满盘无连五时和棋 | 本地 UTS 同步判断 |
| 人机对弈、同席双人 | 一人执黑与电脑对弈,或两人共用一台设备轮流行棋 | 打开任一分发示例即可体验 |
| Cocos 棋室 | 从竹庭大厅进入,查看落子动效、最后一手、胜线及终局棋谱,结算后可再开一局 | uni-app x 完整页面,棋盘需要 WebGL |
| 棋形手卷、提示与悔棋 | 手卷演示四个连线方向;提示只标出建议交点;同席可退一手,人机可退回自己的回合 | 手卷在完整棋室;自建规则会话可用 allowUndo 决定是否允许悔棋 |
| 续局与保存 | 完整棋室自动保存未完本地局;传统示例可手动保存、离桌,再打开棋谱 | 本机存储;恢复时校验每一手 |
| 云端人机、匹配、好友或群邀请 | 接受邀请、同步对局、申请悔棋或求和、查看实际结算 | 需要宿主提供已鉴权的 HTTP 和已绑定用户的聊天连接 |
| 换图与自绘 | 可替换大厅主景、整组道具图标,也可只用规则 API 绘制自己的棋桌 | 内置棋台可直接使用,自有图像按需配置 |
适合哪些场景
| 你的需求 | 从哪里开始 | 第一项验收 |
|---|---|---|
| 给 uni-app x 应用增加一个可玩的小游戏 | 基础示例,注册完整棋室页 | 点「同席双人」,黑白可各下一子 |
| 在传统 uni-app 中做本地棋桌 | 导入表中的 .vue 示例,使用选项式 API |
点击「人机对弈」,在空交点落子后看到白棋应手 |
| 已有棋盘和交互,只想接入裁判 | 高级示例,建局后保存会话编号 | H8 落子后 board[112] 为 1,轮到白棋 |
| 希望退出应用后能接着下 | 进阶示例,保存着序并恢复为新会话 | 黑 H8、白 I8 的棋谱恢复后,撤回一手只剩 H8 |
| 已有用户、好友、聊天和对局服务 | 模块示例,先配置传输,再打开棋室或邀请页 | 两个测试账号接受邀请后看到同一盘面和各自执色 |
下载与导入
| 宿主 | 示例代码位置 |
|---|---|
| uni-app x,Vue 3,Vapor / TypeScript,完整 Cocos 棋室 | uni_modules/lizhao-gomoku/example/uniappx/index.uvue |
| 传统 uni-app,选项式 API,本地规则接入棋桌 | uni_modules/lizhao-gomoku/example/uniapp/index.vue |
从基础到进阶
基础功能配置示例
第一次接入建议先走本地双人局。 在 HBuilderX 导入完整的 uni_modules/lizhao-gomoku/。将下列对象追加到现有 pages.json 的 pages 数组,保留项目原有首页。以下是可直接粘贴的 JSON,字段说明见表。
{
"path": "uni_modules/lizhao-gomoku/example/uniappx/index",
"style": {
"navigationBarTitleText": "松月棋室",
"navigationStyle": "custom",
"swipeBackAsBackPress": true,
"pageOrientation": "portrait",
"hideStatusBar": true,
"hideBottomNavigationIndicator": true,
"disableScroll": true
}
}
// 在业务首页按钮的点击事件中打开棋室。
uni.navigateTo({
url: '/uni_modules/lizhao-gomoku/example/uniappx/index',
fail: error => uni.showModal({ title: '棋室打开失败', content: error.errMsg, showCancel: false })
})
| 参数 | 类型 | 必填 | 说明 | 默认值 | 可选参数 |
|---|---|---|---|---|---|
path |
string | 是 | 本项目直接注册插件演示页,注册时无前导斜杠、无扩展名 | 无 | 使用复制页时填自己的已注册路由 |
style.navigationBarTitleText |
string | 否 | 页面标题 | 继承宿主 | 示例为松月棋室 |
style.navigationStyle |
string | 建议 | 棋室自己绘制返回和设置入口 | 继承宿主 | 示例为 custom |
style.swipeBackAsBackPress |
boolean | 建议 | 在支持的平台将侧滑交给页面返回处理 | 继承宿主 | true / false |
style.pageOrientation |
string | 建议 | 本页首选竖屏 | 继承宿主 | 示例为 portrait |
style.hideStatusBar |
boolean | 否 | 为棋室隐藏系统状态栏 | 继承宿主 | true / false |
style.hideBottomNavigationIndicator |
boolean | 否 | 在支持的设备上隐藏底部指示条 | 继承宿主 | true / false |
style.disableScroll |
boolean | 建议 | 固定全屏棋面,避免页面跟随落子手势滚动 | 继承宿主 | true / false |
若已有注册页,也可以只复制上述 .uvue 的内容到该页,保留插件完整目录,并在自己的路由上应用同样的页面设置。进入「同席双人」后,黑白双方分别选择空交点落子。
传统 uni-app 请选择表中 .vue 文件,将其复制到已注册的 Vue 页面,或注册 uni_modules/lizhao-gomoku/example/uniapp/index 后从首页跳转。这个示例展示规则棋桌和手动存谱。
高级示例
给自己的棋盘接上裁判。 把下段放在业务页的按钮处理函数或独立模块中。示例关闭悔棋,演示黑棋下在天元、电脑为白棋选点。同步方法在调用线程返回;长期对局应在开局时保留编号,离页时再释放。
import { createGomokuGameSync, placeGomokuStoneSync, suggestGomokuMoveSync,
disposeGomokuGameSync } from '@/uni_modules/lizhao-gomoku'
const opened = createGomokuGameSync({ allowUndo: false })
if (!opened.ok || opened.snapshot == null) throw new Error(opened.errMsg)
const id = opened.snapshot.sessionId
try {
// H8 是中央交点:第 7 行 × 15 加第 7 列,行列从 0 起算。
const black = placeGomokuStoneSync(id, 112)
if (!black.ok) throw new Error(black.errSubject + ' ' + black.errCode + ' ' + black.errMsg)
const white = suggestGomokuMoveSync(id)
if (!white.ok) throw new Error(white.errMsg)
// 建议操作只读,确认落子后再提交给裁判。
const after = placeGomokuStoneSync(id, white.point)
if (!after.ok) throw new Error(after.errMsg)
console.log(after.snapshot?.board, after.snapshot?.lastPoint)
} finally {
const closed = disposeGomokuGameSync(id)
if (!closed.ok) console.error(closed.errCode, closed.errMsg)
}
进阶示例
保存着序,恢复棋局。 示例将黑 H8、白 I8 两手写入独立存档,再从 moves 恢复并撤回白棋。每次恢复都会得到新的 sessionId。返回的快照包含独立数组,释放规则会话后仍可显示或归档。
import { restoreGomokuGameSync, getGomokuSnapshotSync, undoGomokuMoveSync,
disposeGomokuGameSync } from '@/uni_modules/lizhao-gomoku'
export function openRecord(moves: number[], undo: boolean) {
// 棋谱不能含重复交点或终局后的着法。校验失败时保留原存档。
const result = restoreGomokuGameSync({ allowUndo: true }, moves)
if (!result.ok || result.snapshot == null) throw new Error(result.errCode + ' ' + result.errMsg)
const id = result.snapshot.sessionId
try {
const read = getGomokuSnapshotSync(id)
if (!read.ok || read.snapshot == null) throw new Error(read.errMsg)
if (!undo || !read.snapshot.canUndo) return read.snapshot
// count 可以是 1 或 2;演示只撤最后一手。
const changed = undoGomokuMoveSync(id, 1)
if (!changed.ok || changed.snapshot == null) throw new Error(changed.errMsg)
return changed.snapshot
} finally {
const closed = disposeGomokuGameSync(id)
if (!closed.ok) console.error(closed.errCode, closed.errMsg)
}
}
// 独立演示键,生产中请在实际落子后保存 snapshot.moves。
const key = 'my-gomoku.readme.record.v1'
try {
uni.setStorageSync(key, JSON.stringify([112, 113]))
const stored = uni.getStorageSync(key)
if (typeof stored !== 'string') throw new Error('没有可读取的棋谱')
const moves = JSON.parse(stored)
if (!Array.isArray(moves)) throw new Error('棋谱应为交点数组')
const record = openRecord(moves, true)
console.log(record.moves, record.turn) // [112],2 表示轮到白棋
} catch (error) {
uni.showModal({ title: '棋谱读写失败', content: String(error), showCancel: false })
}
完整示例
可复制的完整页面(uni-app x、Vue 3、Vapor、TypeScript)。 将整段放到一个已注册的 .uvue 页面并使用基础示例的页面样式。这个页面管理前后台、邀请参数、系统返回键及退出。完整分发主源为 uni_modules/lizhao-gomoku/example/uniappx/index.uvue。
<template>
<view class="page">
<Gomoku :key="generation" :active="active" :invite-token="inviteToken"
:back-request="backRequest" @exit="exitGame" />
</view>
</template>
<script setup lang="ts">
import { nextTick, ref } from 'vue'
import { onLoad, onShow, onHide, onBackPress } from '@dcloudio/uni-app'
// #ifdef WEB
import { onBeforeRouteLeave } from 'vue-router'
// #endif
import Gomoku from '@/uni_modules/lizhao-gomoku/components/lizhao-gomoku/lizhao-gomoku.uvue'
const active = ref(true)
const inviteToken = ref('')
const backRequest = ref(0)
const generation = ref(0)
let leaving = false
// 普通进房传空串。打开邀请时,令牌来自消息卡,身份和有效性由服务端检查。
onLoad(options => {
if (typeof options?.invite_token === 'string') inviteToken.value = options.invite_token
})
onShow(() => nextTick(() => { leaving = false; active.value = true }))
onHide(() => { active.value = false })
function requestBack() {
if (leaving) return false
backRequest.value++ // 由棋室先关闭顶层卷轴,或询问是否离桌。
return true
}
onBackPress(requestBack)
// #ifdef WEB
onBeforeRouteLeave(() => !requestBack())
// #endif
function exitGame() {
// 手机从外部卡片直接进入时可能没有上一页;重新挂载棋室作为退出落点。
if (getCurrentPages().length < 2) { generation.value++; return }
if (leaving) return
leaving = true
uni.navigateBack({ delta: 1, fail: () => { leaving = false; generation.value++ } })
}
</script>
<style>
.page { width: 100%; height: 100%; flex: 1; background-color: #162e25; }
/* #ifdef WEB */
.page { height: 100vh; }
/* #endif */
</style>
| 参数 | 类型 | 必填 | 说明 | 默认值 | 可选参数 |
|---|---|---|---|---|---|
active |
boolean | 否 | 绑定页面显示状态;隐藏时停用输入并暂停未完本地局,返回后由玩家继续 | true | true / false |
inviteToken(模板 invite-token) |
string | 否 | 创建组件时读取;来自 URL 查询参数 invite_token。打开另一张卡时应以新组件接收 |
空字符串 | 服务端签发的邀请凭据 |
backRequest(模板 back-request) |
number | 否 | 每次系统返回时递增,让最上层棋室先处理 | 0 | 单调递增整数 |
@exit |
无参数事件 | 否 | 在大厅离席时由组件通知页面,宿主负责导航 | 无监听 | 自定义退出处理函数 |
模块示例代码
已有完整棋室的项目可以按需接入下面两个模块。外观模块独立于联网模块,本地玩法可以使用默认配置。
模块一 · 替换大厅主景和道具图集
第一次接入可跳过本节。有自有图片时,先将两张 WebP 放在宿主的 static/chess-room/,按示例命名;如果只替换主景,只需准备第一张并省略第二个参数。把配置放到宿主启动或首次打开棋室之前。
import { configureGomokuArtwork } from '@/uni_modules/lizhao-gomoku/static/host/art.js'
import cover from '@/static/chess-room/cover.webp?url' // 自备的透视棋桌主景
import props from '@/static/chess-room/props.webp?url' // 自备的透明六格道具图集
// #ifdef WEB
// 子页面在不同目录下运行,传入宿主构建得到的绝对 URL。
configureGomokuArtwork(new URL(cover, location.href).href, new URL(props, location.href).href)
// #endif
// #ifdef APP
function readWebp(path: string) {
return () => new Promise<string>((resolve, reject) => {
uni.getFileSystemManager().readFile({
filePath: path, encoding: 'base64',
success: r => typeof r.data === 'string'
? resolve('data:image/webp;base64,' + r.data)
: reject(new Error('图片读取结果不是文本')),
fail: reject
})
})
}
// App 本地 WebView 通过宿主取得图片内容,首次打开才读文件。
configureGomokuArtwork(readWebp(cover), readWebp(props))
// #endif
// 恢复内置外观时,在下一次打开棋室前调用 configureGomokuArtwork('')。
| 参数 | 类型 | 必填 | 说明 | 默认值 | 可选参数 |
|---|---|---|---|---|---|
source |
string 或读取函数 | 配置主景时是 | 主景图地址,或无参函数返回图片地址;建议横向 3∶2,主体居中 | 未配置时显示内置棋台 | 绝对 URL、数据地址、返回上述字符串的 Promise、空字符串 |
propSheet |
同 source |
否 | 透明图集按 3 列 × 2 行等分。第一行棋盘、手卷、棋罐,第二行亭阁、折扇、棋谱 | 内置道具图标 | 与主景相同,可单独传入,例如 configureGomokuArtwork('', propsUrl) |
读取函数成功后按本次配置缓存,拒绝或超过 4 秒时回退;再次打开可以重试。直接给 URL 时由棋室加载图片。若宿主需要检查配置读取结果,可在同一模块调用 await getGomokuArtwork() 取得主景字符串,或 await getGomokuRoomArt() 取得 { art, propsArt }。空字符串表示使用内置外观。玩家在大厅「落子动效」或设置内切换动效,偏好保存在本机;Web 会跟随系统减少动态效果设置。
模块二 · 接入自有对局服务和邀请卡
在进入页面前安装宿主适配器。棋室通过 HTTP 使用 /api/v3/game/,匹配和对弈通过同一用户已绑定的聊天连接传输。登录令牌留在宿主。完整签名见 uni_modules/lizhao-gomoku/static/host/service.d.ts。下面的 business 表示应用现有的 HTTP、登录和聊天模块。
import {
configureGomokuService, createGomokuClient, parseGomokuInviteCard
} from '@/uni_modules/lizhao-gomoku/static/host/service.js'
// 在登录、聊天绑定完成后调用。business 是宿主传入的对象。
// apiOrigin 是自有业务域名;session、chat 分别连接现有登录和聊天模块。
export function installChessService(business) {
const transport = {
request(method, path, params) {
return new Promise((resolve, reject) => uni.request({
url: business.apiOrigin + path, method, data: params, timeout: 10000,
// 此例使用 Bearer。若项目使用 Cookie 或其他请求头,沿用该项目的鉴权方式。
header: { Authorization: 'Bearer ' + business.session.accessToken() },
success(res) {
if (res.statusCode >= 200 && res.statusCode < 300) resolve(res.data)
else reject(new Error('五子棋服务 HTTP ' + res.statusCode))
},
fail: reject
}))
},
isBound: () => business.chat.isBoundToCurrentUser(),
send: packet => business.chat.send(packet), // 发送失败要抛错或返回被拒绝的 Promise
// 只转交当前账号的消息对象,返回取消这个监听的函数。
subscribe: fn => business.chat.subscribe(fn)
}
configureGomokuService(transport)
return createGomokuClient(transport) // 可供业务页查询战绩;完整棋室会自行使用已安装的传输
}
// 在 IM 卡片点击时调用。registeredPage 是本宿主注册的五子棋示例页绝对路径。
export function openChessInvite(message, registeredPage) {
const card = parseGomokuInviteCard(message)
if (card) uni.navigateTo({ url: registeredPage + '?invite_token=' + encodeURIComponent(card.token) })
}
| 参数 | 类型 | 必填 | 说明 | 默认值 | 可选参数 |
|---|---|---|---|---|---|
transport |
GomokuTransport 或 null | 是 | 在创建棋室前配置;换号前关闭棋室并清除引用 | null,本地棋仍可用 | 传输对象 / null |
request(method, path, params) |
函数,返回 Promise | 是 | 接收请求方式、含前缀的路径与键值参数;成功解析服务器原始 {code,msg,data};网络错误拒绝 Promise |
无 | GET / POST;参数值为字符串、数字或布尔值 |
send(packet) |
函数 | 是 | 发到当前用户的聊天连接;对象含 type 和业务字段 |
无 | 返回 void 或 Promise |
subscribe(listener) |
函数 | 是 | 将已解码的消息对象交给监听器;返回取消此监听的函数 | 无 | 返回 () => void |
isBound() |
函数,返回 boolean | 是 | 同时检查连接和当前用户绑定状态 | 无 | true / false |
message |
消息对象 | 解析邀请卡时是 | msg_type 为 20,remark 为 JSON 字符串,含 type: 'gomoku_invite'、invite_token、from_uid、group_id、bet_amount |
无 | 合法返回 {token,fromUid,groupId,bet},其他消息返回 null |
import { getGomokuService, createGomokuClient } from '@/uni_modules/lizhao-gomoku/static/host/service.js'
// 在个人战绩页调用。完整棋室会自动处理对局订阅。
export async function readMyChessHistory() {
const transport = getGomokuService()
if (!transport) throw new Error('请先配置棋会服务')
const client = createGomokuClient(transport)
// page 从 1 起;mode=0 表示全部;include_ongoing=1 包含未完局。
const history = await client.records({ mode: 0, page: 1, limit: 20, include_ongoing: 1 })
const ranking = await client.ranking({ scope: 'match', page: 1, limit: 20 })
return { history, ranking } // 均为服务端 data;业务页捕获错误后显示重试。
}
// 仅在宿主自绘联机棋盘时订阅。关闭这个页面时调用返回的函数。
export function watchNetworkMoves(client, gameId, onMove) {
return client.subscribe(packet => {
if (packet.type === 'game_move' && packet.game_id === gameId) onMove(packet)
})
}
// 先关闭棋室、移除本页订阅;账号退出时调用 configureGomokuService(null)。
| 入口 | 对接方式 | 画面与回执 |
|---|---|---|
| 本机雅弈、同席双人 | 直接调用本地 UTS | 离线可玩,支持提示、悔棋与本机续局 |
| 云端人机 | pve/start、move、state、undo、resign |
难度 1~3。一次落子可包含双方行动;缺少完整盘面时补读权威状态 |
| 全服匹配 | GET rooms → game_match_join {room_id} → game_start |
以服务端场次、可进入标记、门槛与原因展示,支持撤销等待 |
| 好友或群邀请 | invite/create 仅发送 to_uid、group_id 之一,并带选中场的 bet_amount |
IM 卡片类型 20。打开卡片查询详情,可接受私聊或群邀请;私聊可拒绝,发起方可撤销 |
| 在线对局 | 广播 game_move、game_state、game_end,恢复时读取 state |
按 board[y*15+x] 映射;等待确认的同一手重试沿用 uuid。服务端决定轮次、每手时间、离线判负和终态 |
| 悔棋、求和 | game_undo_req/ack、game_draw_req/ack |
显示当前查看者剩余额度,对方处理后以快照更新 |
| 金币结算 | bet_amount、settled、双方各自的 game_settle |
免费局和和棋可无结算推送。实际输赢取 actual_win/actual_lose,宿主在回执后重新获取钱包余额 |
| 业务历史与榜单 | await client.records({page:1,limit:20,include_ongoing:1});await client.ranking({scope:'match',page:1,limit:20}) |
两方法供宿主业务页面调用,返回服务端分页对象。平台排行只统计已结束的玩家对局 |
宿主维护聊天心跳、断开重连、bind_user 与 bind_success;重绑后向棋室转交服务端推送的 game_state。切换账号前先退出已打开的棋室,解除该页面订阅,然后调用 configureGomokuService(null)。同一传输可继续用于应用里的其他聊天功能。生产联调需要实际业务域名、两个测试账号及各自的聊天连接。
API 用途速查
公开规则声明在 uni_modules/lizhao-gomoku/utssdk/interface.uts,业务页面统一从 @/uni_modules/lizhao-gomoku 导入。会话只在当前运行期有效,保存和跨启动恢复以棋谱为准。
| 方法 | 返回值 | 用途 |
|---|---|---|
createGomokuGameSync(options) |
GomokuSnapshotReply |
黑先建局,配置仅在建局时读取 |
restoreGomokuGameSync(options, moves) |
GomokuSnapshotReply |
逐手校验,全部合法后才创建新会话,可恢复胜局、和局 |
getGomokuSnapshotSync(sessionId) |
GomokuSnapshotReply |
读取独立快照 |
placeGomokuStoneSync(sessionId, point) |
GomokuSnapshotReply |
当前执方落一子,完成判胜和换手 |
undoGomokuMoveSync(sessionId, count) |
GomokuSnapshotReply |
进行中撤回指定手数,不足则保持原局面 |
suggestGomokuMoveSync(sessionId) |
GomokuSuggestion |
只读建议,成功取 point,失败为 -1 |
disposeGomokuGameSync(sessionId) |
GomokuResult |
释放局面;已分配的编号重复释放成功,后续读取会明确失败 |
| 参数 | 类型 | 必填 | 说明 | 默认值 | 可选参数 |
|---|---|---|---|---|---|
options.allowUndo |
boolean | 是 | 建局或读谱时复制的悔棋开关 | 调用者填写,示例为 true | true / false |
moves |
number[] | 是 | 按黑白交替记录交点,最多 225 手 | 无 | 空数组或合法棋谱 |
sessionId |
number | 是 | 建局回执提供的本进程编号 | 无 | 已分配的正整数 |
point |
number | 是 | 从左上角按行编号,公式为行 × 15 + 列 | 无 | 0 至 224 的整数 |
count |
number | 是 | 整次撤回的手数 | 无 | 1 或 2 |
| 快照字段 | 含义 |
|---|---|
board、moves |
行优先的 225 个交点及历史着序;棋色 0 空、1 黑、2 白 |
phase、turn |
playing、won、draw。进行中 turn 为下一手棋色,终局则为最后落子的棋色 |
winner、winningLine |
胜方棋色或 0;获胜方向全部连续交点。双向同时成线时先取横,其次竖、右下、左下 |
lastPoint、canUndo |
空局为 -1;允许悔棋、以前有着且未终局时 canUndo 为 true |
sessionId |
所属会话的编号 |
GomokuResult 含 ok(是否成功)、errSubject(错误来源)、errCode(数值错误码)、errMsg(中文说明)。GomokuSnapshotReply 另带 snapshot,GomokuSuggestion 另带 point。释放会话只返回公共四项。
联机客户端速查
从 @/uni_modules/lizhao-gomoku/static/host/service.js 导入 createGomokuClient。以下 client 为上文安装函数返回的对象。完整棋室会处理这些调用;自绘联网页面应在对方回应或服务端广播后更新画面。下表每行是一个独立操作。
| 模块 | 调用示例 | 参数与结果 |
|---|---|---|
| 房间与匹配 | await client.rooms()、await client.join(roomId)、await client.cancelMatch() |
roomId 取可进入房间的 room_id。等 game_start 再开局,发送成功只代表消息已发出 |
| 云端人机 | await client.start(2) |
level 为 1 入门、2 进阶、3 挑战;返回服务端局面 |
| 查询、重连 | await client.state(gameId, true) |
true 查询云端人机,false 或省略查询玩家对局;用服务器的 game_id |
| 提交落子 | await client.move(gameId, 112, uuid, false) |
point 为 0~224;uuid 为本次行动的非空唯一标识;同一手超时重试沿用原值;末参 true 走人机 HTTP,false 走玩家消息 |
| 悔棋与认输 | await client.undo(gameId, true)、await client.resign(gameId, false) |
末参同上。人机看 HTTP 回执,玩家悔棋要等对方回应 |
| 求和与答复 | await client.draw(gameId)、await client.answer(gameId, 'undo', false) |
玩家对局使用;kind 为 undo 或 draw,accept 为 true 同意、false 拒绝 |
| 私聊或群邀请 | await client.invite('group_id', groupId, bet) |
target 为 to_uid 或 group_id,二选一;id 为正整数;bet 取场次的非负整数底池,免费局为 0 |
| 邀请卡详情与动作 | await client.info(token)、await client.accept(token)、await client.reject(token)、await client.cancel(token) |
token 来自服务端。接收方接受、私聊接收方可拒绝、发起方可撤销,均以回执为准 |
| 记录和排行 | await client.records({mode: 0, page: 1, limit: 20, include_ongoing: 1})、await client.ranking({scope: 'all', page: 1, limit: 20}) |
可省略参数。记录 mode 为 0 全部、1 人机、2 匹配、3 邀请;页码默认 1,条数默认 20(记录最多 50,榜单最多 100);include_ongoing 默认 1;scope 默认 all,另有 match、invite、bet、free |
| 绑定与监听 | client.bound()、const off = client.subscribe(listener) |
bound 返回当前绑定状态;收到的数据至少有 type;组件离开时调用 off(),宿主仍持有聊天连接 |
读取完整服务端局面时,可调用 parseGomokuSnapshot。此函数要求完整的 225 位棋盘字符串;遇到不完整的广播或局面矛盾,请重新查询。以下函数适合自绘联机棋桌。
import { parseGomokuSnapshot } from '@/uni_modules/lizhao-gomoku/static/host/service.js'
export async function readOnlineBoard(client, gameId, isPve) {
// isPve 为 true 时读云端人机,false 时读匹配或邀请局。
const raw = await client.state(gameId, isPve)
const game = parseGomokuSnapshot(raw) // 缺字段或计数不一致时会抛出错误。
return game // 页面据 game.board 渲染,用 game.color 确认自己执黑或执白。
}
| 在线快照字段 | 类型与读法 |
|---|---|
id、mode、status |
数字。id 是服务端对局编号;mode 为 1 人机、2 匹配、3 邀请;status 为 1 进行中、2 黑胜、3 白胜、4 和棋、5 认输、6 超时或断线、7 中断 |
board、last、count、maxSeq |
board 是 225 个数值,索引与本地相同。last 为末手交点,无可靠末手时为 -1;count 为盘中总子数;maxSeq 为服务端最大着序,缺省为 null |
color、turn、winner |
1 黑、2 白。color 是自己执色;turn 为服务端当前执方,终态可能为 0;无胜方时 winner 为 0 |
reason、win |
reason 为终局原因字符串,缺省为空;服务端判定五连时 win 给出连线交点,其他情况为空数组 |
undo、draw |
当前查看者的剩余悔棋、求和次数,缺省为 0 |
bet、settled |
底池金额或 null、是否已结算。实际输赢取各自收到的结算回执 |
seconds、offline、offlineSeconds |
当前回合与离线的剩余时间均以秒计,缺省为 null;offline 是离线用户编号,无则为 0 |
错误码说明
回复统一携带 ok、errSubject、errCode、errMsg。规则错误来源为 lizhao-gomoku,失败时 snapshot 为 null;只有读谱全部通过才分配编号。
| 错误码 | 含义 | 处理 |
|---|---|---|
| 0 | 成功 | 读取该方法的结果 |
| 9320001 | 配置、坐标、棋谱长度或撤回手数非法 | 检查类型、整型范围和长度 |
| 9320002 | 非法编号、会话不存在或已经释放 | 新建会话或从原始着序恢复 |
| 9320003 | 已经终局或棋谱含终局后的着法 | 显示终局,检查棋谱来源 |
| 9320004 | 交点已占或棋谱重复落子 | 保留局面,提示重新选点 |
| 9320005 | 本局关闭悔棋或现有着数不足 | 使用可撤回的手数或继续原局 |
网络错误通过异常或 Promise 拒绝返回。HTTP 业务包的 code: 1 表示成功,code: 0 表示服务端明确拒绝;客户端会保留拒绝原因。响应格式错误或请求超过 15 秒时,应先同步当前棋局,再决定是否重试。排查完整棋室可打开大厅「记录」或设置内「运行记录」复制诊断,避免把邀请令牌或登录凭据放入日志。
注意事项
平台兼容性
以 HBuilderX 5.34 为基线。√ 表示本表所指功能已验证;× 表示当前实现不支持,或所列版本已核实不能运行;– 表示尚未确认可用。选择项目类型后,再看对应的那一张表。
uni-app(5.34) · 传统 Vue 本地棋桌
| Vue2 | Vue3 | Chrome | Safari | app-vue | app-nvue | Android | iOS | 鸿蒙 |
|---|---|---|---|---|---|---|---|---|
| × | √ | √ | – | – | × | – | – | – |
| 微信小程序 | 支付宝小程序 | 抖音小程序 | 百度小程序 | 快手小程序 | 京东小程序 | 鸿蒙元服务 | QQ 小程序 | 飞书小程序 | 小红书小程序 | 快应用华为 | 快应用联盟 |
|---|---|---|---|---|---|---|---|---|---|---|---|
| – | – | – | – | – | – | – | – | – | – | – | – |
Vue 3 的 H5 发行示例已在 Chrome 完成开局、落子和悔棋。Vue 2 在 5.34 环境编译时无法解析规则声明 interface.uts(TS2307)。选择本地棋桌请使用 Vue 3。
uni-app x(5.34) · 完整 Cocos 棋室
| Chrome | Safari | Android | iOS | 鸿蒙 | 微信小程序 |
|---|---|---|---|---|---|
| √ | – | – | – | – | × |
| 移动平台 | 已完成的验证 | 待确认 |
|---|---|---|
| Android | Vapor 宿主编译、规则模块 DEX 构建 | 匹配基座上的完整棋室真机运行 |
| iOS | Vapor 宿主页面编译、生成规则模块 Swift 源码 | Apple 编译链接与真机运行 |
| 鸿蒙 | Vapor 宿主编译、规则模块 HAR 构建 | 完整宿主 HAP 与真机运行 |
其他能力
| 多语言 | 暗黑模式 | 宽屏模式 | 蒸汽模式(Vapor) |
|---|---|---|---|
| × | × | √ | √ |
界面使用中文与固定棋室主题。两份示例均已在 1280×800 的桌面 Chrome 实际落子、悔棋。完整棋室另测 320×568、390×844 和 844×390 视口。Vapor 对应 uni-app x 宿主;WebGL 和本地 WebView 条件见下表。
运行与许可
| 项目 | 条件和边界 |
|---|---|
| 棋规 | 十五路自由规则。满盘且无人连五判和。建议着按本机棋形评分,无法保证必胜 |
| 宿主与部署 | uni-app x 使用 Vue 3 Vapor,完整棋室使用 WebGL;App 还需要能加载随包资源的系统 WebView。传统 .vue 示例使用自己的棋桌并调用相同的 UTS 规则 |
| 退出与暂停 | uni-app x 页面在隐藏时暂停本地棋局,卸载时释放会话。自绘界面须自行处理离开、重开、保存和释放 |
| 联机 | 需要宿主业务服务,房间、聊天连接、凭据和结算由其维护。断线重读以服务端最新状态为准 |
| 基座 | App 首次引入或变更原生 UTS 时,需要使用包含该插件的匹配基座。设备上的表现与构建、系统 WebView 和图形环境相关 |
| 资源许可 | 自有代码与画面许可见 uni_modules/lizhao-gomoku/LICENSE。Cocos 与依赖的许可证位于 uni_modules/lizhao-gomoku/static/creator/,通信脚本许可见 uni_modules/lizhao-gomoku/static/table/DCLOUD-LICENSE.txt。自行替换的图片由宿主取得相应许可 |
作者系列 UTS 插件
| 插件 | 简介 |
|---|---|
| 朱砂棋院 · 中国象棋 | 同系列的中国象棋游戏与 UTS 棋规插件 |

收藏人数:
购买源码授权版(
试用
赞赏(0)
下载 6486
赞赏 5
下载 12779675
赞赏 1960
赞赏
京公网安备:11010802035340号