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

学习与实践

文档中心

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

处理交互和画面反馈

代码说明:运行完整示例前,先准备本页说明的项目配置、场景或协议。局部用法中的 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" });
方法返回值适用场景
callPromise(拿到服务端响应)需要知道结果(购买、攻击、查询)
sendvoid(发了就不管)不需要结果(广播消息、心跳、日志上报)

💡 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)
          血量、位置、状态                特效、音效、飘字
          一定会送达                      可能丢失
          断线可恢复                      播完即弃

记住核心原则:数据走状态同步,演出走表现事件。 两条通道各司其职,不要让它们互相替代。

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

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

Powered by Discuz! X5.0

© 2001-2026 Discuz! Team.

返回顶部