快速上手多人游戏服务器开发。后续会基于

Google Agones

K8S

系列

• ColyseusJS 轻量级多人游戏服务器开发框架 - 中文手册（上）
• ColyseusJS 轻量级多人游戏服务器开发框架 - 中文手册（中）

状态处理

在

Colyseus

room handlers

stateful

序列化方法

• Schema

  (default)

状态同步时

• 当

  user

  成功加入

  room

  后，他将从服务器接收到完整状态。
• 在每个

  patchRate

  处，状态的二进制补丁会发送到每个客户端（默认值为

  50ms

  ）
• 从服务器接收到每个补丁后，在客户端调用

  onStateChange

  。
• 每种序列化方法都有自己处理传入状态补丁的特殊方式。

Schema

SchemaSerializer

Colyseus 0.10

Schema

Schema

服务端

要使用

SchemaSerializer

• 有一个扩展

  Schema

  类的状态类
• 用

  @type()

  装饰器注释你所有的可同步属性
• 为您的房间实例化状态(

  this.setState(new MyState())

  )

import { Schema, type } from "@colyseus/schema";

class MyState extends Schema {
@type("string")
currentTurn: string;
}

原始类型

这些是您可以为

@type()

如果您确切地知道

number

"number"

"string"

4294967295

"number"

int

float

0

18446744073709551615

"boolean"

true

false

0

1

"int8"

-128

127

"uint8"

0

255

"int16"

-32768

32767

"uint16"

0

65535

"int32"

-2147483648

2147483647

"uint32"

0

4294967295

"int64"

-9223372036854775808

9223372036854775807

"uint64"

0

18446744073709551615

"float32"

-3.40282347e+38

3.40282347e+38

"float64"

-1.7976931348623157e+308

1.7976931348623157e+308

子 schema 属性

