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

学习与实践

文档中心

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

服务端:第一个游戏规则

代码说明:运行完整示例前,先准备本页说明的项目配置、场景或协议。局部用法中的 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 推荐的开发节奏。

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

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

Powered by Discuz! X5.0

© 2001-2026 Discuz! Team.

返回顶部