ColyseusJS 輕量級多人遊戲服務器開發框架 – 中文手冊（上）

快速上手多人遊戲服務器開發。後續會基於 Google Agones，更新相關 K8S 運維、大規模快速擴展專用遊戲服務器的文章。擁抱☁️原生🤗 Cloud-Native！

快速開始

在開始之前，讓我們確保在您的本地機器上安裝了必要的系統需求。

系統必需：

創建一個 barebones(裸) Colyseus server

使用 npm init colyseus-app 命令生成 barebones(裸) Colyseus server。您可以選擇 TypeScript(推薦)，JavaScript 和 Haxe 作為服務器的選擇語言。

npm init colyseus-app ./my-colyseus-app

從官方的例子來看

或者，您可以通過克隆示例項目並在本地運行它來查看一些實際示例。

git clone //github.com/colyseus/colyseus-examples.git
cd colyseus-examples
npm install

要在本地運行服務器，請運行 npm start，然後打開 //localhost:2567 查看每個示例。

Colyseus 工作原理概述

Presentation: Overview of how Colyseus works

JavaScript/TypeScript SDK

JavaScript/TypeScript SDK 與大多數平台兼容：

用法

在項目中包括 JavaScript SDK

如果你正在使用一個構建工具(webpack，rollup或類似的)，這是首選的方法。

npm install --save colyseus.js

如果你不使用構建工具，建議從 GitHub Releases 下載。

<script src="colyseus.js"></script>

或者，您可以使用 unpkg 直接包括分發文件。確保用與您的服務器兼容的版本來替換其中的 @x.x.x 部分。

<script src="//unpkg.com/colyseus.js@^0.14.0/dist/colyseus.js"></script>

連接到服務器：

import * as Colyseus from "colyseus.js"; // 如果通過 <script> 標記包含，則不需要。

var client = new Colyseus.Client('ws://localhost:2567');

加入一個 room(房間):

client.joinOrCreate("room_name").then(room => {
    console.log(room.sessionId, "joined", room.name);
}).catch(e => {
    console.log("JOIN ERROR", e);
});

Room 事件

Room state(狀態) 已經被更新:

room.onStateChange((state) => {
  console.log(room.name, "has new state:", state);
});

從服務器廣播或直接廣播到此客戶端的消息：

room.onMessage("message_type", (message) => {
  console.log(client.id, "received on", room.name, message);
});

發生服務器錯誤：

room.onError((code, message) => {
  console.log(client.id, "couldn't join", room.name);
});

client 離開 room：

room.onLeave((code) => {
  console.log(client.id, "left", room.name);
});

Cocos Creator 3.0

  • 從 GitHub 下載最新的 colyseus-js-client.zip 版本。
  • 解壓 colyseus-js-client.zip 文件。
  • 將 colyseus.js 和 colyseus.d.ts 文件移到 Cocos Creator 項目的 scripts 文件夾中。
  • 單擊 Assets 面板中的 colyseus.js 文件，並啟用 “Import As Plugin”（見下圖）
  • TypeScript: 需要使用 import Colyseus from "./colyseus.js";
  • JavaScript: 需要使用 const Colyseus = require("./colyseus.js");

概述

Colyseus 目前有客戶端 SDK，可用於以下平台：

需要另一個平台的客戶端？在discussion board分享你的興趣吧!

實例化 Colyseus 客戶端

Client 實例用於執行配對調用，然後連接到一個或多個房間。

此時沒有實際的服務器端連接。

import Colyseus from "colyseus.js";
// ...

let client = new Colyseus.Client("ws://localhost:2567");

方法

joinOrCreate (roomName: string, options: any)

通過提供的 roomName 和 options 加入現有房間或創建新房間。

此方法將忽略鎖定的房間或私人房間。

try {
  const room = await client.joinOrCreate("battle", {/* options */});
  console.log("joined successfully", room);

} catch (e) {
  console.error("join error", e);
}

create (roomName: string, options: any)

通過提供的 roomName 和 options 創建新房間。

try {
  const room = await client.create("battle", {/* options */});
  console.log("joined successfully", room);

} catch (e) {
  console.error("join error", e);
}

join (roomName: string, options: any)

通過提供的 roomName 和 options 連接一個現有的房間。

