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

学习与实践

文档中心

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

做 2D 场景和界面

代码说明:运行完整示例前,先准备本页说明的项目配置、场景或协议。局部用法中的 Token、节点、回调和业务函数须来自实际项目,不能单独原样粘贴运行。

前面几页,你的客户端脚本已经能连上服务器、读取游戏状态了。但光有数据没用——你得把它们画到屏幕上。

客户端:第一个2D画面你学过最基础的操作:找到节点、改节点。这一页往前走一步:怎么组织场景、怎么做界面交互、怎么播放动画和音效。


你手里有哪些工具

所有脚本 API 都从 ./sdk/flexcore 引入。主要模块:

模块干什么
scene切换场景、实例化、查找节点
node创建节点、连接信号、释放节点
transform2D/3D 坐标、旋转、缩放、显示/隐藏
uiLabel、Button、Input 等控件
input监听键盘/手柄输入
animation播放动画、补间动画
audio播放音效
resources加载和释放资源

每个模块的函数几乎都返回 Result——还记得 客户端:第一个2D画面的约定吗?先检查 .ok 再读 .value。


场景管理

切换场景

import { scene } from "./sdk/flexcore";

// 切换到指定场景(异步,等加载完成)
const result = await scene.change("Town");
if (!result.ok) {
  console.error("切换失败", result.error.code);
}

// 切换并等待根节点就绪,直接拿到根节点
const ready: unknown = await scene.changeAndWait("Dungeon");
if (ready && typeof ready === "object" && "ok" in ready && ready.ok === true) {
  const root = scene.activeRoot();
  if (root.ok) transform.setVisible(root.value, true);
}

change 发起切换;changeAndWait 等待场景根就绪。r2 随包 facade 的后者推断结果为 unknown,示例先检查返回形状,再通过 scene.activeRoot() 取得可收窄的节点结果。

注册场景回调

import { scene } from "./sdk/flexcore";
import type { SceneHandlers } from "./sdk/flexcore";

const handlers: SceneHandlers = {
  onReady() {
    console.log("Town 场景就绪");
  },
  onDestroy() {
    console.log("场景被销毁");
  },
};
scene.register("Town", handlers);

SceneHandlers.onReady 是无参数回调,不接收 payload;不要与全局 scene.onReady 事件订阅混用。它在场景加载完成、根节点可用后触发。onDestroy 在场景被切换走时触发。

实例化和父子关系

有时候你不切场景,而是在当前场景里实例化一个预制体:

import { scene, transform } from "./sdk/flexcore";

// 用资源 ID 实例化(注意是 AssetId,不是文件路径)
const enemy = scene.instantiate("注册表中的场景AssetId", {
  parent: "Enemies",              // 挂到哪个父节点下
  name: "Slime_01",               // 节点名字
  position: { x: 200, y: 150 },   // 初始位置
  visible: true,
});

if (enemy.ok) {
  transform.setVisible(enemy.value, true);
}

⚠️ instantiate 的第一个参数是 AssetId(字符串),须从项目实际资源注册表取得;不能把文件路径或任意名字当成 AssetId。本页“注册表中的…”字符串都是需替换的占位,未指向已交付素材。

查找节点

// 从场景根按路径查找
const label = scene.getNode("UI/Panel/HpLabel");
if (label.ok) {
  // ...
}

// 从指定节点按相对路径查找
const parent = scene.getNode("UI/Panel");
if (parent.ok) {
  const child = scene.find(parent.value, "HpLabel");
}

节点操作

创建和释放

import { node } from "./sdk/flexcore";

// 创建一个新节点
const sprite = node.create("Sprite2D", {
  name: "Marker",
  position: { x: 100, y: 100 },
});
if (sprite.ok) {
  // ... 使用它
  // 不再需要时释放(只能释放 API 创建的节点)
  node.queueFree(sprite.value);
}

读写属性和调用方法

// 设置属性
node.setProperty(target, "modulate", { r: 1, g: 0, b: 0 });

// 读取属性
const visible = node.getProperty(target, "visible");
if (visible.ok && typeof visible.value === "boolean") {
  console.log("是否可见:", visible.value);
}

// 调用节点上的方法
const result = node.call(target, "set_texture", textureId);

监听信号

节点的信号(比如按钮点击、动画结束)可以通过 on 监听:

const sub = node.on(button, "pressed", () => {
  console.log("按钮被按了");
});

// 不再监听时
sub.dispose();

变换:位置、旋转、缩放

transform 模块负责节点在 2D 和 3D 空间中的变换:

import { transform } from "./sdk/flexcore";

// 2D 位置
transform.setPosition2D(marker, { x: 160, y: 96 });

// 取整位置(像素稳定,避免亚像素抖动)
transform.setPosition2DRounded(marker, { x: 160, y: 96 });

// 读取位置
const pos = transform.getPosition2D(marker);
if (pos.ok) {
  console.log(pos.value.x, pos.value.y);
}

// 旋转(弧度)
transform.setRotation2D(marker, Math.PI / 4);  // 顺时针 45°

