处理客户端消息
代码说明:运行完整示例前,先准备本页说明的项目配置、场景或协议。局部用法中的 Token、节点、回调和业务函数须来自实际项目,不能单独原样粘贴运行。
上一页你学会了用 System 让对象自动运转。但有一类操作我们还没讲:玩家主动触发的动作——点击宝箱、释放技能、购买物品、发起交易。
这些操作和 System 不一样:System 是引擎自动调度的,而玩家动作是客户端发起请求,服务端验证后才执行。这一页讲的就是这条链路。
核心原则
客户端发送的是操作意图,不是权威结果。
玩家点击"使用药水",客户端只是跟服务端说"我想用药水"。能不能用、用了之后回多少血、背包里还有没有——这些全部由服务端判断。客户端永远不能直接修改服务端数据。
协议是什么
协议描述两端共同遵守的消息名称、数字 ID、版本与字段编码。客户端 RPC API 使用字符串协议名,例如 "chest.open";服务端 server.protocols.on 使用 ProtocolDefinition。二者不能互换。协议元数据应从项目实际编译产物或共同契约取得,不手写示例数字 ID冒充项目定义。
服务端处理器的首参是 Uint8Array。必须按协议约定解码,并验证字段类型与范围;不能直接解构 payload.chestId,也不能无依据把所有消息当作普通 JSON。
客户端怎么发请求
在已连接、已认证,且项目已注册对应协议后使用:
import { client } from "@flexcore/client";
const result = await client.rpc.call(
"chest.open",
{ chestId: "1001" },
{ timeoutMs: 5_000 },
);
client.rpc.send("chest.cancel", { chestId: "1001" });
call 等待响应,send 不等待业务确认。超时或网络错误需由项目处理;不能因为客户端等待结束就假定服务端没有执行过操作。涉及扣款等操作,应在业务契约中设计去重。
服务端怎么处理
下面是可类型检查的注册函数。调用方须提供项目真实 ProtocolDefinition、与协议匹配的解码器及权限校验函数。后者应检查目标归属、距离和当前状态;没有这些项目输入,函数不会自行注册协议。最终对象修改仍由同步 System 执行并再次验证。
import { server } from "@flexcore/server";
import type { ProtocolDefinition, ProtocolContext } from "@flexcore/server";
export function registerChestOpen(
definition: ProtocolDefinition,
decodeChestOpen: (payload: Uint8Array) => unknown,
canOpen: (chestId: string, context: ProtocolContext) => Promise<boolean>,
) {
return server.protocols.on(definition, async (payload, context) => {
const request = decodeChestOpen(payload);
if (!context.entityId || context.worldId === null) {
return { ok: false, reason: "not_logged_in" };
}
if (!request || typeof request !== "object" || !("chestId" in request) ||
typeof request.chestId !== "string" || !/^[1-9][0-9]*$/.test(request.chestId)) {
return { ok: false, reason: "invalid_chest_id" };
}
if (!await canOpen(request.chestId, context)) return { ok: false, reason: "not_allowed" };
await server.events.emit("chest.tryOpen", {
chestId: request.chestId, playerId: context.entityId, worldId: context.worldId,
}, { mode: "async", delivery: "async" });
return { ok: true }; // 已接收意图,最终对象状态以同步结果为准
});
}
ProtocolHandler 能做什么
ProtocolHandler 的签名为 (payload: Uint8Array, context: ProtocolContext) => unknown | Promise<unknown>,支持异步读取存储。get(collection, key, { mode: "async" }) 返回 StorageObject<T> | null,数据在 .value,版本在 .version;put(collection, key, value, writeOptions, { mode: "async" }) 需要五个参数。可直接参考保存数据和更新版本中的购买示例。
购买价格必须取自服务端可信商品配置,不能使用客户端提交的 price。先验证 null 和 unknown,再读余额;写入时带 expectedVersion 或使用事务,避免并发覆盖。扣款与发货应作为同一业务原子操作处理。
ProtocolContext 里有什么
connectionId 标识连接,entityId 和 worldId 可能为 null;还有连接代次、序号和协议元信息。它没有 world,不能把 worldId 当作 context.world 使用。
Event handler 同样没有 context.world。事件可以用于异步通知、记录待处理意图;项目需在同步 System 的执行时机读取意图并重新验证、操作对象。emit 不会自动把事件变成 System 回调,也不会自动提交 Entity Draft。
System、Protocol、Event 怎么配合
这是 FlexCore 里最容易混淆的部分。用一张表说清楚:
| 机制 | 谁触发 | 能操作对象吗 | 能异步吗 | 典型用途 |
|---|---|---|---|---|
| System | 引擎自动调度 | ✅ 有 context.world | ❌ 必须同步 | 回血、巡逻、碰撞检测 |
| Protocol handler | 客户端请求 | ❌ 没有 context.world | ✅ 可以 async | 接收请求、验证、读写存储 |
| Event handler | 代码 emit 触发 | ❌ 没有 context.world | ✅ 可以 async | 异步 IO、跨模块通知 |
一个完整的"玩家打开宝箱"流程,三种机制配合:
客户端:client.rpc.call("chest.open", { chestId })
│
▼
Protocol handler(可 async)
│ 验证:玩家在旁边吗?宝箱开过了吗?
│ 读取存储确认权限
│
▼ 验证通过,发事件
Event:server.events.emit("chest.tryOpen", { chestId }, { mode: "async", delivery: "async" })
│ 项目代码记录意图,按 worldId/entityId 路由
│
▼
System(同步,有 context.world)
│ chest.state = "open"
│ context.world.presentation.emit(...) ← 发金光特效
│
▼
StateSync 自动同步 → 客户端看到宝箱打开了
服务端主动发消息
有时候服务端需要主动给客户端发消息(不是响应请求),比如:
- 系统公告:"服务器将在 5 分钟后维护"
- 跨模块通知:战斗模块通知 UI 模块"你被攻击了"
- 广播:某个世界事件发生,通知所有在线玩家
用 server.messaging.send():
// 给特定受众发消息
server.messaging.send(
audience, // AudienceHandle:谁能看到这条消息
messageId, // 消息 ID
sequence, // 序列号
payload, // Uint8Array:消息内容
{ mode: "sync" }, // 执行模式
);
messaging 和 protocols 的区别:
protocols | messaging | |
|---|---|---|
| 方向 | 客户端 → 服务端 | 服务端 → 客户端 |
| 触发方 | 客户端发起 | 服务端主动 |
| 有返回值 | call() 有 | 没有 |
常见错误
请求成功了,但客户端画面没变
client.rpc.call() 得到响应后,还要检查项目定义的业务结果;它本身不代表客户端的本地状态已经更新。
客户端应该通过 observe() 等待 StateSync 推送的变化,而不是在 call() 返回后立刻刷新画面。
// ❌ 错误:call 返回后就改画面
await client.rpc.call("chest.open", { chestId: "1001" });
showChestOpen(); // 此时状态可能还没同步过来
// ✅ 正确:等 observe 触发后再改画面
chest.observe(
v => v.state,
(newState) => {
if (newState === "open") showChestOpen();
},
{ emitCurrent: true },
);
await client.rpc.call("chest.open", { chestId: "1001" });
把 connectionId 当权限证明
context.connectionId 只是"这条消息从哪个连接来的"。它不是权限。
服务端仍然需要验证:这个连接绑定的实体有没有权限做这件事?比如玩家说自己要打开宝箱 #1001,服务端要检查这个玩家是不是在宝箱旁边、宝箱是不是属于这个玩家。
无限重试失败的操作
请求失败后不要立刻重试。如果是权限问题或状态问题(宝箱已开、金币不够),重试一万次还是失败。
应该给用户一个可理解的提示("金币不足"、"宝箱已被打开"),让用户决定下一步做什么。
回头看
这一页的核心就一句话:客户端发意图,服务端做决策。
整条链路:
客户端 call/send → Protocol handler 验证 → System/Event 执行 → StateSync 自动同步 → 客户端 observe 响应
你现在已经认识了 FlexCore 的全部核心机制:
- Schema:定义对象
- System:自动驱动对象
- Protocol(本页):接收玩家指令
- StateSync:自动同步状态
- Presentation:瞬时特效
接下来的章节会讲更具体的能力:持久化存储、地图切换、AOI 视野管理……