Getting Started 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:

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

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:

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

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

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:

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

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'));

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

Cocos Creator Discord Activity