// 缩放(传数字 = 等比缩放)
transform.setScale2D(marker, 2.0);           // 放大 2 倍
transform.setScale2D(marker, { x: 2, y: 1 }); // 只拉宽

// 显示/隐藏
transform.setVisible(marker, false);

💡 2D 游戏里,setPosition2DRounded 比普通 setPosition2D 更常用——它把坐标取整后再设置,避免精灵之间出现亚像素缝隙。


UI 控件

获取控件

import { ui } from "./sdk/flexcore";

// 按类型获取(语义清晰,但不影响返回类型)
const hpLabel = ui.label("HpLabel");
const btn = ui.button("ConfirmButton");
const nameInput = ui.input("NameInput");

// 通用获取
const panel = ui.get("InfoPanel");

虽然 label() / button() / input() 返回的都是同一种 ControlProxy,但用对应类型的方法能提高代码可读性。

操作控件

if (hpLabel.ok) {
  hpLabel.value.setText("HP: 100/100");   // 设置文字
  const text = hpLabel.value.getText();    // 读取文字
}

if (btn.ok) {
  btn.value.setDisabled(true);  // 禁用按钮
  btn.value.focus();            // 聚焦
}

顶层快捷函数

flexcore.ts 还提供了一些顶层便捷函数,适合快速原型:

import { setText, onClick, setVisible } from "./sdk/flexcore";

setText("HpLabel", "HP: 100/100");        // 直接按名字设置文字
setVisible("Cursor", false);               // 直接按名字隐藏
onClick("ConfirmButton", () => {           // 直接按名字绑定点击
  console.log("点击了确认");
});

💡 便捷函数不返回 Result,找不到节点时静默跳过。快速验证想法时很方便;正式开发建议用 ui.* + Result 检查。


输入

查询输入状态

import { input } from "./sdk/flexcore";

// 某个 action 当前是否按下
if (input.isActionPressed("move_right")) {
  // 持续向右移动
}

// 模拟强度(手柄摇杆,返回 0~1)
const strength = input.getActionStrength("move_right");

监听输入事件

// 监听按键按下/抬起
const sub = input.onAction("jump", (pressed: boolean) => {
  if (pressed) {
    // 按下瞬间跳跃
    playJump();
  }
});

// 不再监听
sub.dispose();

onAction 的回调参数是布尔值:true = 按下,false = 抬起。

为什么不能直接监听"按了哪个键"

你可能注意到——上面的 API 全都接收 Action 名(字符串),不是键码。本节使用的 ./sdk/flexcore Action 接口不提供这些函数;不要由此推断其他 SDK 入口也没有物理输入能力。

这是设计上故意的。FlexEngine 的输入系统分两层:

物理按键(键盘/手柄/鼠标)     Action(抽象动作)      脚本代码
  空格键        ──映射──▶  "jump"        ──监听──▶  input.onAction("jump", ...)
  W 键 / 摇杆上  ──映射──▶  "move_up"     ──监听──▶  input.onAction("move_up", ...)
  鼠标左键      ──映射──▶  "attack"      ──监听──▶  input.onAction("attack", ...)

映射在引擎配置层完成(编辑器的 InputMap 面板),脚本只管 Action 名。这样做的好处:

  • 换设备不用改代码——同一个 "jump" Action,PC 上绑空格键,手柄上绑 A 键,手机上绑屏幕按钮,脚本代码一行都不用改。
  • 支持组合绑定——一个 Action 可以绑多个按键(比如 "attack" 同时绑鼠标左键和手柄扳机)。
  • 支持模拟强度——getActionStrength 对键盘返回 0 或 1,对摇杆返回 0~1 的渐进值,脚本用同一套代码处理。

所以,如果你想知道"玩家按了空格键",做法是:

  • 在编辑器的 InputMap 里,把空格键绑定到一个 Action(比如 "jump")
  • 脚本里监听这个 Action:
input.onAction("jump", (pressed: boolean) => {
  if (pressed) {
    console.log("玩家触发了跳跃(可能是空格、手柄A键、屏幕按钮……取决于配置)");
  }
});

⚠️ 本节 Action 接口不返回具体物理按键,只返回哪个 Action 被触发。如果需要区分物理按键(比如做按键自定义界面),要在引擎配置层处理,不在脚本侧。


动画

播放动画

以下 player 应是场景中实际的 AnimationPlayer/AnimationMixer 节点,不是任意角色根节点。

import { animation } from "./sdk/flexcore";

// 播放动画
animation.play(player, "idle", { loop: true });

// 播放一次性动画
animation.play(player, "attack", {
  speed: 1.5,     // 1.5 倍速
  loop: false,
});

// 停止
animation.stop(player, {});

// 暂停 / 恢复
animation.pause(player);
animation.resume(player);

监听动画事件

// 动画播完时触发
const sub = animation.onFinished(player, (animName: string) => {
  if (animName === "attack") {
    animation.play(player, "idle", { loop: true });
  }
});

