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