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

学习与实践

文档中心

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

编写游戏规则

代码说明:运行完整示例前,先准备本页说明的项目配置、场景或协议。局部用法中的 Token、节点、回调和业务函数须来自实际项目,不能单独原样粘贴运行。

上一页你在 Schema 里定义了游戏对象——玩家有血量、宝箱有状态、怪物有攻击力。但光定义字段没有意义,你得让这些对象动起来:血量低于多少时扣减移速、怪物多久巡逻一次、玩家死亡后怎么掉落。

这就是这一页的主题:System——FlexCore 处理游戏对象的核心机制。


System 是什么

System 是一条绑定在特定对象类型上的自动执行规则。你告诉引擎"我要处理这种对象",引擎就会在每一帧(或你指定的间隔)把所有匹配的对象交给你。

打个比方:Schema 定义了"玩家有血量"这个事实,System 负责实现"血量每秒恢复 5 点"这个规则。


注册第一个规则:自动回血

使用定义游戏对象的“给实体加方法”示例中直接声明 hp、maxHp 的 Player;不要把组件组合声明误当作已经展平的 Player 字段。现在我们写一条规则:每隔一段时间,自动恢复一点血量。

import { server } from "@flexcore/server";
import { PlayerToken } from "../generated/server/server.runtime.generated";

server.system(
  PlayerToken,           // 处理哪种对象
  (player, context) => { // 每个匹配的对象都会跑这段
    if (player.hp < player.maxHp) {
      player.hp = Math.min(player.maxHp, player.hp + 5);    // 直接改字段,引擎自动同步
    }
  },
  { intervalTicks: 10 }, // 每 10 tick 执行一次
);

拆开看三个部分:

第一个参数——Token:告诉引擎你要处理哪种对象。Token 是 Schema 编译时自动生成的,你从 generated/server/server.runtime.generated.ts 导入它。不要手写数字 ID。

第二个参数——处理函数:引擎把每个匹配的对象交给你。你可以直接读写对象的字段(player.hp、player.maxHp),改了就生效——引擎会自动通过 StateSync 把变化同步给客户端。

第三个参数——选项:intervalTicks: 10 表示"每 10 tick 执行一次"。不填则每 tick 都执行。

💡 什么是 tick? tick 是服务端逻辑的最小时间单位。FlexCore 默认每秒约 20 tick(即每个 tick ≈ 50ms)。所以 intervalTicks: 10 大约是"每半秒执行一次"。


处理函数的两个参数

(player, context) => { ... }

player——当前对象

它是 Schema 里定义的字段的"活副本"。你可以直接读写:

player.hp          // 读
player.hp += 5     // 写
player.hp = 100    // 直接赋值

⚠️ 这个对象只在当前回调内有效。回调结束后它会自动失效,不能再访问——会抛 stale_entity_draft 错误。不要把它存到全局变量里。

context——运行环境

context 提供了当前调度的上下文信息,以及最重要的 context.world——你操作这个世界的入口。


context.world 能做什么

这是你在 System 回调里操作世界的主要工具:

创建新对象

const slime = context.world.create(SlimeToken, {
  hp: 50,
  attack: 5,
}, {
  transform: { x: 100, y: 200 },  // 出生位置
  tags: ["hostile"],                // 标签
});

刚创建的对象在本次回调提交后才会真正出现在世界里。

按 ID 查找对象

const target = context.world.require(NpcToken, "1001");
target.dialogue = "你好,冒险者!";

找不到会抛 target_not_found。

销毁对象

if (player.hp <= 0) {
  context.world.destroy(player);
  // 调用后不能再访问 player,否则会报错
}

读写 World State

World State 是整个世界共享的数据(不是某个对象的)。在 Schema 里用 @State 定义,通过 context.world.state() 访问:

const gameState = context.world.state(GameStateToken);
gameState.alivePlayerCount -= 1;  // 玩家死亡时减少存活人数

发表现事件

在 游戏功能怎么跑起来你已经见过表现事件。在 System 里,通过 context.world.presentation.emit() 发送:

context.world.presentation.emit(
  DeathEffect,
  { playerId: player.id },
  { audience: { kind: "all" }, startTick: context.world.tick, seed: 0n },
);

⚠️ 表现事件必须和状态修改一起发。如果你只发表现事件但没改任何状态,引擎会报错。


调度控制

server.system() 的第三个参数可以控制执行方式:

