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

学习与实践

文档中心

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

定义游戏对象

代码说明:运行完整示例前,先准备本页说明的项目配置、场景或协议。局部用法中的 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——写法更自然,可读性更好。

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

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

Powered by Discuz! X5.0

© 2001-2026 Discuz! Team.

返回顶部