Skip to content

从 0.10 版本迁移至 0.11 版本

0.11 版本对匹配和可扩展性进行了优化,且在客户端和服务端均有重大变更.

客户端

client.id 已移除.

若您仍在客户端使用 client.id,则应替换为room.sessionId.

客户端已可使用新的匹配方式!

客户端已增加了若干可明确创建或加入房间的方法.

  • joinOrCreate(roomName, options) - 通过命名来加入或创建房间 (原先是 join())
  • create(roomName, options) - 仅创建新房间
  • join(roomName, options) - 仅通过命名加入现有房间
  • joinById(roomId, options) - 仅通过 ID 加入现有房间
  • reconnect(roomId, sessionId) - 重建丢失的连接 (原先是 rejoin())

同时, 客户端不会即时返回 Room 实例. 而是返回一个约定,在 onJoin() 成功执行后实现.

用新的 client.joinOrCreate() 替换您现有的 client.join() 调用:

client.joinOrCreate("battle", {/* options */}).then(room => {
  console.log("joined successfully", room);
}).catch(e => {
  console.error("join error", e);
});
try {
  Room<YourStateClass> room = await client.JoinOrCreate<YourStateClass>("battle", /* Dictionary of options */);
  Debug.Log("joined successfully");

} catch (ex) {
  Debug.Log("join error");
  Debug.Log(ex.Message);
}
client:join_or_create("battle", {--[[options]]}, function(err, room)
  if (err ~= nil) then
    print("join error: " .. err)
    return
  end

  print("joined successfully")
end)
client.joinOrCreate("battle", [/* options */], YourStateClass, function(err, room) {
  if (err != null) {
    trace("join error: " + err);
    return;
  }

  trace("joined successfully");
});
client->joinOrCreate<YourStateClass>("battle", {/* options */}, [=](std::string err, Room<State>* room) {
  if (err != "") {
    std::cout << "join error: " << err << std::endl;
    return;
  }

  std::cout << "joined successfully" << std::endl;
});

Lua, Haxe and C++

在不提供立即可用的 async 机制的语言中, 回调应作为匹配函数的最后一个参数. onJoin() 成功执行后则执行回调.

客户端不再需要room.onJoin.

oom.onJoin 目前仅为内部使用.约定(或回档)完成 room 示例的返回时,客户端则成功加入房间.

现在 reconnect() 需要匹配的是房间ID而不是房间名字.

原先使用的 rejoin() 可接收房间 name 和会话 ID 信息.现在换成 reconnect() 后,您需传递的信息就是房间名字而不是房间id了:

typescript client.reconnect(roomId, sessionId).then(room => {/* ... */});

JavaScript/TypeScript:JavaScript/TypeScript:

房间信号为 onLeave, onStateChange, onMessageonError.

  • 使用onStateChange(callback) 替代 onStateChange.add(callback)
  • 使用 onStateChange.once(callback) 替代 onStateChange.addOnce(callback)

C#/Unity

sender 对象已从所有 Schema 回调和事件中移除.

Schema 回调 API 略有变更

  • 使用 players.OnAdd += (Player player, string key) => {}.
  • 使用 players.OnRemove += (Player player, string key) => {}.
  • ... 等等!

事件 API 略有变更.

这些事件包括 onLeave, onStateChange, onMessageonError.

  • 现已不再需要使用 client.Connect(), room.ReadyToConnect(), room.Connect()client.Recv().
  • 使用 onStateChange += (State state, bool isFirstState) => {} 替代 onStateChange += (sender, e) => {}
  • 使用 onMessage += (object message) => {} 替代onMessage += (sender, e) => {}.
  • 使用 onLeave += (int code) => {} 替代 onLeave += (sender, e) => {}.
  • 使用 onError += (string message) => {} 替代 onError += (sender, e) => {}.

arraySchema.GetItems() 现在返回的是 Dictionary<int, MySchemaType>, 而不是 List<MySchemaType>. 所有 (List<MySchemaType>) state.myArraySchema.GetItems() 均替换为 ((Dictionary<int, MySchemaType>) state.myArraySchema.GetItems()).Values.ToList().

服务器端

express 用法

创建 Colyseus.Server 实例前,您需要:

  • 使用 express.json() 中间件
  • 使用 cors()中间件(若您正从不同的端口或域名对服务器/客户端进行测试)
  • serverexpress 传达给 Colyseus.Server构造函数.
import http from "http";
import express from "express";
import cors from "cors";
import { Server } from "colyseus";

const app = express();

app.use(cors());
app.use(express.json());

const server = http.createServer(app);
const gameServer = new Server({
  server: server
});
const http = require("http");
const express = require("express");
const cors = require("cors");
const colyseus = require("colyseus");

const app = express();

app.use(cors());
app.use(express.json());

const server = http.createServer(app);
const gameServer = new colyseus.Server({
  server: server
});

gameServer.register 已重命名为 gameServer.define

onInit(options) 已重命名为 onCreate(options)

将您房间中的 onInit(options) 方法替换为 onCreate(options).

onAuth(options) 现在改为 onAuth(client, options)

将您房间中的 onAuth(options) 方法替换为 onAuth(client, options).

client.id 现在改为 client.sessionId

client.id 已从客户端上移除,它现在被重命名为 client.sessionId(客户端上为room.sessionId).

client.id 不作为识别唯一用户的可靠标识.若您需要用有效的方法来判断多个浏览器页面中的用户是否为同一用户,可考虑使用某种身份认证形式.@colyseus/social 中的匿名认证可以有效满足这一需求.

requestJoin() 方法已弃用.

要决定玩家是否可加入房间,您应使用房间匹配筛选器,而不是 requestJoin().

以下为 0.10 版本的 requestJoin() 使用以及如何将其转化为 0.11 版本的示例:

// version 0.10
class MyRoom extends Room {
  onInit(options) {
    this.progress = options.progress;
  }

  requestJoin(options, isNew) {
    return this.progress === options.progress;
  }
}

您可在定义房间时通过定义 progress 筛选器来执行同一动作. requestJoin() 应移除.

// version 0.11
gameServer
  .define("dungeon", DungeonRoom)
  .filterBy(['progress']);

避免在 onJoin()onAuth() 中使用 this.clients

只有onJoin() 完成后, client 示例才会自动添加至 this.clients列表.

如果您有一段这样的代码:

onJoin(client, options) {
  if (this.clients.length === 2) {
    // do something!
  }
}

我们推荐您用其他代码替代, 比如:

onJoin(client, options) {
  this.state.players[client.sessionId] = new Player(/*...*/);
  if (Object.keys(this.state.players).length === 2) {
    // do something!
  }
}

onLeave(client, options) {
  delete this.state.players[client.sessionId];
}

Back to top