一个游戏功能怎样跑起来
代码说明:运行完整示例前,先准备本页说明的项目配置、场景或协议。局部用法中的 Token、节点、回调和业务函数须来自实际项目,不能单独原样粘贴运行。
前面两页,你在服务端写了一个能跑的模块(见服务端:第一个游戏规则),在客户端写了一段能控制画面的脚本(见客户端:第一个2D画面)。但它们各自独立——服务端不知道客户端在干什么,客户端也不知道服务端在想什么。
一个真正的游戏功能,需要两端配合。这一页用一个具体的例子——玩家打开一个宝箱——带你走完整个链路:从客户端发请求,到服务端处理,再到所有客户端看到变化。
理解了这个链路,你就理解了 FlexCore 的核心设计。
全景图
先看一张整体的数据流向:
客户端:玩家点击宝箱
│
▼ 发送 RPC 请求
服务端:收到请求
│
├─ System 验证:能不能开?玩家在不在旁边?
├─ 验证通过 → 修改宝箱状态(从"关闭"变成"打开")
│
▼ StateSync 自动同步
所有附近的客户端:收到状态更新
│
├─ Observe 发现宝箱状态变了 → 切换画面(显示打开的图)
├─ Presentation 收到"打开"事件 → 播放音效和特效
│
▼
玩家看到:宝箱打开了,金光一闪
整个链路有五个角色,我们逐个认识它们。
第一步:先定义"宝箱是什么"
在写任何逻辑之前,你得先告诉引擎"宝箱"这个对象长什么样。这是在 Schema 里做的。
// scripts/schema.ts(简化示意,下一页会详细讲)
import { Entity, Field, GameEntity } from "@flexcore/schema";
@Entity("Chest")
export class Chest extends GameEntity {
@Field.string({ visibility: "public", clientAccess: "readonly" })
state = "closed";
@Field.string()
itemId = "";
}
这里显式将 state 标为 visibility: "public"、clientAccess: "readonly",客户端才能读取它。itemId 保持默认的 server-only / excluded,只在服务端使用。可见性是字段级设置,还受实体受众与 AOI 等规则约束。
💡 Schema 的完整写法(字段类型、可见性、编译流程)在下一页会专门讲。这里你只需要记住一个概念:对象的字段和可见范围,在 Schema 里一次定义,全程生效。
Schema 定义好后,编译器会帮你生成两样东西:
- 服务端 Token(比如
ChestToken)—— 服务端用它来操作宝箱
- 客户端 Token(比如
ChestClientToken)—— 客户端用它来观察宝箱
你不需要手写这些 Token,它们由编译器自动生成。
第二步:客户端发起请求
玩家走到宝箱旁边,按下交互键。客户端需要告诉服务端:"我要打开这个宝箱。"
怎么告诉?用 RPC(远程过程调用)——客户端调用服务端的一个"协议",把请求发过去:
import { client } from "@flexcore/client";
// 玩家点击了宝箱 #1001
await client.rpc.call("chest.open", { chestId: "1001" });
client.rpc.call() 做的事情:
- 把请求打包,发给服务端
- 等待服务端处理完(所以用
await)
- 服务端返回结果后继续执行
重要:客户端发完请求后,不要假设请求一定成功。也许宝箱已经开过了,也许玩家离得太远——这些由服务端判断。客户端应该等状态同步回来再更新画面(下一步会讲)。
💡 @flexcore/client 是专门负责网络通信的包,和 客户端:第一个2D画面用的 ./sdk/flexcore(控制画面)是两回事。联机功能用 @flexcore/client,画面操作用 ./sdk/flexcore。
第三步:服务端处理请求
服务端收到 "chest.open" 这个请求后,需要做两件事:
- 验证:这个宝箱存在吗?玩家在旁边吗?宝箱已经开过了吗?
- 修改:验证通过后,把宝箱状态从
closed改成open
这些逻辑写在 System 里。System 是 FlexCore 用来处理游戏对象的规则,你在 服务端:第一个游戏规则的结尾已经见过它的预告:
import { server } from "@flexcore/server";
import { ChestToken } from "../generated/server/server.runtime.generated";
// 注册一个处理宝箱的规则
server.system(ChestToken, (chest, context) => {
// 每个"打开"状态的宝箱都会跑这段逻辑
// chest.state、chest.itemId 都可以直接读写
if (chest.state === "open") {
// 已经开过了,什么也不做
return;
}
});
除了 System,服务端还需要注册一个协议处理器来接收客户端的 RPC 请求。协议处理器验证请求并记录待处理意图,由同步 System 再次验证、修改对象状态;StateSync 随后把符合可见性和受众规则的变化同步出去。
你不需要手动写"通知客户端"的代码——字段具备正确的可见性、客户端投影和受众配置时,服务端提交变化后由 StateSync 推送给相关客户端。
第四步:状态自动同步(StateSync)
StateSync 是 FlexCore 的内置机制,你不需要写任何代码来触发它。
它的工作原理很简单:
服务端改了 Chest.state = "open"
↓
StateSync 检测到这个字段变了(而且是 public 的)
↓
找到所有"能看到这个宝箱"的客户端
↓
把变化推送过去
哪些客户端"能看到"?由两个因素决定:
- 字段的
visibility与clientAccess:字段须允许对应受众读取,且生成客户端只读投影;默认server-only/excluded不公开
- AOI(Area of Interest):只有宝箱附近的客户端才会收到,远处的不会
需要公开读取的字段显式写 visibility: "public", clientAccess: "readonly"。r2 的 class-first 编译暂不接受声明中的 owner-only,本例不依赖它。
第五步:客户端响应变化
客户端收到 StateSync 推送的状态变化后,怎么知道"宝箱开了"?
用 Observe——订阅对象某个字段的变化:
import { client } from "@flexcore/client";
import { ChestClientToken } from "./generated/client/client.generated";
// 找到宝箱 #1001 的客户端视图
const chest = client.world.entities.get(ChestClientToken, "1001");
if (!chest) throw new Error("宝箱尚未同步或不在当前视野内");
// 订阅它的 state 字段
const handle = chest.observe(
(value) => value.state, // 只关心 state 字段
(newState, oldState) => { // state 变了就触发
if (newState === "open") {
// 用 ./sdk/flexcore 的 API 切换画面
// 比如显示打开的宝箱图片、播放动画
}
},
{ emitCurrent: true }, // 注册时立即触发一次当前值
);
observe() 做了三件事:
- 选择关注的字段(
value.state)——只有这个字段变了才触发回调
- 变化时执行你的回调——给你新值和旧值
- 返回一个
handle,不需要时调用handle.dispose()取消订阅
为什么用 observe 而不是轮询? 因为 observe 是事件驱动的——状态不变就不触发,状态变了立刻触发。这样可以集中处理变化,具体开销取决于项目。
状态 vs 表现事件
你可能会问:宝箱打开时的"金光特效"和"叮的一声",也是通过 state 变化触发的吗?
不是。 FlexCore 区分两种东西:
| 状态(State) | 表现事件(Presentation) | |
|---|---|---|
| 回答什么问题 | "现在是什么样?" | "刚刚发生了什么?" |
| 生命周期 | 持续存在,可以随时读取 | 瞬时的,错过就没了 |
| 例子 | 宝箱是开还是关、玩家血量多少 | 宝箱打开瞬间的金光特效、受击的屏幕震动 |
| 恢复方式 | 断线重连后可以恢复 | 断线重连后不会重播 |
服务端怎么发表现事件
服务端在修改状态的同时,可以顺便发一个表现事件。以宝箱为例:
import { defineManagedPresentationEventToken } from "@flexcore/server";
// 1. 定义事件 Token:告诉引擎这个事件的 ID 和怎么编码数据
const ChestOpenEffect = defineManagedPresentationEventToken<{ chestId: string }>(
"chest.opened", // 事件 ID
(payload) => new TextEncoder().encode(JSON.stringify(payload)), // 编码器
() => "effect.chest.open", // 内容 ID(对应客户端的特效资源)
);
// 2. 在 System 里发事件(必须和状态修改一起发)
server.system(ChestToken, (chest, context) => {
if (chest.state === "closed") {
chest.state = "open"; // 改状态
// 同时发一个表现事件
context.world.presentation.emit(
ChestOpenEffect,
{ chestId: chest.id },
{
audience: { kind: "all" }, // 谁能看到这个特效
startTick: context.world.tick, // 从哪一帧开始
seed: 0n,
},
);
}
});
关键规则:表现事件必须和状态修改一起提交。不能单独发一个表现事件——如果你只发了事件没改状态,引擎会报错。这样设计是为了保证"看到的特效"和"实际的状态"永远一致。
客户端怎么订阅表现事件
客户端通过 presentation.on() 接收所有表现事件,用 eventId 区分不同类型:
import { presentation } from "@flexcore/client";
presentation.on((event) => {
switch (event.eventId) {
case "chest.opened": {
// 宝箱打开特效
const data = JSON.parse(new TextDecoder().decode(event.payload));
playEffectAt(data.chestId); // 用 ./sdk/flexcore 播放金光特效
playSound("chest_open"); // 播放"叮"的音效
break;
}
case "combat.damage": {
// 伤害飘字
// ...
break;
}
}
});
ClientPresentationEvent 包含几个重要字段:
| 字段 | 含义 |
|---|---|
eventId | 事件类型(如 "chest.opened"),用来区分不同事件 |
contentId | 具体内容标识(如 "effect.chest.open"),对应客户端的特效/音频资源 |
payload | 事件数据(Uint8Array),包含业务信息 |
priority | 优先级("low" / "normal" / "high") |
什么时候用状态,什么时候用表现事件
一个简单的判断标准:
- 必须能恢复的数据(宝箱开没开、玩家多少血)→ 放进状态
- 瞬时的效果(音效、特效、镜头抖动)→ 用表现事件
⚠️ 不要只靠表现事件来保存游戏结果。如果玩家断线重连,表现事件不会重播——但状态会恢复。
几条原则
走到这里,整个链路就清楚了。最后总结几条核心原则:
- 客户端不直接改服务端数据。想改?发 RPC 请求,让服务端验证后改。
- 服务端改了数据,同步是自动的。你不需要写"通知客户端"的代码。
- 客户端用 observe 响应变化,不要轮询。
- 状态和表现事件分工明确:状态管"是什么",表现事件管"发生了什么"。
这四条原则贯穿 FlexCore 的所有设计。后面写任何功能——战斗、任务、交易、聊天——都是在这个框架里填充内容。
下面的章节会讲什么
现在你知道了全链路长什么样,接下来的章节会逐个深入:
- Schema 怎么写:定义对象字段、可见范围、组件组合
- System 怎么注册:服务端处理游戏对象的具体规则
- RPC 协议怎么定义:客户端和服务端之间的通信契约
- Observe 怎么用:客户端响应式更新画面的最佳实践
- 表现事件怎么发:服务端触发、客户端接收瞬时效果