Presence API

When you need to scale your server on multiple processes and/or machines, you’d need to provide the Presence option to the Server. The purpose of Presence is to allow communicating and sharing data between different processes, specially during match-making.

LocalPresence (default)
RedisPresence

The presence instance is also available on every Room handler. You may use its API to persist data and communicate between rooms via PUB/SUB.

`LocalPresence`

This is the default option. It’s meant to be used when you’re running Colyseus in a single process.

`RedisPresence`

Use this option when you’re running Colyseus on multiple processes and/or machines.

Constructor parameters:

clientOpts: The redis client options (host/credentials). See full list of options.

app.config.ts

import config from "@colyseus/tools";
import { RedisPresence } from "@colyseus/redis-presence";
 
export default config({
    // ...
    options: {
        presence: new RedisPresence(process.env.REDIS_URI)
    },
    // ...
});

server.ts

import { Server } from "colyseus";
import { RedisPresence } from "@colyseus/redis-presence";
 
// This happens on the slave processes.
const gameServer = new Server({
    // ...
    presence: new RedisPresence(process.env.REDIS_URI)
});
 
gameServer.listen(2567);

server.js

const colyseus = require('colyseus');
const RedisPresence = require('@colyseus/redis-presence').RedisPresence;
 
// This happens on the slave processes.
const gameServer = new colyseus.Server({
    // ...
    presence: new RedisPresence(process.env.REDIS_URI)
});
 
gameServer.listen(2567);

API

The Presence API is highly based on Redis’s API, which is a key-value database.

Every Room instance has a presence property:

MyRoom.ts

export class MyRoom extends Room {
    onCreate() {
        this.presence // full Presence API is available from here
    }
}

Alternatively, you can access matchMaker.presence from anywhere, by importing the Match-maker API:

server.ts

import { matchMaker } from "colyseus";
 
matchMaker.presence // full Presence API is available from here

Subscribes to the given topic. The callback will be triggered whenever a message is published on topic.

Signature

presence.subscribe(topic: string, callback: Function)

MyRoom.ts

this.presence.subscribe("global-event", (data) => {
    console.log("received message:", data);
});

Unsubscribe

Unsubscribe from given topic.

Signature

presence.unsubscribe(topic: string, callback?: Function)

Unsubscribe from all previously subscribed “global-event” callbacks.

MyRoom.ts

//
this.presence.unsubscribe("global-event");

Publish

Posts a message to given topic.

Signature

presence.publish(topic: string, data: any)

MyRoom.ts

this.presence.publish("global-event", { any: 1, data: 2, here: "3" });

Set

Set key to hold the string value.

Signature

presence.set(key: string, value: string)

Example: Setting a "global-key" to hold "a string value".

this.presence.set("global-key", "a string value");

Set with expiration

Set key to hold the string value and set key to timeout after a given number of seconds.

Signature

presence.setex(key: string, value: string, seconds: number)

Example: Setting a "global-key" that is globally available for 2 minutes.

MyRoom.ts

this.presence.setex("global-key", "a string value", 120);

Get the value of key

Get the value of key.

Signature

presence.get(key: string)

MyRoom.ts

const globalKeyValue = await this.presence.get("global-key");

Delete the key

Removes the specified key.

Signature

presence.del(key: string): void

MyRoom.ts

await this.presence.del("global-key");

Check if key exists

Returns if key exists.

Signature

presence.exists(key: string): Promise<boolean>

MyRoom.ts

const globalKeyExists = await this.presence.exists("global-key");

Increment value of key

Increments the number stored at key by one.

Signature

presence.incr(key: string)

If the key does not exist, it is set to 0 before performing the operation.

An error is returned if the key contains a value of the wrong type or contains a string that can not be represented as integer.

This operation is limited to 64 bit signed integers.

MyRoom.ts

await this.presence.incr("global-count");
await this.presence.incr("global-count");
await this.presence.incr("global-count");
 
// get value from "global-count" key
const count = await this.presence.get("global-count");
console.log(count) // => 3

Decrement value of key

Decrements the number stored at key by one.

Signature

presence.decr(key: string)

If the key does not exist, it is set to 0 before performing the operation.

An error is returned if the key contains a value of the wrong type or contains a string that can not be represented as integer.

This operation is limited to 64 bit signed integers.

MyRoom.ts

await this.presence.decr("global-count");
await this.presence.decr("global-count");
await this.presence.decr("global-count");
 
// get value from "global-count" key
const count = await this.presence.get("global-count");
console.log(count) // => 33

Add members to a Set

Add the specified members to the set stored at key.

Signature

presence.sadd(key: string, value: any)

