Macro-driven Observability Layer for Colyseus Haxe Client

[serjek]

Idea: Macro-Driven Observability Layer for Colyseus Haxe Client

Summary

Introduce an optional observability layer for the Colyseus Haxe client that automatically converts Colyseus Schema objects into reactive, observable client models using compile-time macros.

The goal is to eliminate manual callback wiring, drastically reduce complexity when working with nested schemas, and provide a declarative, reactive API on top of Colyseus’ low-level callback system.

---

Problem Statement

Colyseus schemas expose state changes via callbacks such as:

• onChange
• listen
• onAdd
• onRemove

While flexible, this approach becomes hard to scale on the client when:

• Schemas are deeply nested
• Collections contain other schemas
• UI requires fine-grained reactivity
• State must be mirrored into client-side models

Typical client code ends up with:

• Large amounts of boilerplate
• Manual listener management
• Repeated rebuild logic for arrays and maps
• Fragile lifecycle handling for nested schemas

---

Proposed Solution

A macro-driven observability layer that:

1. Analyzes Colyseus schemas at compile time
2. Generates observable client-side models
3. Automatically wires Colyseus callbacks
4. Exposes state via reactive primitives

All logic is generated at compile time — no runtime reflection.

---

Key Features

1. Automatic Model Generation

Given a Colyseus Schema, macros generate a corresponding observable model:

• Primitive fields → State<T>
• Nested schemas → nested observable structs
• Arrays / Maps → ObservableArray / ObservableMap
• Serialized fields → automatically parsed

No manual mapping or glue code required.

---

2. Declarative Reactivity

Consumers interact with:

• Observable fields
• Observable collections
• Stable object graphs

Instead of manually managing:

• onChange
• listen
• onAdd / onRemove
• Deeply nested callback chains

---

3. Macro-Generated Wiring

Macros generate deterministic, optimized wiring code:

• One onChange per collection
• Centralized rebuild logic
• Correct handling of nested schemas
• No container replacement (stable identity)

Callback complexity is fully hidden from the user.

---

4. Zero Runtime Overhead

• No reflection
• No dynamic field access
• No runtime schema inspection

All logic is expanded at compile time.

---

Example (Conceptual)

@:build(SchemaObserve.build())
class GameState extends Schema {
	@:type("string")
	public var phase:String;

	@:type("array", Player)
	public var players:ArraySchema<Player>;
}

Generated observable model (conceptually):

{
	phase: State<String>,
	players: ObservableArray<{
		id: State<String>,
		score: State<Int>
	}>
}

All Colyseus listeners are generated and wired automatically.

---

Advantages and Trade-offs

Pros

• Strong reactivity without manual code
• Significant reduction in Colyseus callback complexity
• Safe handling of deeply nested schemas
• Compile-time guarantees
• No runtime cost
• Clear separation between network schema and UI state
• Particularly useful for UI-heavy clients (games, dashboards)

Cons

• Additional dependencies
• Generated code can be verbose or redundant
• Debugging requires inspecting generated output
• Slightly increased compile times
• Macro implementation complexity

These trade-offs are acceptable for medium-to-large or long-lived projects.

---

Required Dependencies

Dependency stack:

• tink_state (observable primitives)
• tink_json (optional, Serialized<T> support)
• tink_core

---

Target Use Cases

• Game clients with complex UI state
• Applications with deeply nested Colyseus schemas
• Projects suffering from callback sprawl
• Teams wanting declarative, reactive client-side state

---

Non-Goals

• Replacing Colyseus core APIs
• Changing server-side schemas
• Introducing runtime reflection
• Enforcing a specific UI framework

---

Open Questions

• Should this live in the colyseus-haxe repo or as a companion library?
• How configurable should the macro generation be?
• Edge cases handling? Prototype is completely missing tests, as it currently covers creators needs.

---

Conclusion

A macro-driven observability layer can significantly improve developer experience for Haxe Colyseus clients by shifting complexity from runtime to compile time.

It leverages Haxe’s strengths - macros, typing, and code generation - to transform Colyseus’ low-level callbacks into a high-level reactive model, without sacrificing performance.

[endel]

Hi @serjek, can this be optional / add-on? We can incorporate it into the SDK itself but I wouldn't feel comfortable maintaining such complex macro systems after it gets merged

