做 2D 场景和界面
代码说明:运行完整示例前,先准备本页说明的项目配置、场景或协议。局部用法中的 Token、节点、回调和业务函数须来自实际项目,不能单独原样粘贴运行。
前面几页,你的客户端脚本已经能连上服务器、读取游戏状态了。但光有数据没用——你得把它们画到屏幕上。
客户端:第一个2D画面你学过最基础的操作:找到节点、改节点。这一页往前走一步:怎么组织场景、怎么做界面交互、怎么播放动画和音效。
你手里有哪些工具
所有脚本 API 都从 ./sdk/flexcore 引入。主要模块:
| 模块 | 干什么 |
|---|---|
scene | 切换场景、实例化、查找节点 |
node | 创建节点、连接信号、释放节点 |
transform | 2D/3D 坐标、旋转、缩放、显示/隐藏 |
ui | Label、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 订阅(与服务端通信)。