Version 0.17 is out! 🎉 - Read the migration guide and upgrade your projects.
Getting StartedHaxe Haxe

Haxe

You’re encouraged to use this SDK along with any Haxe Game Engine, such as: OpenFL, Kha, HaxeFlixel, Heaps, HaxePunk, etc.

Install package

Install colyseus from haxelib:

Terminal
haxelib install colyseus

SDK Example Project

The colyseus-hx repository contains an example project that can be compiled to html5, neko, cpp, ios, etc.

Compiling the example project to html5

Terminal
git clone https://github.com/colyseus/colyseus-hx.git
cd colyseus-hx/example/openfl
 
# Install haxelib dependencies
haxelib install openfl
haxelib install lime
haxelib install tink_http
haxelib install tink_await
haxelib install swf
haxelib install colyseus-websocket
 
# Compile the project
haxelib run lime test project.xml html5

Running the test server locally

To run the test server locally, you will need to run the following commands in your terminal:

Terminal
git clone https://github.com/colyseus/sdks-test-server
cd sdks-test-server
npm install
npm start

You can see the source code for the test server here.

You should be able to see the server running at http://localhost:2567, and the example project will be able to connect to it.

Quick Example

This example shows how to connect to a room, listen for state changes, and send messages.

import io.colyseus.Client;
import io.colyseus.Room;
import io.colyseus.serializer.schema.Callbacks;
 
class NetworkManager {
    var client:Client;
    var room:Room<Dynamic>;
 
    public function new() {
        client = new Client("ws://localhost:2567");
 
        client.joinOrCreate("my_room", [], Dynamic, function(err, room) {
            if (err != null) {
                trace("JOIN ERROR: " + err);
                return;
            }
 
            this.room = room;
            trace("Joined room: " + room.id);
 
            // Get state callbacks handler
            var callbacks = Callbacks.get(room);
 
            // Listen for changes on a state property
            callbacks.listen("currentTurn", function(currentValue, previousValue) {
                trace("Turn changed: " + previousValue + " -> " + currentValue);
            });
 
            // Listen for players being added
            callbacks.onAdd("players", function(player, sessionId) {
                trace("Player joined: " + sessionId);
 
                callbacks.listen(player, "hp", function(currentHp, previousHp) {
                    trace("Player " + sessionId + " hp: " + currentHp);
                });
            });
 
            // Listen for players being removed
            callbacks.onRemove("players", function(player, sessionId) {
                trace("Player left: " + sessionId);
            });
 
            // Send a message to the server
            room.send("move", {x: 10, y: 20});
 
            // Listen for messages from the server
            room.onMessage("chat", function(message) {
                trace("Chat: " + message);
            });
 
            room.onLeave = function(code) {
                trace("Left room: " + code);
            };
        });
    }
}

SDK API

Navigate to the Client SDK for API Reference, and select the Haxe tab.

State Schema Codegen

For compiled languages like Haxe, you need to generate client-side schema classes that match your server’s state structure. Run the following command from your server directory:

Terminal
npx schema-codegen src/rooms/schema/* --haxe --output ../src/schema/

See the full State Schema Codegen documentation for more options and details.

Reactive Schema Tools

The SDK ships with Haxe macros that turn generated schema classes into reactive tink.state observables — no manual listeners required.

Dependencies – add to your .hxml:

-lib tink_state
-lib tink_macro
-lib tink_json   # optional, for serialised string fields

ObservableSchemaMacro — generates a typed State<T> field for every property of a schema class:

@:build(io.colyseus.tools.ObservableSchemaMacro.build(MyRoomState))
class MyRoomObservable {
    private static var link:CallbackLink;
    public function listen(room:Room<MyRoomState>)
        link = SchemaListenMacro.listenRef(Callbacks.get(room), room.state);
    public function dispose() link.cancel();
}

SchemaListenMacro — wires schema listen / onAdd / onRemove callbacks to the observable fields generated above. It handles primitives, nested schemas, ArraySchema, and MapSchema recursively.

Using observables — after calling observables.listen(room):

// React to any change across all players
Observable.autorun(() -> for (player in observables.players) {
    trace('x=${player.x.value} y=${player.y.value}');
    trace('items: ${player.items.toArray()}');
});
 
// Bind to a single field
observables.currentTurn.observe().bind(x -> trace('Turn: $x'));

Enable -D debug_macro to write the generated code to GameSchemaDebug.hx / ListenDebug.hx for inspection. See the full example in colyseus-hx/example/tools.

ios target caveats

You may need to manually apply this patch in order to compile for iOS: HaxeFoundation/hxcpp@5f63d23

More info: http://community.openfl.org/t/solved-system-not-available-on-ios-with-xcode-9-0/9683?source_topic_id=10046

Next Steps

Cocos Creator Cocos CreatorDiscord Discord Activity