服务端:第一个游戏规则
代码说明:运行完整示例前,先准备本页说明的项目配置、场景或协议。局部用法中的 Token、节点、回调和业务函数须来自实际项目,不能单独原样粘贴运行。
这一页带你把服务端项目真正跑起来。完成后,你会有一份能启动的代码、一个能记录事件的模块,并知道下一步该把游戏逻辑写在哪里。
你会得到什么
跟着做完后,你的项目里会有:
- 一个能被 FlexCore 加载的服务端模块
- 一个启动时会增加观测计数的回调
- 一个能跟随世界创建/销毁的临时状态
这看起来不多,但它是所有后续规则的共同起点——角色、战斗、任务、背包,都要从"模块能跑起来"开始。
需要准备什么
- 已安装
fc-tools
- 已解压包含 SDK、配套 Node.js、npm 和 TypeScript 的引擎包
- 一个自主选择的项目目录,比如
./first-flexcore-game
第一步:创建项目
fc-tools.exe server init --project ./first-flexcore-game --install --engine-root ./engine
cd ./first-flexcore-game
fc-tools.exe server check --project .
./engine 是所选引擎目录;请在执行前换成实际路径。三条命令分别完成以下步骤:
- init:用默认模板创建项目,生成
scripts/main.ts和scripts/schema.ts
- cd:进入项目目录
init --install 同时从所选引擎离线恢复 SDK 和配套编译器。普通 npm install 不能替代这一步。
- check:检查项目结构是否完整、能不能被 FlexCore 识别
如果 check 没报错,说明你的项目已经是一个合法的 FlexCore 服务端工程了。
第二步:看看你的第一个模块
打开 scripts/main.ts,你会看到这样的代码:
import { defineGameplayModule } from "@flexcore/module";
import { moduleId, server } from "@flexcore/server";
export default defineGameplayModule({
id: moduleId("@project/main"),
version: "1.0.0",
setup(module) {
module.onActorStart(() => {
server.observability.counter(
"script.runtime.ready",
1,
{},
{ mode: "sync" },
);
});
module.onWorldInit((world) => {
world.scope.set("initialized", true);
});
module.onWorldDestroy((world) => {
world.scope.clear();
});
},
});
不用紧张,我们逐段拆开看:
模块的定义
export default defineGameplayModule({
id: moduleId("@project/main"),
version: "1.0.0",
setup(module) { /* 在此注册回调 */ },
});
defineGameplayModule:告诉 FlexCore"这是一个玩法模块"
id:模块的唯一标识,用moduleId()包起来保证格式正确
version:语义化版本号(比如1.0.0),升级模块时要改它
setup:模块的入口函数,所有规则都在这里注册
三个生命周期回调
module.onActorStart(() => { ... }); // Actor 启动时
module.onWorldInit((world) => { ... }); // 世界创建时
module.onWorldDestroy((world) => { ... }); // 世界销毁时
这三个回调是 FlexCore 给你的"入场时机":
| 回调 | 什么时候触发 | 适合做什么 |
|---|---|---|
onActorStart | 服务端启动,Actor 准备就绪 | 记录日志、初始化全局配置 |
onWorldInit | 一个世界(比如一张地图)被创建 | 给这个世界准备临时状态 |
onWorldDestroy | 世界被销毁 | 清理临时状态 |
两个核心 API
server.observability.counter("script.runtime.ready", 1, {}, { mode: "sync" });
这是 FlexCore 的"埋点"接口。你可以用它记录任何事件:玩家登录、怪物被击杀、技能释放……后面排查问题时,这些计数会非常有用。
world.scope.set("initialized", true);
world.scope 是一个临时存储区,只在这个世界存活期间有效。世界销毁时它会自动清空。适合放一些"当前世界运行中需要、但不需要持久化"的临时数据。
⚠️ world.scope 不是数据库。需要长期保存的数据(玩家等级、背包物品)要选择并配置相应持久化路径,见保存数据和更新版本,我们下一步会讲到。
第三步:构建项目
fc-tools.exe server build --project .
构建会做两件事:
- 编译 Schema:检查
scripts/schema.ts里的数据定义是否合法
- TypeScript 检查:确保你的代码没有类型错误
构建成功,说明你的模块入口、SDK 导入、项目结构都通过了工具链验证。这是写复杂逻辑前的安全网。
第四步:运行起来看看
fc-tools.exe server dev --project .
dev 命令的运行方式与所需配置以随包工具帮助和完整操作手册为准;本页的计数器代码不等于已配置好数据库、通信与运行授权。
启动后,你应该能在观测系统中确认 script.runtime.ready 计数已触发——这就证明你的模块真的被加载了,onActorStart 回调真的执行了。
确认这个计数,你就完成了"第一个游戏规则":让模块跑起来。 🎉
下一步:从模块到游戏对象
到目前为止,你的模块还只是增加了观测计数并设置了临时状态。真正的游戏需要处理对象:玩家、怪物、道具、技能。
FlexCore 的做法是先定义数据,再写规则:
1. 在 Schema 里定义对象
打开 scripts/schema.ts,你会看到:
import { defineSchema } from "@flexcore/schema";
export default defineSchema({
formatVersion: 1,
audiences: {},
components: {},
});
现在是空的。下一步你要在这里定义你的游戏对象——比如"玩家有血量、有等级"、"怪物有攻击力、有掉落表"。
2. 用 server.system() 注册规则
定义完对象后,用 server.system() 注册处理这些对象的规则:
server.system(PlayerToken, (player, context) => {
// 每个玩家都会跑这段逻辑
});
这里的 PlayerToken 是 Schema 编译后自动生成的"对象句柄",你不需要手写它的 ID。
3. 编译后会生成什么
当你用 class-first 编译器处理 Schema 后,会生成这些文件:
generated/server/server.generated.ts ← 服务端类型定义
generated/server/server.runtime.generated.ts ← 运行时 Token(如 PlayerToken)
generated/client/client.generated.ts ← 客户端类型定义
不要手写 Token 的数字 ID,也不要复制测试里的 ID。Token 由 Schema 编译结果提供,在模块命名空间与稳定 lock 下保持身份一致。
常见问题
setup() 里能直接写游戏逻辑吗?
不建议。setup() 的作用是注册回调(就像我们刚才做的),不是处理游戏对象。
比如"每帧检查玩家是否死亡"这种持续运行的处理,应该写成专门的规则,注册到引擎里让它自动调度。这一页还没讲到怎么写这种规则,请继续阅读编写游戏规则。
world.scope 里能存玩家的等级、背包吗?
不能。scope 是临时存储,世界一销毁就全没了——服务器重启、换地图,里面的东西都会丢失。
玩家的等级、背包这种需要长期保存的数据,要放在专门的持久化存储里。这一页还没讲到,后面会专门讲怎么存。
回调返回的句柄要不要保存?
生命周期回调会返回一个"可释放句柄"。模块正常停止时由引擎自动清理。只有当你需要在运行期间动态注册/注销回调时,才需要手动保存和管理这个句柄。
还有其他生命周期回调吗?
有。除了 onActorStart / onWorldInit / onWorldDestroy,还有:
onWorldTick:每个世界每帧触发(接收tick计数)
onActorStop:Actor 停止时触发
这些在写更复杂的逻辑时会用到。
小结
走到这里,你已经掌握了 FlexCore 服务端开发的最小闭环:
init 创建项目
→ main.ts 定义模块
→ setup() 注册回调
→ build 验证结构
→ dev 运行起来
→ 观测计数确认模块被加载
接下来的方向:
- 想让游戏有对象?去
schema.ts里定义你的第一个 Entity
- 想让对象动起来?用
server.system()注册处理规则
- 想保存数据?用
@State({ persistent: true })定义需要持久化的状态
每一步都从"能跑起来"开始,确认有效后再扩展。这是 FlexCore 推荐的开发节奏。