您可以在 "root" 状态定义中定义更多自定义数据类型，如直接引用(

direct reference

map

array

import { Schema, type } from "@colyseus/schema";

class World extends Schema {
@type("number")
width: number;

@type("number")
height: number;

@type("number")
items: number = 10;
}

class MyState extends Schema {
@type(World)
world: World = new World();
}

ArraySchema

ArraySchema

JavaScript

可以从数组中使用更多的方法。看看数组的 MDN 文档。

示例：自定义

Schema

import { Schema, ArraySchema, type } from "@colyseus/schema";

class Block extends Schema {
@type("number")
x: number;

@type("number")
y: number;
}

class MyState extends Schema {
@type([ Block ])
blocks = new ArraySchema<Block>();
}

示例：基本类型的数组

您不能在数组内混合类型。

import { Schema, ArraySchema, type } from "@colyseus/schema";

class MyState extends Schema {
@type([ "string" ])
animals = new ArraySchema<string>();
}

array.push()

在数组的末尾添加一个或多个元素，并返回该数组的新长度。

const animals = new ArraySchema<string>();
animals.push("pigs", "goats");
animals.push("sheeps");
animals.push("cows");
// output: 4

array.pop()

从数组中删除最后一个元素并返回该元素。此方法更改数组的长度。

animals.pop();
// output: "cows"

animals.length
// output: 3

array.shift()

从数组中删除第一个元素并返回被删除的元素。这个方法改变数组的长度。

animals.shift();
// output: "pigs"

animals.length
// output: 2

array.unshift()

将一个或多个元素添加到数组的开头，并返回数组的新长度。

animals.unshift("pigeon");
// output: 3

array.indexOf()

返回给定元素在数组中的第一个下标，如果不存在则返回

-1

const itemIndex = animals.indexOf("sheeps");

array.splice()

通过删除或替换现有元素和/或在适当位置添加新元素来更改数组的内容。

// find the index of the item you'd like to remove
const itemIndex = animals.findIndex((animal) => animal === "sheeps");

// remove it!
animals.splice(itemIndex, 1);

array.forEach()

迭代数组中的每个元素。

this.state.array1 = new ArraySchema<string>('a', 'b', 'c');

this.state.array1.forEach(element => {
console.log(element);
});
// output: "a"
// output: "b"
// output: "c"

MapSchema

MapSchema

建议使用

Maps

ID

entities

players

enemies

"目前仅支持字符串 key"：目前，

MapSchema

key

string

import { Schema, MapSchema, type } from "@colyseus/schema";

class Player extends Schema {
@type("number")
x: number;

@type("number")
y: number;
}

class MyState extends Schema {
@type({ map: Player })
players = new MapSchema<Player>();
}

map.get()

通过

key

map

const map = new MapSchema<string>();
const item = map.get("key");

OR

//
// NOT RECOMMENDED
//
// This is a compatibility layer with previous versions of @colyseus/schema
// This is going to be deprecated in the future.
//
const item = map["key"];

map.set()

按

key

map

const map = new MapSchema<string>();
map.set("key", "value");

OR

//
// NOT RECOMMENDED
//
// This is a compatibility layer with previous versions of @colyseus/schema
// This is going to be deprecated in the future.
//
map["key"] = "value";

map.delete()

按

key

map

map.delete("key");

OR

//
// NOT RECOMMENDED
//
// This is a compatibility layer with previous versions of @colyseus/schema
// This is going to be deprecated in the future.
//
delete map["key"];

map.size

返回

MapSchema

const map = new MapSchema<number>();
map.set("one", 1);
map.set("two", 2);

console.log(map.size);
// output: 2

map.forEach()

按插入顺序遍历

map

key/value

this.state.players.forEach((value, key) => {
console.log("key =>", key)
console.log("value =>", value)
});

"所有 Map 方法"：您可以从 Maps 中使用更多的方法。看一看 MDN 文档的 Maps。

CollectionSchema

"

CollectionSchema

CollectionSchema

JavaScript

Haxe

c#

LUA

c++

CollectionSchema

ArraySchema

import { Schema, CollectionSchema, type } from "@colyseus/schema";

class Item extends Schema {
@type("number")
damage: number;
}

class Player extends Schema {
@type({ collection: Item })
items = new CollectionSchema<Item>();
}

collection.add()

将

item

CollectionSchema

const collection = new CollectionSchema<number>();
collection.add(1);
collection.add(2);
collection.add(3);

collection.at()

获取位于指定

index

item

const collection = new CollectionSchema<string>();
collection.add("one");
collection.add("two");
collection.add("three");

collection.at(1);
// output: "two"

collection.delete()

根据

item

item

collection.delete("three");

collection.has()

返回一个布尔值，无论该

item

set

if (collection.has("two")) {
console.log("Exists!");
} else {
console.log("Does not exist!");
}

collection.size

返回

CollectionSchema

const collection = new CollectionSchema<number>();
collection.add(10);
collection.add(20);
collection.add(30);

console.log(collection.size);
// output: 3

collection.forEach()

对于

CollectionSchema

index/value

forEach()

collection.forEach((value, at) => {
console.log("at =>", at)
console.log("value =>", value)
});

SetSchema

"

SetSchema

SetSchema

JavaScript

Haxe

C#

LUA

C++

SetSchema

"更多"：你可以从

Sets

SetSchema

CollectionSchema

Sets

Sets

import { Schema, SetSchema, type } from "@colyseus/schema";

class Effect extends Schema {
@type("number")
radius: number;
}

class Player extends Schema {
@type({ set: Effect })
effects = new SetSchema<Effect>();
}

set.add()

向

SetSchema

item

const set = new CollectionSchema<number>();
set.add(1);
set.add(2);
set.add(3);

set.at()

获取位于指定

index

const set = new CollectionSchema<string>();
set.add("one");
set.add("two");
set.add("three");

set.at(1);
// output: "two"

set.delete()

根据项的值删除项。

set.delete("three");

set.has()

返回一个布尔值，无论该项是否存在于集合中。

if (set.has("two")) {
console.log("Exists!");
} else {
console.log("Does not exist!");
}

set.size

返回

SetSchema

const set = new SetSchema<number>();
set.add(10);
set.add(20);
set.add(30);

console.log(set.size);
// output: 3

过滤每个客户端的数据

"这个特性是实验性的"：

@filter()

@filterChildren()

过滤旨在为特定客户端隐藏状态的某些部分，以避免在玩家决定检查来自网络的数据并查看未过滤状态信息的情况下作弊。

数据过滤器是每个客户端和每个字段(或每个子结构，在

@filterChildren

true

请注意，如果过滤函数的依赖关系发生变化，它不会自动重新运行，但只有在过滤字段(或其子字段)被更新时才会重新运行。请参阅此问题以了解解决方法。

@filter()

property decorator

@filter()

下面是

@filter()

class State extends Schema {
@filter(function(client, value, root) {
// client is:
//
// the current client that's going to receive this data. you may use its
// client.sessionId, or other information to decide whether this value is
// going to be synched or not.

// value is:
// the value of the field @filter() is being applied to

// root is:
// the root instance of your room state. you may use it to access other
// structures in the process of decision whether this value is going to be
// synched or not.
})
@type("string") field: string;
}

@filterChildren()

属性装饰器

@filterChildren()

arrays

maps

sets

@filter()

value

key

ArraySchema

MapSchema

CollectionSchema

class State extends Schema {
@filterChildren(function(client, key, value, root) {
// client is:
//
// the current client that's going to receive this data. you may use its
// client.sessionId, or other information to decide whether this value is
// going to be synched or not.

// key is:
// the key of the current value inside the structure

// value is:
// the current value inside the structure

// root is:
// the root instance of your room state. you may use it to access other
// structures in the process of decision whether this value is going to be
// synched or not.
})
@type([Cards]) cards = new ArraySchema<Card>();
}

例子： 在一场纸牌游戏中，每张纸牌的相关资料只应供纸牌拥有者使用，或在某些情况下(例如纸牌已被丢弃)才可使用。

查看

@filter()

import { Client } from "colyseus";

class Card extends Schema {
@type("string") owner: string; // contains the sessionId of Card owner
@type("boolean") discarded: boolean = false;

/**
* DO NOT USE ARROW FUNCTION INSIDE `@filter`
* (IT WILL FORCE A DIFFERENT `this` SCOPE)
*/
@filter(function(
this: Card, // the instance of the class `@filter` has been defined (instance of `Card`)
client: Client, // the Room's `client` instance which this data is going to be filtered to
value: Card['number'], // the value of the field to be filtered. (value of `number` field)
root: Schema // the root state Schema instance
) {
return this.discarded || this.owner === client.sessionId;
})
@type("uint8") number: number;
}

向后/向前兼容性

向后/向前兼容性可以通过在现有结构的末尾声明新的字段来实现，以前的声明不被删除，但在需要时被标记为

@deprecated()

这对于原生编译的目标特别有用，比如 C#, C++, Haxe 等 — 在这些目标中，客户端可能没有最新版本的 schema 定义。

限制和最佳实践

• 每个

  Schema

  结构最多可以容纳

  64

  个字段。如果需要更多字段，请使用嵌套的

  Schema

  结构。

• NaN

  或

  null

  数字被编码为

  0

• null

  字符串被编码为

  ""

• Infinity

  被编码为

  Number.MAX_SAFE_INTEGER

  的数字。
• 不支持多维数组。了解如何将一维数组用作多维数组

• Arrays

  和

  Maps

  中的项必须都是同一类型的实例。

• @colyseus/schema

  只按照指定的顺序编码字段值。

  encoder

  (服务器)和

  decoder

  (客户端)必须有相同的

  schema

  定义。
• 字段的顺序必须相同。

客户端

Callbacks

您可以在客户端

schema

• onAdd (instance, key)

• onRemove (instance, key)

• onChange (changes)

  (on

  Schema

  instance)

• onChange (instance, key)

  (on collections:

  MapSchema

  ,

  ArraySchema

  , etc.)

• listen()

"C#, C++, Haxe"：当使用静态类型语言时，需要根据

TypeScript schema

schema

参见在客户端生成 schema

onAdd (instance, key)

onAdd

maps

MapSchema

ArraySchema

onAdd

holder

key

room.state.players.onAdd = (player, key) => {
console.log(player, "has been added at", key);

// add your player entity to the game world!

// If you want to track changes on a child object inside a map, this is a common pattern:
player.onChange = function(changes) {
changes.forEach(change => {
console.log(change.field);
console.log(change.value);
console.log(change.previousValue);
})
};

// force "onChange" to be called immediatelly
player.triggerAll();
};

onRemove (instance, key)

onRemove

MapSchema

ArraySchema

onRemove

holder

key

room.state.players.onRemove = (player, key) => {
console.log(player, "has been removed at", key);

// remove your player entity from the game world!
};

onChange (changes: DataChange[])

onChange

Schema

您可以注册

onChange

Schema

onChange

room.state.onChange = (changes) => {
changes.forEach(change => {
console.log(change.field);
console.log(change.value);
console.log(change.previousValue);
});
};

你不能在未与客户端同步的对象上注册

onChange

onChange (instance, key)

onChange

Schema

collection structures

每当 primitive 类型(

string

number

boolean

room.state.players.onChange = (player, key) => {
console.log(player, "have changes at", key);
};

如果您希望检测 non-primitive 类型(包含

Schema

onAdd

onChange

"

onChange

onAdd

onRemove

onAdd

onRemove

onChange

如果在这些步骤中还需要检测更改，请考虑注册 `onAdd` 和 `onRemove`。

.listen(prop, callback)

监听单个属性更改。

.listen()

JavaScript/TypeScript

参数:

• property

  : 您想要监听更改的属性名。

• callback

  : 当

  property

  改变时将被触发的回调。

state.listen("currentTurn", (currentValue, previousValue) => {
console.log(`currentTurn is now ${currentValue}`);
console.log(`previous value was: ${previousValue}`);
});

.listen()

const removeListener = state.listen("currentTurn", (currentValue, previousValue) => {
// ...
});

// later on, if you don't need the listener anymore, you can call `removeListener()` to stop listening for `"currentTurn"` changes.
removeListener();

listen

onChange

.listen()

onChange

state.onChange = function(changes) {
changes.forEach((change) => {
if (change.field === "currentTurn") {
console.log(`currentTurn is now ${change.value}`);
console.log(`previous value was: ${change.previousValue}`);
}
})
}

客户端 schema 生成

这只适用于使用静态类型语言(如 C#、C++ 或 Haxe)的情况。

在服务器项目中，可以运行

npx schema-codegen

schema

npx schema-codegen --help

输出:

schema-codegen [path/to/Schema.ts]

Usage (C#/Unity)
schema-codegen src/Schema.ts --output client-side/ --csharp --namespace MyGame.Schema

Valid options:
--output: fhe output directory for generated client-side schema files
--csharp: generate for C#/Unity
--cpp: generate for C++
--haxe: generate for Haxe
--ts: generate for TypeScript
--js: generate for JavaScript
--java: generate for Java

Optional:
--namespace: generate namespace on output code

Built-in room » Lobby Room

"大厅房间的客户端 API 将在 Colyseus 1.0.0 上更改"：

• 内置的大厅房间目前依赖于发送消息来通知客户可用的房间。当

  @filter()

  变得稳定时，

  LobbyRoom

  将使用

  state

  代替。

服务器端

内置的

LobbyRoom

import { LobbyRoom } from "colyseus";

// Expose the "lobby" room.
gameServer
.define("lobby", LobbyRoom);

// Expose your game room with realtime listing enabled.
gameServer
.define("your_game", YourGameRoom)
.enableRealtimeListing();

在

onCreate()

onJoin()

onLeave()

onDispose()

LobbyRoom

如果你已经更新了你房间的

metadata

lobby

updateLobby()

import { Room, updateLobby } from "colyseus";

class YourGameRoom extends Room {

onCreate() {

//
// This is just a demonstration
// on how to call `updateLobby` from your Room
//
this.clock.setTimeout(() => {

this.setMetadata({
customData: "Hello world!"
}).then(() => updateLobby(this));

}, 5000);

}

}

客户端

您需要通过从

LobbyRoom

import { Client, RoomAvailable } from "colyseus.js";

const client = new Client("ws://localhost:2567");
const lobby = await client.joinOrCreate("lobby");

let allRooms: RoomAvailable[] = [];

lobby.onMessage("rooms", (rooms) => {
allRooms = rooms;
});

lobby.onMessage("+", ([roomId, room]) => {
const roomIndex = allRooms.findIndex((room) => room.roomId === roomId);
if (roomIndex !== -1) {
allRooms[roomIndex] = room;

} else {
allRooms.push(room);
}
});

lobby.onMessage("-", (roomId) => {
allRooms = allRooms.filter((room) => room.roomId !== roomId);
});

Built-in room » Relay Room

内置的

RelayRoom

通过简单地中继消息(将消息从客户端转发给其他所有人) — 服务器端不能验证任何消息 — 客户端应该执行验证。

RelayRoom

服务器端

import { RelayRoom } from "colyseus";

// Expose your relayed room
gameServer.define("your_relayed_room", RelayRoom, {
maxClients: 4,
allowReconnectionTime: 120
});

客户端

请参阅如何注册来自

relayed room

连接到房间

import { Client } from "colyseus.js";

const client = new Client("ws://localhost:2567");

//
// Join the relayed room
//
const relay = await client.joinOrCreate("your_relayed_room", {
name: "This is my name!"
});

在玩家加入和离开时注册回调

//
// Detect when a player joined the room
//
relay.state.players.onAdd = (player, sessionId) => {
if (relay.sessionId === sessionId) {
console.log("It's me!", player.name);

} else {
console.log("It's an opponent", player.name, sessionId);
}
}

//
// Detect when a player leave the room
//
relay.state.players.onRemove = (player, sessionId) => {
console.log("Opponent left!", player, sessionId);
}

//
// Detect when the connectivity of a player has changed
// (only available if you provided `allowReconnection: true` in the server-side)
//
relay.state.players.onChange = (player, sessionId) => {
if (player.connected) {
console.log("Opponent has reconnected!", player, sessionId);

} else {
console.log("Opponent has disconnected!", player, sessionId);
}
}

发送和接收消息

//
// By sending a message, all other clients will receive it under the same name
// Messages are only sent to other connected clients, never the current one.
//
relay.send("fire", {
x: 100,
y: 200
});

//
// Register a callback for messages you're interested in from other clients.
//
relay.onMessage("fire", ([sessionId, message]) => {

//
// The `sessionId` from who sent the message
//
console.log(sessionId, "sent a message!");

//
// The actual message sent by the other client
//
console.log("fire at", message);
});

Colyseus 的最佳实践

这一部分需要改进和更多的例子！每一段都需要有自己的一页，有详尽的例子和更好的解释。

• 保持你的 room 类尽可能小，没有游戏逻辑
• 使可同步的数据结构尽可能小 理想情况下，扩展

  Schema

  的每个类应该只有字段定义。
• 自定义 getter 和 setter 方法可以实现，只要它们中没有游戏逻辑。

npm install --save @colyseus/command

room

dispatcher

import { Room } from "colyseus";
import { Dispatcher } from "@colyseus/command";

import { OnJoinCommand } from "./OnJoinCommand";

class MyRoom extends Room<YourState> {
dispatcher = new Dispatcher(this);

onCreate() {
this.setState(new YourState());
}

onJoin(client, options) {
this.dispatcher.dispatch(new OnJoinCommand(), {
sessionId: client.sessionId
});
}

onDispose() {
this.dispatcher.stop();
}
}

const colyseus = require("colyseus");
const command = require("@colyseus/command");

const OnJoinCommand = require("./OnJoinCommand");

class MyRoom extends colyseus.Room {

onCreate() {
this.dispatcher = new command.Dispatcher(this);
this.setState(new YourState());
}

onJoin(client, options) {
this.dispatcher.dispatch(new OnJoinCommand(), {
sessionId: client.sessionId
});
}

onDispose() {
this.dispatcher.stop();
}
}

// OnJoinCommand.ts
import { Command } from "@colyseus/command";

export class OnJoinCommand extends Command<YourState, {
sessionId: string
}> {

execute({ sessionId }) {
this.state.players[sessionId] = new Player();
}

}

// OnJoinCommand.js
const command = require("@colyseus/command");

exports.OnJoinCommand = class OnJoinCommand extends command.Command {

execute({ sessionId }) {
this.state.players[sessionId] = new Player();
}

}

我是为少
微信：uuhells123
公众号：黑客下午茶
加我微信（互相学习交流），关注公众号（获取更多学习资料~）