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

学习与实践

文档中心

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

连接游戏和读取状态

代码说明:运行完整示例前,先准备本页说明的项目配置、场景或协议。局部用法中的 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 视野管理、地图切换、表现层优化……

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

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

Powered by Discuz! X5.0

© 2001-2026 Discuz! Team.

返回顶部