Specified members that are already a member of this set are ignored.

If key does not exist, a new set is created before adding the specified members.

MyRoom.ts

await this.presence.sadd("global-set1", "member-one");
await this.presence.sadd("global-set1", "member-one"); // ignored, not added
await this.presence.sadd("global-set1", "member-two");
await this.presence.sadd("global-set1", "member-three");

Get all members of a Set

Returns all the members of the set value stored at key.

Signature

presence.smembers(key: string)

MyRoom.ts

const globalSetMembers = await this.presence.del("global-set1");
console.log(globalSetMembers) // => ["member-one", "member-two", "member-three"]

Check if member is in the Set

Returns if member is a member of the set stored at key

Signature

presence.sismember(key: string, member: string): number

Return value

1 if the element is a member of the set.
0 if the element is not a member of the set, or if key does not exist.

MyRoom.ts

const isMember = await this.presence.sismember("global-set1", "member-three");
 
if (isMember) {
    console.log("member-three IS present on 'global-set1'");
 
} else {
    console.log("member-three IS NOT present on 'global-set1'");
}

Remove member(s) from a Set

Remove the specified members from the set stored at key.

Signature

presence.srem(key: string, value: any)

Specified members that are not a member of this set are ignored.

If key does not exist, it is treated as an empty set and this command returns 0.

MyRoom.ts

await this.presence.srem("global-set1", "member-three");

Get total members in Set

Returns the set number of elements (cardinality) of the set stored at key.

Signature

presence.scard(key: string)

MyRoom.ts

const cardinality = await this.presence.scard("global-set1");
console.log(cardinality) // => 2

Get intersection of Sets

Returns the members of the set resulting from the intersection of all the given sets.

Signature

presence.sinter(...keys: string[]): Promise<string[]>

MyRoom.ts

// add members to "global-set1"
await this.presence.sadd("global-set1", "member-one");
await this.presence.sadd("global-set1", "member-two");
 
// add members to "global-set2"
await this.presence.sadd("global-set2", "member-two");
await this.presence.sadd("global-set2", "member-three");
 
// get the intersection
const intersection = await this.presence.sinter("global-set1", "global-set2");
console.log(intersection); // => ["member-two"]

Set a field in a Hash

Sets field in the hash stored at key to value.

Signature

presence.hset(key: string, field: string, value: string)

If key does not exist, a new key holding a hash is created.

If field already exists in the hash, it is overwritten.

await this.presence.hset("global-hashmap1", "key1", "1");
await this.presence.hset("global-hashmap1", "key2", "2");

Increment field in a Hash

Increments the number stored at field in the hash stored at key by increment.

Signature

presence.hincrby(key: string, field: string, value: number)

If key does not exist, a new key holding a hash is created.

If field does not exist the value is set to 0 before the operation is performed.

MyRoom.ts

await this.presence.hset("global-hashmap1", "key1", "2");
const incr = await this.presence.hincrby("global-hashmap1", "key1", "5");
console.log(incr) // => "7"

Get field in a Hash

Returns the value associated with field in the hash stored at key.

Signature

presence.hget(key: string, field: string): Promise<string>

MyRoom.ts

await this.presence.hset("global-hashmap1", "key", "value");
const value = await this.presence.hget("global-hashmap1", "key");
console.log(value) // => "value"

Get all fields in a Hash

Returns all fields and values of the hash stored at key.

Signature

presence.hgetall(key: string): Promise<{ [field: string]: string }>

MyRoom.ts

await this.presence.hset("global-hashmap1", "key1", "1");
await this.presence.hset("global-hashmap1", "key2", "2");
 
const value = await this.presence.hgetall("global-hashmap1");
console.log(value) // => {"key1": "1", "key2": "2"}

Delete field in a Hash

Removes the specified field from the hash stored at key.

Signature

presence.hdel(key: string, field: string): Promise<boolean>

Returns true if removed, and false if key or field does not exist.

MyRoom.ts

await this.presence.hset("global-hashmap1", "key1", "1");
await this.presence.hset("global-hashmap1", "key2", "2");
 
// delete "key2" from "global-hashmap1".
await this.presence.hset("global-hashmap1", "key2");

Get the length of a Hash

Returns the number of fields contained in the hash stored at key

Signature

presence.hlen(key: string): Promise<number>

MyRoom.ts

await this.presence.hset("global-hashmap1", "key1", "1");
await this.presence.hset("global-hashmap1", "key2", "2");
 
// get length from "global-hashmap1".
const length = await this.presence.hlen("global-hashmap1");
console.log(length) // => 2

Last updated on February 14, 2025

Custom HTTP Routes Driver