server.system(
  PlayerToken,
  (player, context) => { ... },
  {
    id: "player.regen",        // 规则的唯一标识(用于日志和调试)
    intervalTicks: 10,         // 每 10 tick 执行一次
    priority: "low",           // 优先级:critical > high > normal > low
    budgetUs: 5000,            // 单次执行预算:5ms,仍受运行时上限约束
  },
);
选项含义不填时的默认值
id规则名称,方便在日志里找到它自动生成
intervalTicks执行间隔(tick 数)每 tick 都执行
priority多条规则冲突时谁先跑"normal"
budgetUs单次执行预算(微秒),仍受运行时上限约束1000(1ms)

超出单次脚本预算会使本次执行失败;不能把同步 JavaScript 回调暂停在任意语句、再于下一 tick 从原语句续跑。调度器因整批预算推迟尚未执行的规则,是另一层调度行为。

什么时候用 intervalTicks

不是所有规则都需要每帧执行:

  • 每帧检查(不填 intervalTicks):碰撞检测、移动同步
  • 每秒检查(intervalTicks: 20):回血、Buff 过期
  • 低频检查(intervalTicks: 100):离线检测、成就统计

频率越低,CPU 占用越少。按需选择。

💡 为什么不用定时器来做回血? 见下面的"定时器"章节——定时器回调没有 context.world,不能操作游戏对象。


原子性:要么全做,要么全不做

这是 System 最重要的特性之一。

一个 System 回调里做的所有修改——改字段、创建对象、销毁对象、发表现事件——会被打包成一个批次。引擎保证:

  • 回调正常结束 → 所有修改一起生效
  • 回调抛异常 → 所有修改全部丢弃,一个都不提交
server.system(PlayerToken, (player, context) => {
  player.hp -= 100;
  // ... 假设这里抛了个异常
  context.world.state(GameStateToken).combatCount += 1;
});

如果异常发生,player.hp 不会减少,combatCount 也不会变。不会出现"扣了血但没算战斗次数"这种半成品状态。

这就是为什么处理函数必须是同步的——不能返回 Promise。异步操作会破坏原子性保证。


定时器:只能做不碰对象的轻量任务

除了 System,FlexCore 还提供了 server.timers 用于按真实时间(毫秒)调度。但它有一个硬限制:

⚠️ Timer 回调里没有 context.world。不能读写对象、创建/销毁实体、发表现事件。需要操作游戏对象的周期性逻辑(回血、巡逻、刷新怪物),必须用上面的 System + intervalTicks。

💡 你可能注意到 JavaScript 自带 setTimeout / setInterval,它们也能定时执行。区别在于:server.timers 由引擎统一管理,支持显式作用域和持久化;选择 world 作用域的任务随该世界清理,不能假定默认任务都绑定世界;而 setTimeout 是脚本运行时的通用能力,不知道游戏世界的生命周期。但两者都拿不到 context.world——回血、巡逻这类操作对象的逻辑,只能用 System。

那定时器能做什么?记录指标、定时通知、会话清理这类不碰对象的轻量任务:

import { server } from "@flexcore/server";

// 1. 注册一个具名处理函数
server.timers.registerHandler("reportMetrics", () => {
  server.observability.counter("metrics.heartbeat", 1, {}, { mode: "sync" });
}, { mode: "sync" });

// 2. 每 60 秒执行一次
server.timers.schedule({
  mode: "sync",
  handler: "reportMetrics",
  delayMs: 60_000,
  intervalMs: 60_000,  // 加了 intervalMs = 循环;不填 = 只触发一次
});

一句话总结:要碰对象 → System;只做记录/通知 → Timer。


验证

注册完规则后,编译检查:

fc-tools.exe server build --project .

如果 Token 名字或字段不匹配(比如 Schema 改了但忘了重新编译),这里会报错。先重新编译 Schema,不要手动改 generated 目录下的文件。

然后运行起来看效果:

fc-tools.exe server dev --project .

通过项目自己的日志、指标或状态变化确认 System 执行情况;不能假定默认日志逐次打印所有调度。如果规则没生效,检查:

  • Token 是否从正确的 generated 文件导入
  • intervalTicks 是否设得太大(等太久才触发)
  • 回调里有没有抛异常(会在日志里看到错误)

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

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

Powered by Discuz! X5.0

© 2001-2026 Discuz! Team.

返回顶部