此方法將忽略鎖定的房間或私人房間。

try {
  const room = await client.join("battle", {/* options */});
  console.log("joined successfully", room);

} catch (e) {
  console.error("join error", e);
}

joinById (roomId: string, options: any)

通過 roomId 加入現有房間。私人房間可以通過 id 連接。

try {
  const room = await client.joinById("KRYAKzRo2", {/* options */});
  console.log("joined successfully", room);

} catch (e) {
  console.error("join error", e);
}

使用 getAvailableRooms() 檢索可加入的 roomId 列表。

reconnect (roomId: string, sessionId: string)

將客戶端重新連接到他以前連接的房間。

必須與服務器端的 allowReconnection() 一起使用。

try {
  const room = await client.reconnect("wNHTX5qik", "SkNaHTazQ");
  console.log("joined successfully", room);

} catch (e) {
  console.error("join error", e);
}

getAvailableRooms (roomName?: string)

列出要連接的所有可用房間。鎖好的房間和私人房間不會被列出。roomName 是可選的。

client.getAvailableRooms("battle").then(rooms => {
  rooms.forEach((room) => {
    console.log(room.roomId);
    console.log(room.clients);
    console.log(room.maxClients);
    console.log(room.metadata);
  });
}).catch(e => {
  console.error(e);
});

consumeSeatReservation (reservation)

通過預訂座位加入一個房間。

“高級用法”：
請參閱Match-maker API以了解如何檢索座位預訂數據。

try {
  const room = await client.consumeSeatReservation(reservation);
  console.log("joined successfully", room);

} catch (e) {
  console.error("join error", e);
}

Room API (Client-side)

屬性

state: any

當前房間的狀態。此變量始終與服務器端的最新 state 同步。要偵聽整個狀態的更新，請參閱 onStateChange 事件。

您可以將 callbacks 附加到您 state 中的特定結構。參閱 schema callbacks。

sessionId: string

當前連接的客戶端的唯一標識符。此屬性與服務器端的 client.sessionId 匹配。

id: string

房間的唯一標識。您可以與其他客戶端共享此 id，以便允許他們直接連接到此房間。

// get `roomId` from the query string
let roomId = location.href.match(/roomId=([a-zA-Z0-9\-_]+)/)[1];

// joining a room by its id
client.joinById(roomId).then(room => {
  // ...
});

name: string

room handler 的名稱。例如："battle"。

方法

send (type, message)

向 room handler 發送一種類型的消息。消息是用 MsgPack 編碼的，可以保存任何 JSON-seriazeable(JSON可序列化)的數據結構。

//
// sending message with string type
//
room.send("move", { direction: "left"});

//
// sending message with number type
//
room.send(0, { direction: "left"});

從服務器端使用 Room#onMessage() 讀取消息。

leave ()

與房間斷開連接。

room.leave();

使用 Room#onLeave() 處理與服務器端的斷開連接。

removeAllListeners()

移除 onMessage，onStateChange，onLeave 和 onError 監聽器。

如果您使用的是 Fossil Delta 序列化程序，還將刪除所有 .listen() 調用。。

事件

onStateChange

查看 State Handling » Schema » Client-side 部分了解更多詳細信息。

此事件在服務器更新其狀態時觸發。

room.onStateChange.once((state) => {
  console.log("this is the first room state!", state);
});

room.onStateChange((state) => {
  console.log("the room state has been updated:", state);
});

onMessage

當服務器直接向客戶端或通過廣播發送消息時，會觸發此事件。

room.onMessage("powerup", (message) => {
  console.log("message received from server");
  console.log(message);
});

要將消息從服務器直接發送到客戶端，您需要使用 client.send() 或room.broadcast()

onLeave

當客戶端離開房間時觸發此事件。

可能出現的 code：

room.onLeave((code) => {
  console.log("client left the room");
});

onError

當 room handler 中發生某些錯誤時，將觸發此事件。

room.onError((code, message) => {
  console.log("oops, error ocurred:");
  console.log(message);
});

Refs

中文手冊同步更新在：

我是為少
微信：uuhells123
公眾號：黑客下午茶
加我微信（互相學習交流），關注公眾號（獲取更多學習資料~）

VirMach 便宜 VPS

QNews

QNews