// 动画内部的事件点(在编辑器里打的关键帧事件)
animation.onEvent(player, (payload: AnimationEventPayload) => {
  if (payload.event === "hit") {
    // 命中关键帧触发本地表现,权威伤害由服务端计算
    dealDamage();
  }
});

补间动画(Tween)

Tween 用来做平滑过渡——移动到某个位置、淡入淡出等。返回的 Promise 解析表示取得 Tween 句柄,不代表动画已经播完,不能把 .then() 当作播放结束通知:

// 让节点平滑移动到目标位置
const tween = await animation.tween(marker, {
  property: "position",
  to: { x: 300, y: 200 },
  duration: 0.5,
  easing: "ease_out",
});

if (tween.ok) {
  // 需要中途取消时
  // tween.value.stop();
}

音效

import { audio } from "./sdk/flexcore";

// 播放音效(异步,返回句柄)
const handle = await audio.play("注册表中的跳跃音效AssetId", {});  // "注册表中的跳跃音效AssetId" 是音效的 AssetId
if (handle.ok) {
  // 调整音量
  handle.value.setVolume(0.5);

  // 停止播放
  handle.value.stop();
}

// 播放 BGM(循环)
const bgm = await audio.play("注册表中的背景音乐AssetId", { loop: true, volume: 0.3 });

资源

检查资源是否存在

import { resources } from "./sdk/flexcore";

if (resources.exists("注册表中的场景AssetId")) {
  console.log("资源存在");
}

// 查看资源信息
const info = resources.info("注册表中的场景AssetId");
if (info.ok) {
  console.log(info.value.type);  // 资源类型
  console.log(info.value.path);  // 资源路径
}

加载资源

// 加载文本
const text = resources.text("注册表中的文本AssetId");
if (text.ok) {
  console.log(text.value.value);  // 文本内容
}

// 加载 JSON
const config = resources.json<{ level: number }>("注册表中的配置AssetId");
if (config.ok && config.value.value) {
  console.log(config.value.value.level);
}

// 异步加载二进制
const data = await resources.load("注册表中的二进制AssetId");
if (data.ok) {
  // data.value.value 是 ArrayBuffer
}

释放资源

const handle = resources.text("注册表中的文本AssetId");
if (handle.ok) {
  // 用完后释放
  resources.release(handle.value);
}

💡 资源句柄由取得它的代码按生命周期管理。示例应在不再使用时释放持有的句柄;不要假定场景切换会代替所有手动获取句柄的清理。


把它串起来:一个交互流程

下面可放入客户端入口。先在场景中准备 HpLabel 和 Player/AnimationPlayer,配置 jump Action 及 jump 动画,将 jumpSoundAssetId 替换为实际资源注册表中的字符串 ID。它演示本地表现,不修改服务端权威位置;血量更新函数由收到游戏数据的代码调用。

import { scene, ui, input, animation, audio } from "./sdk/flexcore";

const hpLabel = ui.label("HpLabel");
const playerAnimation = scene.getNode("Player/AnimationPlayer");
const jumpSoundAssetId = "注册表中的跳跃音效AssetId";
const inputSub = input.onAction("jump", (pressed: boolean) => {
  if (!pressed || !playerAnimation.ok) return;
  const played = animation.play(playerAnimation.value, "jump", {});
  if (!played.ok) console.error("跳跃动画播放失败", played.error.code);
  void audio.play(jumpSoundAssetId, {}).then(sound => {
    if (!sound.ok) console.error("跳跃音效播放失败", sound.error.code);
  });
});

export function updateHp(current: number, max: number) {
  if (hpLabel.ok) hpLabel.value.setText(`HP: ${current}/${max}`);
}
export function disposeInteraction() {
  inputSub.dispose(); // 场景退出时由项目生命周期调用
}

常见问题

instantiate 报 resource.invalid_asset_id?

请检查传入值是否为项目实际资源注册表中的字符串 AssetId,不能传数字或直接传文件路径。

动画不播放?

检查:

  • 节点上是否有 AnimationPlayer 子节点
  • 动画名称是否拼写正确(大小写敏感)
  • 用 animation.has(node, "attack") 确认动画是否存在

onAction 没反应?

确认 action 名称在 InputMap 中已定义。用 input.isActionPressed("你的action名") 在每帧日志里测试一下,看是否返回 true。

UI 控件找不到?

  • 确认控件在当前运行的场景里(不是别的场景)
  • 名字大小写完全一致
  • 用 node.get("UI/Panel/HpLabel") 带完整路径试一下

回头看

这一页覆盖了客户端表现层的全部核心能力:

场景(scene)→ 节点(node)→ 变换(transform)→ 控件(ui)
                                                        ↓
输入(input)→ 动画(animation)→ 音效(audio)→ 资源(resources)

记住一个原则:UI 和表现层只负责呈现,真正的游戏数据在服务端。 想改数据?发 RPC 请求(07 页)。想响应数据变化?用 observe 订阅(与服务端通信)。

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

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

Powered by Discuz! X5.0

© 2001-2026 Discuz! Team.

返回顶部