定义游戏对象
代码说明:运行完整示例前,先准备本页说明的项目配置、场景或协议。局部用法中的 Token、节点、回调和业务函数须来自实际项目,不能单独原样粘贴运行。
上一页你看到了一个完整的功能链路——客户端发请求、服务端处理、状态同步、客户端响应。但那里有个东西我们一笔带过了:宝箱的数据结构从哪来?
答案就是这一页的主题:Schema。
在 FlexCore 里,你用装饰器告诉引擎:"我的游戏里有这些对象,它们长这样,这些字段客户端能看到。"引擎拿到这份"说明书"后,才能帮你生成代码、同步状态、验证数据。
定义一个对象
先看一个最小的例子——定义一个"玩家":
// scripts/schema.ts
import { Entity, Field, GameEntity } from "@flexcore/schema";
@Entity("Player")
export class Player extends GameEntity {
@Field.string({ visibility: "public", clientAccess: "readonly" })
name = "";
@Field.uint32({ visibility: "public", clientAccess: "readonly" })
level = 1;
@Field.int32({ visibility: "public", clientAccess: "readonly" })
hp = 100;
}
拆开看几个部分:
@Entity("Player"):告诉引擎"这是一个实体类型,名字叫 Player"。实体是游戏里有身份、有生命周期、能被查找的对象。
extends GameEntity:所有实体都继承这个基类。
@Field.string()/@Field.uint32()/@Field.int32():声明字段的类型。
= ""/= 1/= 100:字段的默认值,直接写就行,跟普通 TypeScript 类一样。
写完这个类,编译器就会帮你生成 Token(操作句柄)、同步规则、类型定义——你不需要手写这些。
给实体加方法
class-first 的核心优势是数据和行为放在一起。你可以在类里直接写方法,像普通 TypeScript 类一样:
import { Entity, Field, GameEntity } from "@flexcore/schema";
@Entity("Player")
export class Player extends GameEntity {
@Field.int32({ min: 0, visibility: "public", clientAccess: "readonly" })
hp = 100;
@Field.int32({ min: 0, visibility: "public", clientAccess: "readonly" })
maxHp = 100;
takeDamage(amount: number) {
this.hp = Math.max(0, this.hp - amount);
}
heal(amount: number) {
this.hp = Math.min(this.maxHp, this.hp + amount);
}
get isDead() {
return this.hp <= 0;
}
}
然后在 System 回调里直接调用:
server.system(PlayerToken, (player) => {
if (player.isDead) return;
player.heal(5); // 调用类方法
});
方法内部对 this.hp 的修改,和直接写 player.hp += 5 效果一样——都会被引擎追踪、自动同步。
用继承复用逻辑
import { Entity, Field, GameEntity } from "@flexcore/schema";
@Entity("Character", { abstract: true })
export abstract class Character extends GameEntity {
@Field.int32({ min: 0, visibility: "public", clientAccess: "readonly" }) hp = 100;
takeDamage(amount: number) {
this.hp = Math.max(0, this.hp - amount);
}
}
@Entity("Player")
export class Player extends Character {
@Field.string({ visibility: "public", clientAccess: "readonly" }) name = "";
}
@Entity("Monster")
export class Monster extends Character {
@Field.int32() attack = 10;
}
Player 和 Monster 都继承了 takeDamage,不用重复写。这就是 class-first 的优势——数据和逻辑都在同一条继承链上。
⚠️ 方法里不能做异步操作(不能 async),也不能跨回调保存 this——和直接在 System 里写逻辑的限制一样。
四种类型
FlexCore 的数据模型有四种类型,用不同的装饰器区分:
| 装饰器 | 是什么 | 例子 |
|---|---|---|
@Entity | 实体——有身份、有生命周期、能被 World 创建和查询 | 玩家、怪物、宝箱、NPC |
@Component | 组件——可复用的字段组,能附加到多个实体 | Transform(位置)、Health(血量) |
@Object | 嵌入对象——纯数据结构,没有身份,嵌在字段里 | Attributes(属性组)、Vec2(坐标) |
@State | 世界状态——整个世界共享的数据,不属于某个实体 | GameState(回合数、存活人数) |
Entity 和 Component 怎么配合
import { Component, Entity, Field, GameEntity } from "@flexcore/schema";
@Component("Health")
export class Health {
@Field.int32({ min: 0, visibility: "public", clientAccess: "readonly" })
hp = 100;
@Field.int32({ min: 0, visibility: "public", clientAccess: "readonly" })
maxHp = 100;
}
@Component("Transform")
export class Transform {
@Field.float32({ visibility: "public", clientAccess: "readonly" })
x = 0;
@Field.float32({ visibility: "public", clientAccess: "readonly" })
y = 0;
}
@Entity("Player", { components: [Health, Transform] })
export class Player extends GameEntity {
@Field.string({ visibility: "public", clientAccess: "readonly" })
name = "";
}
这段声明记录 Player 与 Health、Transform 的组件关系。但 r2 的 class-first 生成结果不会把这些组件字段展平为 PlayerRuntimeContract 或 PlayerClientView 的字段;不能据此直接写 player.hp 或在客户端读取 player.x。本指南后续回血示例采用前面“给实体加方法”中直接声明 hp、maxHp 的 Player。需要复用可直接访问的实体行为时,可参考上面的类继承示例,实际访问方式以生成产物为准。
Object 和 Entity 有什么区别
import { Object, Entity, Field, GameEntity } from "@flexcore/schema";
@Object("Attributes")
export class Attributes {
@Field.int32({ min: 0 })
strength = 10;
@Field.int32({ min: 0 })
agility = 10;
}
@Entity("Player")
export class Player extends GameEntity {
@Field.object(Attributes)
attributes = { strength: 10, agility: 10 } as Attributes;
}
Object 是"嵌在字段里的纯数据"——它没有自己的 ID,不能被 World 单独查询,只是某个实体字段的一部分。你可以把它理解成"结构体"。
State:世界共享的数据
import { State, Field } from "@flexcore/schema";
@State("GameState", { persistent: true })
export class GameState {
@Field.int32()
round = 1;
@Field.uint32()
alivePlayerCount = 0;
}
State 不属于任何实体,而是整个世界共享的。通过 context.world.state(GameStateToken) 访问(下一页会讲)。
persistent: true 声明该状态需要持久化;实际恢复还依赖持久化配置、成功保存的快照及恢复路径,不能据此保证任意崩溃后的全部最新修改都已落盘。
字段类型
FlexCore 提供了丰富的字段类型。在 class-first 里通过 @Field.xxx() 来指定:
基本类型
@Field.string({ visibility: "public", clientAccess: "readonly" }) name = "";
@Field.bool() active = false;
@Field.int32({ visibility: "public", clientAccess: "readonly" }) hp = 100;
@Field.uint32({ visibility: "public", clientAccess: "readonly" }) level = 1;
@Field.uint64() experience = 0n;
@Field.float32() rate = 1.0;
常用类型一览:
| 装饰器 | 用途 | 默认值写法 |
|---|---|---|
@Field.string() | 文本 | = "hello" |
@Field.bool() | 布尔值 | = true |
@Field.int32() / @Field.uint32() | 32 位整数(4 字节) | = 100 |
@Field.int64() / @Field.uint64() | 64 位整数(8 字节) | = 0n |
@Field.int128() / @Field.uint128() | 128 位整数(16 字节) | = 0n |
@Field.bigint() | 变长大整数(大小不确定时用) | = 0n |
@Field.float32() / @Field.float64() | 浮点数 | = 1.0 |
@Field.decimal() | 精确小数(货币类) | = "3.14" |
@Field.entityRef(Player, { optional: true }) | 可选实体引用 | targetId: bigint | undefined |
为什么有 bigint 还要有 int32 / uint64 这些具体类型?
区别在于存储和传输占多少字节:
int32/uint32:固定 4 字节
int64/uint64:固定 8 字节
bigint:变长,数值越大字节越多
游戏服务器里每个字段每天要在网络上来回传输几百万次。给字段选一个够用的具体类型(比如玩家等级用 uint32 就够了),比统一用 bigint 省下大量带宽和内存。只有当你真的不确定数值范围时,才用 bigint。
💡 @Field 的类型和默认值的写法是两件事。
@Field.uint64() 决定的是这个字段最终怎么存、怎么传——用 4 字节还是 8 字节。这是"存储格式"。 默认值 = 0n 只是 JavaScript 写大整数的一种方式(在数字后面加个 n)。
打个比方:你去寄快递,@Field 的类型是你选的箱子大小(小箱、中箱、大箱);0n 是你在寄件单上填数字时用的写法。两者各管各的——你怎么填单子,不影响箱子大小。
那为什么大数字非要用 0n?因为 JavaScript 普通数字有精度上限,遇到大数字会丢精度。统一用 0n 就不会出这个问题。引擎拿到你写的 0n 后,会自动按 @Field 指定的格式去存储——你只管写 0n,剩下的交给引擎。
复合类型
除了基本类型,你还能把多个字段组合起来:
import { Object, Entity, Field, GameEntity } from "@flexcore/schema";
@Object("Attributes")
export class Attributes {
@Field.int32() strength = 10;
@Field.int32() agility = 10;
}
@Entity("Player")
export class Player extends GameEntity {
// 嵌入对象:一组不同类型的字段
@Field.object(Attributes)
attributes = { strength: 10, agility: 10 } as Attributes;
// 引用另一个实体
@Field.entityRef(Player, { optional: true })
targetId: bigint | undefined;
}
@Field.object() 嵌入一个 Object 类型;@Field.entityRef(Player, ...) 引用另一个实体,引用值必须大于零,不能用 0n 冒充不存在的实体。没有目标时使用可选字段并保持未设置。还有 @Field.list() 和 @Field.map() 用于列表和映射,用法类似。
字段约束
在装饰器选项里加约束:
import { Entity, Field, GameEntity } from "@flexcore/schema";
@Entity("Player")
export class Player extends GameEntity {
@Field.uint32({ min: 1, max: 99 , visibility: "public", clientAccess: "readonly" })
level = 1;
@Field.string({ visibility: "public", clientAccess: "readonly" })
name = "";
}
编译器检查约束和默认值是否合法;运行时输入也必须验证。r2 的 Field.string 选项不支持 maxLength,名字长度应在服务端业务校验中检查。
visibility:谁能看到这些数据
在 class-first 里,visibility 是字段级别的——你可以精确控制每个字段的可见性:
import { Entity, Field, GameEntity } from "@flexcore/schema";
@Entity("Player")
export class Player extends GameEntity {
// 客户端能看到
@Field.string({ visibility: "public", clientAccess: "readonly" })
name = "";
@Field.int32({ visibility: "public", clientAccess: "readonly" })
hp = 100;
// 客户端看不到——只有服务端知道
@Field.float32({ visibility: "server-only" })
dropRate = 0.1;
// 私密任务暂时仅保留在服务端
@Field.string({ visibility: "server-only" })
secretQuest = "";
}
本页可编译示例使用以下两种取值:
visibility | 含义 | 例子 |
|---|---|---|
"public" | 所有视野内的客户端都能看到 | 血量、位置、外观 |
"server-only" | 只有服务端知道 | AI 状态、掉落概率、内部计时器 |
💡 不写时默认为 visibility: "server-only" 和 clientAccess: "excluded"。需要客户端读取的字段须显式写 visibility: "public" 与 clientAccess: "readonly"。
r2 的 TypeScript 选项声明中虽包含 owner-only,但随包 class-first 编译会拒绝该值;当前不能把它作为可用写法。需要私密字段时先保持服务端专用,按项目真实通信契约控制接收者,不用 public 代替私密投影。
⚠️ 不要把所有字段都设成 "public"。服务端专用的数据(AI 逻辑、概率配置、反作弊状态)应该设为 "server-only",避免泄露给客户端。
数据的生命周期
不同类型的数据,存活的时间不一样:
| 类型 | 活多久 | 怎么定义 |
|---|---|---|
| Entity 字段 | 跟随实体——实体销毁就没了 | @Field.xxx() |
| World State | 跟随世界——世界销毁就没了 | @State("X") |
| World State(持久化) | 可按配置从已保存状态恢复 | @State("X", { persistent: true }) |
| 临时字段 | 只在一次回调内有效 | @Transient() |
@Transient:临时字段
有些数据不需要进同步、不需要持久化,只是临时用一下(比如缓存、当前目标):
import { Entity, Field, GameEntity, Transient } from "@flexcore/schema";
@Entity("Monster")
export class Monster extends GameEntity {
@Field.int32({ visibility: "public", clientAccess: "readonly" })
hp = 100;
@Transient()
cachedTargetId = ""; // 临时缓存,不进同步、不持久化
}
@Transient 标记的字段不进入同步、不进入持久化、不进入生成的契约——它只是普通的 TypeScript 类字段。
编译 Schema
Schema 写好后,需要编译它:
fc-tools.exe schema --entry scripts/schema.ts --class-first --module @demo/game --output generated --lock schema.lock.json
两个关键参数:
--class-first:告诉编译器用装饰器模式解析(只读 AST,不执行你的代码)
--module @demo/game:你的模块命名空间,编译器用它生成全局唯一的 ID
本命令从已恢复的项目依赖查找 TypeScript。若在项目外单独编译,可将 FLEXCORE_TYPESCRIPT_PATH 指向所选引擎的 toolchains/typescript/package/lib/typescript.js,不需要在线安装。
编译器会做这几件事:
- 解析类和装饰器:提取所有
@Entity、@Field等信息
- 校验结构:检查类型、约束、默认值是否合法
- 分配稳定 ID:给每个实体和字段分配唯一的数字 ID
- 生成 lock 文件:
schema.lock.json,记录所有 ID 的映射关系
- 生成运行时文件:Token、类型定义、客户端绑定
💡 schema.lock.json 应该提交到版本控制。它记录稳定身份。重命名应显式使用 renamedFrom 并检查契约差异;不能仅改字段名就假定旧数据自动匹配。
编译后生成什么
上面的命令显式使用 generated 输出目录(未指定时默认 dist/schema),其中会有:
generated/
├── contracts/
│ ├── canonical-ir.v2.json ← 规范化契约 IR
│ ├── contract-diff.json ← 与上一版本的差异
│ └── schema.lock.json ← 输出侧 lock 副本
├── server/
│ ├── server.generated.ts ← 服务端类型
│ └── server.runtime.generated.ts ← 运行时 Token 与绑定
├── client/
│ ├── client.generated.ts ← 客户端类型和 Token
│ └── client.generated.gd ← GDScript(Godot)绑定
其中最重要的是 server.runtime.generated.ts——它导出了你定义的每个实体对应的 Token:
// 自动生成的代码,不要手写
export const PlayerToken = defineManagedEntityToken({ ... });
export const ChestToken = defineManagedEntityToken({ ... });
下一页讲 System 时,你就会从 server.runtime.generated.ts 导入这些 Token。
⚠️ generated 目录下的文件都是自动生成的,不要手动编辑。每次改了 Schema,重新编译就会更新。
改字段时要注意什么
游戏开发是迭代的——你不可能一开始就把所有字段定对。改字段时记住这条规则:
改字段语义时,在装饰器选项里递增 version。
// v1:只有 hp
@Field.int32({ version: 1 , visibility: "public", clientAccess: "readonly" })
hp = 100;
// v2:改了 hp 的语义 → 版本递增
@Field.int32({ version: 2 , visibility: "public", clientAccess: "readonly" })
hp = 100;
// 新增的 maxHp 从 version 1 开始
@Field.int32({ version: 1 , visibility: "public", clientAccess: "readonly" })
maxHp = 100;
版本号帮助引擎和客户端识别"这是同一份数据的不同版本",避免老客户端读到新格式时崩溃。
可以安全做的改动:
- 新增字段(新字段从 version 1 开始)
- 扩大
min/max范围
需要格外小心的改动:
- 删除字段(用
renamedFrom标记重命名,不要直接删)
- 改字段类型(需要迁移数据)
- 缩小
min/max(已有数据可能不合法)
验证
Schema 写好后,用 server build 一次性检查整个项目:
fc-tools.exe server build --project .
如果字段默认值不合法、类型不匹配、约束冲突,编译器会在这里报错,不会让你带着问题继续往下走。
养成习惯:改完 Schema → 编译 → build 检查。这三步是安全网,确保你的数据定义始终是合法的。
高级:Schema-first 写法
上面用的 class-first(装饰器)是推荐的日常写法。FlexCore 还支持另一种叫 Schema-first 的写法——用 defineSchema() 对象字面量来声明:
import { defineSchema, schemaTypes } from "@flexcore/schema";
import { string, uint32 } from "@flexcore/value";
export default defineSchema({
formatVersion: 1,
audiences: {},
components: {
"@demo/player": {
version: 1,
visibility: "public",
fields: {
name: { type: schemaTypes.string, default: string("") },
level: { type: schemaTypes.uint32, default: uint32(1n) },
},
},
},
});
两种写法的对比:
| Class-first(推荐) | Schema-first(高级) | |
|---|---|---|
| 写法 | 装饰器 + 类继承 | 对象字面量 |
| 风格 | 面向对象,接近普通 TypeScript | 声明式数据描述 |
| visibility | 字段级 | 组件级 |
| 默认值 | 直接赋值(= 100) | 构造器(int32(0n)) |
| 编译命令 | --class-first --module ... | 默认(不加 --class-first) |
| 适合 | 日常开发 | 工具生成、批量定义 |
Schema-first 的结构更扁平、更像配置文件,适合工具自动生成或需要批量定义大量数据结构的场景。日常开发建议用 class-first——写法更自然,可读性更好。