找回密码
 立即注册
搜索
热搜: 活动 交友 discuz
跳到内容
FlexCore开发者社区

学习与实践

文档中心

从入门操作到版本更新,找到适合当前阶段的说明。

处理客户端消息

代码说明:运行完整示例前,先准备本页说明的项目配置、场景或协议。局部用法中的 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 的区别:

protocolsmessaging
方向客户端 → 服务端服务端 → 客户端
触发方客户端发起服务端主动
有返回值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 视野管理……

Archiver|小黑屋|FlexCore开发者社区

GMT+8, 2026-11-20 00:20 , Processed in 0.081631 second(s), 5 queries .

Powered by Discuz! X5.0

© 2001-2026 Discuz! Team.

返回顶部