客户端:第一个 2D 画面
代码说明:运行完整示例前,先准备本页说明的项目配置、场景或协议。局部用法中的 Token、节点、回调和业务函数须来自实际项目,不能单独原样粘贴运行。
上一页你在服务端让模块跑了起来——但说实话,跑起来之后你只能盯着日志看。这一页不一样了:你会让屏幕上出现东西。
客户端开发最爽的地方就是即时反馈——改一行代码,画面立刻给你回应。这一页我们要做的很简单:在画面上显示一行文字、放一个可见的标记。但就是这两个操作,是所有客户端开发的基础——HUD、背包界面、角色动画、特效,都要从"脚本找到节点、改节点"开始。
你需要的东西:已解压的引擎包、其中的 fc-tools 和一个自主选择的项目目录(比如 ./first-flex-client)。准备好了就开始。
第一步:创建项目
fc-tools.exe client init --project ./first-flex-client --engine-root ./engine
cd ./first-flex-client
fc-tools.exe client check --project . --engine-root ../engine
./engine 代表你选择的引擎目录,请换成实际位置;改变工作目录后相应调整路径。三条命令分别完成以下步骤:
- init:创建客户端工程,生成
src/scripts/main.ts(脚本入口)和src/scripts/sdk/flexcore.ts(引擎 API)
- cd:进入项目目录
init --engine-root 从所选引擎恢复客户端 SDK 和配套工具链,不承诺普通 npm install 即可完成。
- check:检查工程结构是否完整、能不能被 FlexEngine 识别
如果 check 没报错,说明你的项目已经是一个合法的 FlexCore 客户端工程了。
第二步:认识你的脚本
打开 src/scripts/main.ts。默认情况下,它只有几行简单的代码,大概长这样:
import { FlexCore } from "./sdk/flexcore";
FlexCore.log("客户端脚本已加载");
这行代码做的事情很简单:从本地 SDK 引入 FlexCore 全局对象,然后输出一行日志。
flexcore.ts 是什么
注意 import 的路径是 ./sdk/flexcore,而不是某个 npm 包。这是 FlexCore 故意设计的:
初始化项目时,fc-tools 会在 src/scripts/sdk/ 下生成一个 flexcore.ts,它把引擎的所有脚本 API 暴露给你——包括 scene(场景)、node(节点)、transform(变换)、ui(界面控件)、input(输入)、resources(资源)等等。
始终从 ./sdk/flexcore 引入这些 API,不要从其他地方引入。这样你的脚本才能和引擎版本保持一致。
💡 你可能还会看到一个叫 @flexcore/client 的包。那个包负责的是连接服务器、收发网络数据,不是控制画面的。这一页用不到它,后面讲到网络联机时才会用到。
第三步:在场景里准备两个节点
脚本要控制的东西不是凭空产生的——你得先在画面上放一些"节点"。
节点是 FlexEngine 场景的基本单位。一个标签、一个图片、一个按钮,都是一个节点。每个节点有名字,脚本通过名字找到它们。
现在你需要两个节点:
- 一个叫
StatusLabel的标签(Label)——用来显示文字
- 一个叫
Marker的节点(Node2D 或 Sprite)——用来显示一个可见的标记
怎么创建它们?用 dev 命令打开编辑器:
fc-tools.exe client dev --project . --engine-root ../engine --open-editor
编辑器打开后,在场景树里添加这两个节点,给它们命名。
⚠️ 如果你还不熟悉编辑器,也可以先跳过这一步,直接写下面的脚本。运行时脚本会发现节点不存在——这正好让我们练习怎么处理这种情况。
第四步:用脚本控制节点
回到 src/scripts/main.ts,把内容替换成:
import { node, transform, ui } from "./sdk/flexcore";
// 1. 找到标签,设置文字
const label = ui.label("StatusLabel");
if (label.ok) {
label.value.setText("客户端已准备");
}
// 2. 找到标记节点,移动到指定位置并显示
const marker = node.get("Marker");
if (marker.ok) {
transform.setPosition2D(marker.value, { x: 160, y: 96 });
transform.setVisible(marker.value, true);
}
不用紧张,我们逐段拆开看:
所有操作都返回 Result
你可能注意到 label.ok 和 marker.ok 这种写法。这是 FlexCore 的一个重要约定:
每一个查找操作都返回一个 Result。Result 有两种状态:
ok为true:成功了,可以通过.value拿到结果
ok为false:失败了,可以通过.error查看原因
为什么要这样设计?因为节点可能不存在——名字打错了、场景里忘了放、节点被删了……Result 让你必须先检查再使用,不会因为找不到节点而导致整个脚本崩溃。
查找节点
const label = ui.label("StatusLabel"); // 按名字找 UI 标签
const marker = node.get("Marker"); // 按路径找节点
ui.label()专门找 UI 控件(标签、按钮、输入框等)
node.get()按路径找任意节点(比如"Marker"或"UI/Panel/Title")
修改节点
label.value.setText("客户端已准备"); // 设置标签文字
transform.setPosition2D(marker.value, { x: 160, y: 96 }); // 移动到 (160, 96)
transform.setVisible(marker.value, true); // 设为可见
setText是标签控件的方法
transform.setPosition2D设置 2D 坐标
transform.setVisible控制显示/隐藏
transform 是一个独立的 API 模块,专门负责节点的位置、旋转、缩放、可见性。
第五步:检查并运行
fc-tools.exe client check --project . --engine-root ../engine
fc-tools.exe client dev --project . --engine-root ../engine --open-editor
- check:TypeScript 检查 + 工程结构校验
- dev --open-editor:编译脚本、打包资源、打开 FlexEngine 编辑器
如果一切正常,编辑器运行后你应该能看到:
StatusLabel显示"客户端已准备"
Marker出现在坐标 (160, 96)
看到这两个效果,你就完成了"第一个 2D 画面":让脚本成功控制了画面上的节点。
下一步:从静态画面到动态交互
到目前为止,你的画面还是静态的——文字写死了,位置固定了。真正的游戏需要:
- 响应玩家输入:用
inputAPI 监听键盘、鼠标
- 播放动画:用
animationAPI 控制角色动画
- 连接服务器:用
@flexcore/client接收服务端发来的游戏状态
- 渲染实体:用
entityAPI 把服务端的角色、怪物显示到画面上
画面能力在 ./sdk/flexcore 中,网络联机能力在 @flexcore/client 中,后面的章节会逐步讲到。
常见问题
节点名字写对了,但 ok 还是 false?
检查以下几点:
- 节点是否在当前运行的场景里(而不是别的场景)
- 节点名字的大小写是否完全一致
- 如果用
node.get()传的是路径,确认路径层级正确
ui.label() 和 node.get() 有什么区别?
ui.label() 专门找 UI 控件,返回的是控件代理(有 setText 等 UI 专属方法)。 node.get() 找任意节点,返回的是通用节点代理。如果你只需要改位置、可见性,用 node.get 就够了;如果需要操作 UI 控件特有功能,用对应的 ui.* 方法。
为什么要从 ./sdk/flexcore 引入,不能用 @flexcore/client?
它们负责的事情完全不同:
./sdk/flexcore:控制画面——场景、节点、UI、动画、音频、资源……这一页用的就是这个
@flexcore/client:连接服务器——网络通信、RPC、接收游戏状态……联机时才用
混用会导致 API 找不到或类型不匹配。
顶层便捷函数(setText、onClick 等)和 ui.* / node.* 有什么关系?
flexcore.ts 还提供了一些顶层便捷函数,比如 setText("StatusLabel", "你好")、onClick("Btn", () => {})。它们是 ui.* 和 node.* 的简化写法,内部实现是一样的。
区别在于:便捷函数不返回 Result,找不到节点时会静默跳过。适合快速做原型;正式开发建议用 ui.* / node.* + Result 检查,这样能及时发现问题。
回头看
这一页你做的事情,用一句话概括:脚本通过名字找到场景里的节点,然后改它。
听起来朴素,但客户端开发的核心循环就是这个:
找节点 → 改节点 → 看效果 → 再改 → 再看
后面的所有能力——输入响应、动画播放、网络联机——都是在这个循环上加东西:
| 你想要 | 用什么 |
|---|---|
| 玩家按键盘,角色动起来 | input API |
| 角色跑起来有动作 | animation API |
| 和服务端联机,看到别的玩家 | @flexcore/client + entity API |
画面能力由 ./sdk/flexcore 提供,联机能力由 @flexcore/client 提供,后面的章节逐个展开。