连接游戏和读取状态
代码说明:运行完整示例前,先准备本页说明的项目配置、场景或协议。局部用法中的 Token、节点、回调和业务函数须来自实际项目,不能单独原样粘贴运行。
前面几页,你的客户端脚本已经能控制画面上的节点了。但那是"单机"状态——画面上只有你一个人。真正的游戏需要联机:连上服务器,看到其他玩家,接收服务端推送的状态。
这一页讲客户端怎么从"断开"变成"在线",以及连上之后怎么读取游戏数据。
连接之前:先认证
FlexCore 使用独立的认证服务。客户端不能直接连游戏服——得先登录认证服务,拿到一张"门票"(Ticket),再用门票去连游戏服。
为什么要分两步?因为认证服务和游戏服是不同的服务器,各管各的事:
- 认证服务负责"你是谁"——验证账号密码,发放 Ticket
- 游戏服负责"你在干什么"——处理游戏逻辑,同步状态
客户端 认证服务 游戏服
│ │ │
│── 账号 + 密码 ──────────▶│ │
│◀── Ticket + 游戏服地址 ─│ │
│ │ │
│── 用 Ticket 连接 ─────────────────────────────────▶│
│◀── 认证通过,进入游戏 ──────────────────────────────│
第一步:登录认证服务
用 @flexcore/auth-client(一个独立的 npm 包,不依赖 FlexEngine):
import { createAuthClient } from "@flexcore/auth-client";
// 创建认证客户端
const auth = createAuthClient({
baseUrl: "https://auth.example.invalid", // 替换为项目认证服务地址
realmId: "项目realm",
titleId: "项目title",
environmentId: "项目environment",
});
// 登录
const login = await auth.login({
account: "alice",
password: "secret123",
});
// login 里包含:
// - gameServer:游戏服的地址和端口
// - gameTicket:用于连接游戏服的门票
login 中包含这些字段(以下仅为结构节选;实际可信身份还包含签名身份信息,不要自行裁剪后重建连接参数):
{
gameServer: {
host: "game1.yourgame.com",
port: 7777,
transport: "tcp", // 或 "websocket"
},
gameTicket: "eyJhbGciOi...", // 一次性 Ticket,不在日志中输出
}
💡 认证服务返回的 Ticket 有时效限制。过期后需要重新登录获取新 Ticket——不能把一张 Ticket 用一辈子。
第二步:连接游戏服
拿到 Ticket 后,用 @flexcore/client 连接游戏服:
import { client } from "@flexcore/client";
client.connect(
login.gameServer.host, // "game1.yourgame.com"
login.gameServer.port, // 7777
{
transport: login.gameServer.transport, // "tcp" 或 "websocket"
credential: login.gameTicket, // 认证门票
gameServer: login.gameServer, // 保留认证服务返回的可信游戏服身份
},
);
client.connect() 做的事情比你想象的多——它不是简单地建立 TCP 连接,而是走完一整个安全握手和认证流程。
连接状态机
从 connect() 到"能收发游戏数据",客户端会经历这些状态:
Disconnected
→ Connected TCP/WebSocket 连接建立
→ Secure 加密握手完成(800/801)
→ AwaitingAuthentication 等待 Ticket 验证(802)
→ Authenticated Ticket 验证通过(803)
→ EntityAttached 玩家实体绑定完成
这些状态由引擎自动管理,你不需要手动推进。但你需要知道:只有在 Authenticated 之后,才能收发项目协议;只有在 EntityAttached 之后,才能读取游戏实体。
怎么知道连接到了哪一步?监听引擎事件:
import { events } from "@flexcore/client";
events.on("world:ready", () => {
console.log("初始同步完成,可以读取实体了");
});
events.on("connection:closed", (info) => {
console.log("连接断开", info);
});
读取实体
连接建立、初始同步完成后,你就能读取服务端同步过来的实体了。
实体从哪来
你不需要手动创建实体。服务端会通过 StateSync 自动把你视野范围内的实体推送给客户端。你只需要用 Token 去"查"它们。
get 和 require
import { client } from "@flexcore/client";
import { PlayerClientToken } from "./generated/client/client.generated";
// 方式一:get——找不到返回 null
const player = client.world.entities.get(PlayerClientToken, "1001");
if (player) {
console.log(player.name); // 读取字段
}
// 方式二:require——找不到抛异常
const target = client.world.entities.require(PlayerClientToken, "1001");
console.log(target.name);
两者区别:
| 方法 | 找不到时 | 什么时候用 |
|---|---|---|
get | 返回 null | 不确定实体在不在视野内 |
require | 抛 ClientReplicaError | 确定实体一定存在,找不到说明出 bug 了 |
⚠️ 实体 ID 是字符串形式的正整数(如 "1001"),不是数字。
实体是只读的
客户端拿到的实体是只读视图(Replica)——你不能修改它的字段:
player.name = "Bob"; // ❌ 会抛 client_replica_readonly 错误
想改?发 RPC 请求让服务端改(之前讲过了)。客户端永远不能直接改服务端数据。
观察变化
光读取当前值不够——你需要知道什么时候值变了。用 observe():
// 订阅玩家血量变化
const sub = player.observe(
(value) => value.hp, // 关心哪个字段
(newHp, oldHp) => { // 变了就触发
console.log(`HP: ${oldHp} → ${newHp}`);
updateHpBar(newHp); // 刷新画面
},
{
emitCurrent: true, // 注册时立即触发一次当前值
},
);
// 不再需要时取消订阅
sub.dispose();
observe() 做了三件事:
- 选择关注的字段——只有这个字段变了才触发
- 变化时执行回调——给你新值和旧值
- 返回一个 Disposable,
dispose()后不再触发
💡 emitCurrent: true 很有用——注册时立刻用当前值触发一次回调,省得你额外写一行"先手动读一次"的代码。
Replica 的生命周期
实体不是永远都在的。玩家走远了、切换地图了、断线了——对应的 Replica 会进入不同的生命周期状态:
| 状态 | 含义 | 还能读字段吗 |
|---|---|---|
live | 正常,数据是最新的 | ✅ |
stale | 数据可能过时(类型漂移) | ❌ 会抛 client_replica_stale |
removed | 实体被销毁了 | ❌ 会抛 client_replica_removed |
baseline_replaced | 全量基线替换(重连/换地图) | ❌ 会抛 client_replica_baseline_replaced |
world_closed | 世界视图关闭了 | ❌ 会抛 client_replica_world_closed |
生命周期是单向不可逆的——一旦离开 live,就回不去了。
你可以通过 player.lifecycle 读取当前状态:
if (player.lifecycle === "live") {
// 安全读取
console.log(player.hp);
}
⚠️ 进入非 live 状态后,observe 注册的回调不会再触发,之前返回的 Disposable 也会自动失效。
断线与重连
断线时,引擎会派发 connection:closed 事件。你需要处理这种情况——给玩家一个提示,或者尝试重连。
events.on("connection:closed", (info) => {
showReconnectDialog();
});
FlexCore 的重连策略很简单:重新走一遍认证流程。一次性 Ticket 不应复用。按当前认证会话取得新 Ticket;下例仅演示重新登录,项目可使用 SDK 提供的 Ticket 刷新能力。
// 重连:重新登录拿新 Ticket
async function reconnect() {
const login = await auth.login({ account, password });
client.connect(
login.gameServer.host,
login.gameServer.port,
{
transport: login.gameServer.transport,
credential: login.gameTicket, // 新 Ticket
gameServer: login.gameServer, // 保留认证服务返回的可信游戏服身份
},
);
}
重连成功后,服务端会重新推送初始状态(全量基线),旧 Replica 失效;新的全量基线创建新的 live 视图,旧对象不会重新变为 live。
完整示例
下面是可复用、可类型检查的连接函数。playerToken 必须由项目实际 Schema 生成,myEntityId 必须来自已绑定的玩家身份;由调用方提供界面回调。它不制造 Token 或猜测玩家身份。先注册事件再连接,返回函数用于退出时清理本次订阅。
import { createAuthClient } from "@flexcore/auth-client";
import type { AuthClientConfig } from "@flexcore/auth-client";
import { client, events } from "@flexcore/client";
import type { ClientEntityToken, ClientDisposable } from "@flexcore/client";
export async function connectPlayer(
config: AuthClientConfig,
credentials: { account: string; password: string },
playerToken: ClientEntityToken<{ readonly hp: number }>,
myEntityId: string,
updateHpBar: (hp: number) => void,
showReconnectDialog: () => void,
) {
// 1. 登录认证服务,使用项目配置的 realm/title/environment。
const auth = createAuthClient(config);
const login = await auth.login(credentials);
let healthSub: ClientDisposable | undefined;
// 2. 注册初始同步回调,每次新基线重新获取实体。
const readySub = events.on("world:ready", () => {
healthSub?.dispose();
const me = client.world.entities.get(playerToken, myEntityId);
healthSub = me?.observe(v => v.hp, hp => updateHpBar(hp), { emitCurrent: true });
});
// 3. 注册断线回调。
const closedSub = events.on("connection:closed", () => {
healthSub?.dispose();
showReconnectDialog();
});
const dispose = () => {
healthSub?.dispose(); readySub.dispose(); closedSub.dispose();
};
// 4. 连接游戏服,保留完整可信身份。
try {
client.connect(login.gameServer.host, login.gameServer.port, {
transport: login.gameServer.transport,
credential: login.gameTicket,
gameServer: login.gameServer,
});
} catch (error) {
dispose();
throw error;
}
return dispose;
}
常见问题
为什么 get 返回 null?
两种可能:
- 实体不在你的视野范围内——AOI(兴趣区域)机制只同步你附近的实体。走远了就看不到了。
- 初始同步还没完成——等
world:ready事件后再读取。
transport 选 tcp 还是 websocket?
- TCP:延迟更低,适合 PC 客户端、移动原生客户端
- WebSocket:能穿透更多防火墙,适合 Web 浏览器客户端
两种传输方式在协议层面完全一致,不需要改业务代码。
为什么不把认证和连接合并成一步?
分离认证和游戏连接有两个好处:
- 安全隔离——认证服务不碰游戏数据,游戏服不存密码。即使游戏服被攻破,玩家密码也不会泄露。
- 灵活调度——认证服务可以根据负载情况,把玩家分配到不同的游戏服。客户端拿到哪个游戏服地址,就连哪个。
回头看
客户端从"断开"到"在线"的完整链路:
登录认证服务 → 拿到 Ticket → 连接游戏服 → 安全握手 → Ticket 验证 → 初始同步 → 读取实体 → observe 变化
你现在已经认识了客户端开发的全部核心流程。后面的章节会讲更具体的能力:AOI 视野管理、地图切换、表现层优化……