[serjek]

Hey @endel! Yeah, this is completely optional feature, user can annotate a class with build macro or skip it completely and manage callbacks on their own. My current implementation looks like this (simplified):

final matchObservables:MatchSchemaObservables = new MatchSchemaObservables();

client.joinOrCreate(
	MATCH,
	new ClientOptions({ ... }),
	MatchSchema,
	(err, room) -> {
		...
		matchObservables.listen(room);
	}
);

@:build(ObservableSchemaMacro.build(MatchSchema))
class MatchSchemaObservables {
	private var room:Room<MatchSchema>;
	private var cb:SchemaCallbacks<MatchSchema>;
	private var link:CallbackLink;

	public function listen(room:Room<MatchSchema>) {
		this.room = room;
		cb = Callbacks.get(room);
		link = SchemaListenMacro.listenRef(cb, room.state);
	}

	public function dispose() {
		link.cancel();
	}
}

Generated code. Note that schema is not touched, all macro output is generated in separate class that user has to create manually:

package ru.smartpref.ui.colyseus.match;
class MatchSchemaDebug {
	private var room : Room<MatchSchema>;
	private var cb : SchemaCallbacks<MatchSchema>;
	private var link : CallbackLink;
	public function listen(room:Room<MatchSchema>) {
		this.room = room;
		cb = Callbacks.get(room);
		link = SchemaListenMacro.listenRef(cb, room.state);
	}
	public function dispose() {
		link.cancel();
	}
	public final sides : 
		tink.state.ObservableMap<String, { 
			var rating : tink.state.State<common.api.Types.RatingData>; 
			var username : tink.state.State<String>; 
			var id : tink.state.State<Int>; 
			var isOnline : tink.state.State<Bool>;
		}> = new tink.state.ObservableMap([]);
	public final createdBy : tink.state.State<Int> = new tink.state.State(0);
	public final isStarted : tink.state.State<Bool> = new tink.state.State(false);
	public function new() { }
}

SchemaListenMacro unwraps to this:

cb.onChange(room.state, function() {
        {
                function __rebuild() {
                        for (k => _ in this.sides) this.sides.remove(k);
                        for (__k => __item in ((room.state.sides : SchemaUtils.MapType<Dynamic>))) 
						this.sides.set(__k, { 
							rating : new tink.state.State(((tink.Json.parse(__item.rating) : common.api.Types.RatingData))), 
							username : new tink.state.State(__item.username), 
							id : new tink.state.State(__item.id), 
							isOnline : new tink.state.State(__item.isOnline) 
						});
                	};
                __rebuild();
                cb.onChange(room.state.sides, __rebuild);
        };
        this.createdBy.set(room.state.createdBy);
        this.isStarted.set(room.state.isStarted);
})

Note the tink.Json.parse - this is built-in support for Serialized<T> schema type field, that is also optional:

@:keep
class MatchSchema extends Schema {
	@:type("map", MatchUserSchema)
	public var sides:MapSchema<MatchUserSchema> = new MapSchema();

	@:type("number")
	public var createdBy:Int;

	@:type("boolean")
	public var isStarted:Bool;
}

@:keep
class MatchUserSchema extends Schema {
	@:type("string")
	public var rating:Serialized<RatingData>;

	@:type("string")
	public var username:String = "";

	@:type("number")
	public var id:Int = 0;

	@:type("boolean")
	public var isOnline:Bool = false;
}

[serjek]

In fact i noticed that inner map members will not update with current approach, but it's still WIP, and eventually will get to work. I will create a separate repo for that, and then we could reference it somewhere, perhaps in deps of colyseus-haxe project with a new example targeting pure nodejs (so that RN and web devs could use it as drop in).

[endel]

No worries! Remember you have write access to the colyseus-haxe repo - if you'd like to create a branch to experiment there feel free to do so. We could maybe have a io.colyseus.macros namespace with this stuff!

[serjek]

So, here is the PR - colyseus/colyseus-haxe#71
Note even though it lacks unit tests and is more like a draft for future contributions, it's still quite solid and could cover 95% of regular developer needs. Take your time in reviewing it, I'm curious about a feedback!