处理交互和画面反馈
代码说明:运行完整示例前,先准备本页说明的项目配置、场景或协议。局部用法中的 Token、节点、回调和业务函数须来自实际项目,不能单独原样粘贴运行。
想象一个场景:玩家按下攻击键,角色挥剑,怪物扣血、冒出一个红色的"-50"、播放命中的音效。
这件事看起来一瞬间就发生了,但拆开来看,它走了一整条链路:
玩家按键 → 客户端发请求 → 服务端计算伤害 → 更新怪物血量
↓
┌─────────────────────┐
↓ ↓
血量同步回客户端 派发表现事件
(持久状态) (瞬态反馈)
↓ ↓
更新血条 播放特效 + 飘字
这条链路里有两类完全不同的"画面反馈"。这一页讲清楚它们各自是什么、怎么处理。
两类反馈:持久状态 vs 瞬态表现
持久状态(用 observe 订阅)
怪物的血量是游戏数据——它必须准确、必须可恢复。玩家断线重连后,血条上显示的数字应该和服务端一致。
这类反馈通过 状态同步 传递,客户端用 observe() 订阅(与服务端通信讲过):
monster.observe(
(v) => v.hp,
(newHp, oldHp) => {
updateHpBar(newHp); // 血量变了,刷新血条
},
{ emitCurrent: true },
);
特点:只关心最终结果。服务端血量从 100 变到 50,客户端只知道"变成了 50",不管中间发生了什么。
瞬态表现(用 presentation.on 接收)
那个红色的"-50"飘字、命中的火花特效、"叮"的一声——它们是演出效果。播完就没了,不影响游戏数据。玩家就算没看到飘字,怪物的血量该是多少还是多少。
这类反馈通过 表现事件(Presentation Event)传递,客户端用 presentation.on() 接收:
import { presentation } from "@flexcore/client";
presentation.on((event) => {
if (event.contentId === "fx.hit.fire") {
playHitEffect(event); // 播放命中特效
}
});
特点:只关心过程表现。告诉你"刚才发生了一次命中,快播放特效",但不负责维护游戏数据。
为什么要分两种
你可能会想:为什么不把飘字也存进怪物的状态里,一起同步过来?
因为表现事件是可能丢失的。网络延迟、客户端卡顿、断线重连——这些情况下特效可能播不出来或播晚了。如果把"是否显示过飘字"当成游戏数据,一旦丢失就会导致数据不一致。
所以 FlexCore 的原则是:
| 持久状态 | 瞬态表现 | |
|---|---|---|
| 传递方式 | StateSync 状态同步 | Presentation 表现事件 |
| 客户端接收 | observe() | presentation.on() |
| 丢了会怎样 | 会自动补发(重连后全量同步) | 丢了就丢了,不影响游戏结果 |
| 典型内容 | 血量、位置、装备、状态标记 | 特效、音效、飘字、震屏 |
| 生命周期 | 实体存活期间一直有效 | 播完即弃 |
💡 一句话记忆:状态同步解决"当前结果",表现事件解决"短时过程"。不要只靠表现事件来保存必须恢复的游戏结果。
第一步:捕获输入,发送请求
交互的起点是玩家操作。用 做2D场景和界面学过的输入 API 监听按键(FlexEngine 的输入系统基于 Action 抽象,脚本监听的是 "attack" 这样的动作名,不是物理键码——详见 做2D场景和界面"为什么不能直接监听按了哪个键"):
import { input } from "./sdk/flexcore";
import { client } from "@flexcore/client";
// 监听攻击键
const sub = input.onAction("attack", (pressed) => {
if (!pressed) return; // 只在按下瞬间触发
attack();
});
async function attack() {
// 发送攻击请求给服务端
const result = await client.rpc.call("combat.attack", {
targetId: "2001", // 怪物的实体 ID
});
// result 是服务端返回的响应
console.log("攻击结果", result);
}
call 还是 send
client.rpc 有两个方法:
// call:请求-响应,等服务端返回
const result = await client.rpc.call("combat.attack", { targetId: "2001" });
// send:单向发送,不等返回
client.rpc.send("chat.broadcast", { message: "hello" });
| 方法 | 返回值 | 适用场景 |
|---|---|---|
call | Promise(拿到服务端响应) | 需要知道结果(购买、攻击、查询) |
send | void(发了就不管) | 不需要结果(广播消息、心跳、日志上报) |
💡 call 会等待服务端响应,网络慢时 await 会延后后续处理,但不会阻塞整个 JavaScript 线程。如果不需要返回值,用 send 更轻量。
第二步:接收持久状态变化
服务端收到攻击请求后,会计算伤害、扣减怪物血量。这个血量变化通过状态同步推送到客户端。
你不需要做额外的事情来"接收"——只要在实体出现时就用 observe() 订阅好:
import { client } from "@flexcore/client";
import { MonsterClientToken } from "./generated/client/client.generated";
// 找到怪物实体
const monster = client.world.entities.get(MonsterClientToken, "2001");
if (monster) {
// 订阅血量——服务端扣血后自动触发
monster.observe(
(v) => v.hp,
(newHp) => {
updateHpBar(newHp); // 刷新血条
},
{ emitCurrent: true },
);
}
这部分在 与服务端通信详细讲过,这里不再重复。
第三步:接收瞬态表现事件
光更新血条不够——你还要播放命中的火花特效、飘出伤害数字、播放音效。这些通过表现事件传递。
注册表现事件回调
import { presentation } from "@flexcore/client";
presentation.on((event) => {
// 每一个表现事件都会走到这里
handlePresentation(event);
});
presentation.on() 接收一个回调函数,所有表现事件都会经过这个回调。你需要根据事件自身的标识来决定怎么处理。
⚠️ presentation.on() 返回 void,不像 observe() 或 input.onAction() 那样返回可 dispose() 的句柄。如果想取消注册,需要用 events.off("presentation:event")(见本页末尾"句柄清理"一节)。
表现事件里有什么
每个表现事件(ClientPresentationEvent)包含这些字段:
interface ClientPresentationEvent {
contentId: string; // 内容标识,如 "fx.hit.fire"
eventId: string; // 事件标识,如 "combat.hit"
priority: "low" | "normal" | "high"; // 优先级
payload: Uint8Array; // 附加数据(需要自己解码)
latePolicy: "skip" | "fallback" | "update_required";
worldId: number;
seed: string; // 随机种子(供项目采用确定性表现逻辑)
startTick: string;
sequence: string;
// ...其他元数据字段
}
开发者最常用的是三个字段:
contentId— 告诉你"该播什么"。比如"fx.hit.fire"表示火属性命中特效,"ui.damage_popup"表示飘伤害数字。
payload— 附加数据,比如伤害值、命中位置。它是Uint8Array,通常用 JSON 解码。
priority— 优先级。系统负载高时,"low"优先级的事件可能被丢弃。
处理事件:解码 + 分派
function handlePresentation(event) {
// 解码 payload(JSON 格式的 Uint8Array)
const data = JSON.parse(
new TextDecoder().decode(event.payload)
);
switch (event.contentId) {
case "fx.hit.fire":
// 播放火花特效,data 里可能有坐标、伤害值
spawnHitEffect(data.x, data.y, "fire");
break;
case "ui.damage_popup":
// 飘伤害数字
showDamagePopup(data.amount, data.x, data.y);
break;
case "audio.hit":
// 播放命中音效
playHitSound(data.soundId);
break;
}
}
💡 payload 永远是 Uint8Array,不是结构化对象。必须在回调里自己解码。最常见的是 JSON,但也可能是二进制格式——取决于服务端怎么编码的。
优先级意味着什么
| 优先级 | 行为 |
|---|---|
"high" | 高优先处理,仍不是可靠持久交付保证 |
"normal" | 正常投递 |
"low" | 系统过载时第一个被丢弃 |
所以:重要的表现事件(大招特效、关键剧情演出)应该用 "high" 或 "normal";不重要的(环境粒子、远处的次要音效)可以用 "low"。
优先级由服务端在派发事件时指定,客户端只读取。
串联:一次完整的攻击交互
下面是可类型检查的接线函数。项目提供真实 ClientEntityToken、目标 ID、表现载荷解码器及界面回调,不手写 Token 的契约 ID。场景须包含 Player/AnimationPlayer 和 attack 动画,并配置 attack Action。这里通过 events.on("presentation:event") 取得独立订阅句柄,退出时只清理本函数注册的回调。
import { scene, input, animation } from "./sdk/flexcore";
import { client, events } from "@flexcore/client";
import type { ClientEntityToken, ClientDisposable } from "@flexcore/client";
type Effect = { x: number; y: number; amount: number };
export function setupAttackFeedback(
monsterToken: ClientEntityToken<{ readonly hp: number }>,
monsterId: string,
decodeEffect: (payload: Uint8Array) => Effect | null,
spawnHitEffect: (x: number, y: number) => void,
showDamagePopup: (amount: number, x: number, y: number) => void,
updateHpBar: (hp: number) => void,
) {
// 1. 接收表现事件,只按项目约定的编码解码。
const effectSub = events.on("presentation:event", (event: unknown) => {
if (!event || typeof event !== "object" || !("contentId" in event) ||
!("payload" in event) || !(event.payload instanceof Uint8Array)) return;
if (event.contentId !== "fx.hit.fire" && event.contentId !== "ui.damage_popup") return;
const data = decodeEffect(event.payload);
if (!data) return;
if (event.contentId === "fx.hit.fire") spawnHitEffect(data.x, data.y);
else showDamagePopup(data.amount, data.x, data.y);
});
// 2. 初始同步和基线替换后重新订阅目标。
let healthSub: ClientDisposable | undefined;
const bindHealth = () => {
healthSub?.dispose();
const monster = client.world.entities.get(monsterToken, monsterId);
healthSub = monster?.observe(v => v.hp, hp => updateHpBar(hp), { emitCurrent: true });
};
const readySub = events.on("world:ready", bindHealth);
bindHealth(); // 若实体尚未进入视野,get 返回 null,待后续项目实体可见通知再次绑定
// 3. 本地播放挥剑,请求服务端计算权威结果。
const inputSub = input.onAction("attack", (pressed: boolean) => {
if (!pressed) return;
const player = scene.getNode("Player/AnimationPlayer");
if (player.ok) animation.play(player.value, "attack", {});
void client.rpc.call("combat.attack", { targetId: monsterId }).catch(error => {
console.error("攻击请求失败", error);
});
});
return { bindHealth, dispose() {
inputSub.dispose(); effectSub.dispose(); readySub.dispose(); healthSub?.dispose();
} };
}
注意第 3 步里一个细节:攻击动画是本地立即播放的,不等服务端返回。这是因为动画是角色自己的表现,不需要等服务端确认——按下就挥剑,体验才流畅。而怪物的血量变化、命中特效则是等服务端推过来的。
这种"本地即时表现 + 服务端权威"的思路在联网游戏里很常见:
| 内容 | 谁说了算 | 什么时候播 |
|---|---|---|
| 角色挥剑动画 | 客户端自己 | 立即播放 |
| 怪物扣血 | 服务端 | 等状态同步 |
| 命中特效 | 服务端触发 | 等表现事件 |
| 伤害飘字 | 服务端触发 | 等表现事件 |
句柄清理
输入监听、节点信号、状态订阅都会返回可 dispose() 的句柄。页面结束或不再需要时,必须清理:
// 这些都返回 Disposable
const inputSub = input.onAction("attack", handler);
const nodeSub = node.on(button, "pressed", handler);
const observeSub = monster.observe(selector, handler);
// 清理
inputSub.dispose();
nodeSub.dispose();
observeSub.dispose();
但 presentation.on() 是个例外——它返回 void,没有句柄。如果要取消表现事件回调,用 events 模块:
import { events } from "@flexcore/client";
// 取消所有表现事件回调
events.off("presentation:event");
⚠️ events.off("presentation:event") 会移除所有注册在该事件名上的回调,不能只移除其中一个。所以表现事件回调通常只在页面初始化时注册一次,不频繁增删。
常见问题
飘字 / 特效没出现?
按顺序排查:
- 服务端有没有派发? 表现事件由服务端代码触发,确认服务端逻辑确实派发了对应
contentId的事件。
- 优先级太低被丢了? 如果事件优先级是
"low",系统过载时会被丢弃。检查服务端日志有没有DroppedLowPriority。
contentId拼写对了吗? 客户端的switch (event.contentId)要和服务端派发时用的字符串完全一致(大小写敏感)。
payload解码失败? 如果JSON.parse抛异常,整个回调会中断。加try/catch保护一下。
血量变了但飘字没出来?
这是正常的——血量和飘字走的是两条独立的通道。血量走状态同步(一定会到),飘字走表现事件(可能丢)。不要假设"收到血量变化就一定能收到对应的飘字"。
能不能不表现事件,自己根据血量变化算飘字?
可以,但不推荐。比如你观察到血量从 100 变到 50,自己算出"-50"然后飘字。问题是:
- 你不知道伤害的类型(火?冰?物理?),不知道该播什么颜色的特效
- 你不知道命中的位置,不知道特效该播在哪
- 如果一次扣了多段伤害,你只能看到一个总差值,飘不出多段数字
这些信息只有服务端知道,所以由服务端通过表现事件告诉你。
call 和 send 能不能混用?
可以,它们只是两种不同的发送方式,服务端用同一个 ProtocolHandler 接收。区别只在于客户端是否等待响应。
回头看
一次交互从按键到画面,经过三个阶段:
输入(input)→ 请求(rpc)→ 服务端处理
↓
┌──────────────────────────────┐
↓ ↓
持久状态(observe) 瞬态表现(presentation)
血量、位置、状态 特效、音效、飘字
一定会送达 可能丢失
断线可恢复 播完即弃
记住核心原则:数据走状态同步,演出走表现事件。 两条通道各司其职,不要让它们互相替代。