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

学习与实践

文档中心

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

客户端:第一个 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 画面":让脚本成功控制了画面上的节点。


下一步:从静态画面到动态交互

到目前为止,你的画面还是静态的——文字写死了,位置固定了。真正的游戏需要:

  • 响应玩家输入:用 input API 监听键盘、鼠标
  • 播放动画:用 animation API 控制角色动画
  • 连接服务器:用 @flexcore/client 接收服务端发来的游戏状态
  • 渲染实体:用 entity API 把服务端的角色、怪物显示到画面上

画面能力在 ./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 提供,后面的章节逐个展开。

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

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

Powered by Discuz! X5.0

© 2001-2026 Discuz! Team.

返回顶部