编写游戏规则
代码说明:运行完整示例前,先准备本页说明的项目配置、场景或协议。局部用法中的 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是否设得太大(等太久才触发)
- 回调里有没有抛异常(会在日志里看到错误)