Events & Pub-Sub

Events are the primary communication mechanism in Multisynq applications. The publish-subscribe (pub-sub) pattern enables clean, decoupled communication between Models and Views while maintaining perfect synchronization.

Core Event API

These functions are only available to classes that inherit from Multisynq.Model or Multisynq.View.

Sends an event to all subscribers

publish(scope, event, data)

scope: Namespace for the event (String)
event: Name of the event (String)
data: Optional data payload (any serializable type)

// Example: Publishing player input
this.publish("player-123", "move", { direction: "left", speed: 5 });

Sends an event to all subscribers

publish(scope, event, data)

scope: Namespace for the event (String)
event: Name of the event (String)
data: Optional data payload (any serializable type)

// Example: Publishing player input
this.publish("player-123", "move", { direction: "left", speed: 5 });

Registers to receive events

subscribe(scope, event, handler)

scope: Namespace to listen to (String)
event: Event name to listen for (String)
handler: Function to handle the event

// Example: Subscribing to player input
this.subscribe("player-123", "move", this.handlePlayerMove);

Removes a specific subscription

unsubscribe(scope, event)

// Example: Stop listening to player input
this.unsubscribe("player-123", "move");

Removes all subscriptions

unsubscribeAll()

Called automatically when you destroy() a model or view.

Handler Requirements

Critical difference: Model and View handlers have different requirements!

Must use method names, not function expressions

// ✅ Correct - use method name
class GameModel extends Multisynq.Model {
    init() {
        this.subscribe("input", "move", this.handleMove);
    }
    
    handleMove(data) {
        // Handle the move
    }
}

// ❌ Incorrect - function expressions don't work
class GameModel extends Multisynq.Model {
    init() {
        this.subscribe("input", "move", (data) => {
            // This won't work in models!
        });
    }
}

This is because functions cannot be serialized, so only the method name is stored.

Must use method names, not function expressions

// ✅ Correct - use method name
class GameModel extends Multisynq.Model {
    init() {
        this.subscribe("input", "move", this.handleMove);
    }
    
    handleMove(data) {
        // Handle the move
    }
}

// ❌ Incorrect - function expressions don't work
class GameModel extends Multisynq.Model {
    init() {
        this.subscribe("input", "move", (data) => {
            // This won't work in models!
        });
    }
}

This is because functions cannot be serialized, so only the method name is stored.

Can use any function form

// ✅ All of these work in views
class GameView extends Multisynq.View {
    init() {
        // Method name
        this.subscribe("ui", "update", this.handleUpdate);
        
        // Arrow function
        this.subscribe("ui", "alert", (message) => {
            alert(message);
        });
        
        // Anonymous function
        this.subscribe("ui", "log", function(data) {
            console.log(data);
        });
    }
    
    handleUpdate(data) {
        // Handle the update
    }
}

Event Routing Patterns

Understanding event routing is crucial for proper Multisynq development:

Events are transmitted to the synchronizer and mirrored to all users

// View publishes
this.publish("game", "player-action", { type: "jump" });

// Model receives on ALL devices during next simulation
this.subscribe("game", "player-action", this.handlePlayerAction);

Use case: User input, game actions, any synchronized state changes

Events are transmitted to the synchronizer and mirrored to all users

// View publishes
this.publish("game", "player-action", { type: "jump" });

// Model receives on ALL devices during next simulation
this.subscribe("game", "player-action", this.handlePlayerAction);

Use case: User input, game actions, any synchronized state changes

Events are queued and handled locally after simulation

// Model publishes locally
this.publish("effects", "explosion", { x: 100, y: 200 });

// View receives only on local device
this.subscribe("effects", "explosion", this.showExplosion);

Use case: Visual effects, audio cues, local UI updates

Events are executed immediately and synchronously

// Model publishes to another model
this.publish("internal", "calculate", { values: [1, 2, 3] });

// Another model receives immediately
this.subscribe("internal", "calculate", this.performCalculation);

Use case: Internal model organization, component communication

Handler executes immediately, before the publish call returns.

Events are queued and handled in the same update cycle

// View publishes to another view
this.publish("ui", "toggle-panel", { panel: "settings" });

// Another view receives in same update cycle
this.subscribe("ui", "toggle-panel", this.handlePanelToggle);

Use case: UI state management, local interface coordination

Scopes and Namespacing

Scopes provide namespacing to avoid event name conflicts and enable targeted communication:

Built-in scopes available everywhere

// Session-wide events
this.subscribe(this.sessionId, "game-start", this.handleGameStart);

// User-specific events
this.subscribe(this.viewId, "user-input", this.handleUserInput);

// Public events
this.subscribe("public", "announcement", this.handleAnnouncement);

Built-in scopes available everywhere

// Session-wide events
this.subscribe(this.sessionId, "game-start", this.handleGameStart);

// User-specific events
this.subscribe(this.viewId, "user-input", this.handleUserInput);

// Public events
this.subscribe("public", "announcement", this.handleAnnouncement);

Target specific model instances

class Player extends Multisynq.Model {
    init() {
        // Listen to events for this specific player
        this.subscribe(this.id, "move", this.handleMove);
        this.subscribe(this.id, "attack", this.handleAttack);
    }
}

// Send event to specific player
this.publish(playerId, "move", { direction: "up" });

Create your own namespaces

// Team-based events
this.subscribe("team-red", "strategy", this.handleTeamStrategy);
this.subscribe("team-blue", "strategy", this.handleTeamStrategy);

// System events
this.subscribe("system", "error", this.handleSystemError);
this.subscribe("system", "warning", this.handleSystemWarning);

Practical Examples

🎮 Game Input System

Complete input handling pattern

class GameView extends Multisynq.View {
    init() {
        document.addEventListener('keydown', (e) => {
            // Send input to model
            this.publish(this.viewId, "input", {
                key: e.key,
                action: "down"
            });
        });
        
        document.addEventListener('keyup', (e) => {
            this.publish(this.viewId, "input", {
                key: e.key,
                action: "up"
            });
        });
    }
}

class GameModel extends Multisynq.Model {
    init() {
        this.players = new Map();
        // Listen for all player inputs
        this.subscribe("*", "input", this.handleInput);
    }
    
    handleInput(data) {
        const playerId = this.getEventSender();
        const player = this.players.get(playerId);
        if (player) {
            player.processInput(data);
        }
    }
}

🎨 Visual Effects System

Model-triggered visual effects

class GameModel extends Multisynq.Model {
    explodeAsteroid(asteroid) {
        // Destroy the asteroid
        asteroid.destroy();
        
        // Trigger visual effect locally
        this.publish("effects", "explosion", {
            x: asteroid.x,
            y: asteroid.y,
            size: asteroid.size
        });
    }
}

class GameView extends Multisynq.View {
    init() {
        this.particles = [];
        this.subscribe("effects", "explosion", this.createExplosion);
    }
    
    createExplosion(data) {
        // Create particle effect
        for (let i = 0; i < 10; i++) {
            this.particles.push(new Particle(data.x, data.y));
        }
    }
}

🤖 AI Agent Communication

Agent-specific communication channels

class AIAgent extends Multisynq.Model {
    init() {
        // Each agent has its own communication channel
        this.subscribe(this.id, "command", this.handleCommand);
        this.subscribe(this.id, "sensor-data", this.processSensorData);
    }
    
    handleCommand(command) {
        switch(command.type) {
            case "move":
                this.moveTo(command.target);
                break;
            case "attack":
                this.attackTarget(command.target);
                break;
        }
    }
    
    reportStatus() {
        // Report to central command
        this.publish("command", "agent-status", {
            id: this.id,
            status: this.status,
            position: { x: this.x, y: this.y }
        });
    }
}

Best Practices

🎯 Targeted Communication

Use specific scopes for efficient communication

// ✅ Good - specific scope
this.publish(playerId, "player-event", data);

// ❌ Avoid - broad scope when specific is better
this.publish("global", "player-event", data);

📦 Small Payloads

Keep event data small and simple

// ✅ Good - minimal data
this.publish("input", "move", { direction: "left" });

// ❌ Avoid - large data structures
this.publish("input", "move", { 
    player: entirePlayerObject,
    gameState: entireGameState
});

🔄 Avoid Chains

Don’t create Model → View → Model chains

// ❌ Avoid this pattern
class GameModel extends Multisynq.Model {
    someMethod() {
        // Model triggers view event
        this.publish("ui", "update", data);
    }
}

class GameView extends Multisynq.View {
    init() {
        this.subscribe("ui", "update", (data) => {
            // View triggers model event - BAD!
            this.publish("model", "response", processedData);
        });
    }
}

🧹 Clean Up

Unsubscribe when no longer needed

class TemporaryComponent extends Multisynq.View {
    init() {
        this.subscribe("temp", "event", this.handler);
    }
    
    destroy() {
        this.unsubscribe("temp", "event");
        // Or use unsubscribeAll() for all subscriptions
        super.destroy();
    }
}

Common Patterns

Centralized state management

class GameState extends Multisynq.Model {
    init() {
        this.score = 0;
        this.level = 1;
        
        this.subscribe("game", "score", this.updateScore);
        this.subscribe("game", "level", this.updateLevel);
    }
    
    updateScore(points) {
        this.score += points;
        this.publish("ui", "score-changed", this.score);
    }
    
    updateLevel(newLevel) {
        this.level = newLevel;
        this.publish("ui", "level-changed", this.level);
    }
}

Centralized state management

class GameState extends Multisynq.Model {
    init() {
        this.score = 0;
        this.level = 1;
        
        this.subscribe("game", "score", this.updateScore);
        this.subscribe("game", "level", this.updateLevel);
    }
    
    updateScore(points) {
        this.score += points;
        this.publish("ui", "score-changed", this.score);
    }
    
    updateLevel(newLevel) {
        this.level = newLevel;
        this.publish("ui", "level-changed", this.level);
    }
}

Object creation and destruction

class Player extends Multisynq.Model {
    init() {
        // Announce player joined
        this.publish("players", "joined", {
            id: this.id,
            name: this.name
        });
    }
    
    destroy() {
        // Announce player left
        this.publish("players", "left", {
            id: this.id,
            name: this.name
        });
        
        super.destroy();
    }
}

Time-based event systems

class GameTimer extends Multisynq.Model {
    init() {
        this.timeLeft = 60;
        this.tick();
    }
    
    tick() {
        this.timeLeft--;
        
        // Notify views of time change
        this.publish("timer", "update", this.timeLeft);
        
        if (this.timeLeft <= 0) {
            this.publish("game", "time-up", {});
        } else {
            this.future(1000).tick();
        }
    }
}

Event Debugging

Track event flow in development

class DebugModel extends Multisynq.Model {
    publish(scope, event, data) {
        console.log(`[MODEL] Publishing: ${scope}:${event}`, data);
        super.publish(scope, event, data);
    }
    
    subscribe(scope, event, handler) {
        console.log(`[MODEL] Subscribing to: ${scope}:${event}`);
        super.subscribe(scope, event, handler);
    }
}

Track event flow in development

class DebugModel extends Multisynq.Model {
    publish(scope, event, data) {
        console.log(`[MODEL] Publishing: ${scope}:${event}`, data);
        super.publish(scope, event, data);
    }
    
    subscribe(scope, event, handler) {
        console.log(`[MODEL] Subscribing to: ${scope}:${event}`);
        super.subscribe(scope, event, handler);
    }
}

Validate event data structure

class ValidatedModel extends Multisynq.Model {
    publish(scope, event, data) {
        // Validate data can be serialized
        try {
            JSON.stringify(data);
        } catch (e) {
            console.error(`Invalid event data for ${scope}:${event}`, e);
            return;
        }
        
        super.publish(scope, event, data);
    }
}

Performance Considerations

Avoid these performance pitfalls:

High-frequency events: Don’t publish events every frame
Large payloads: Keep event data minimal
Circular subscriptions: Avoid event loops
Unused subscriptions: Always clean up when done

Limit event frequency

class ThrottledInput extends Multisynq.View {
    init() {
        this.lastMove = 0;
        document.addEventListener('mousemove', this.handleMouseMove);
    }
    
    handleMouseMove(e) {
        const now = Date.now();
        if (now - this.lastMove < 16) return; // ~60fps max
        
        this.lastMove = now;
        this.publish("input", "mouse-move", {
            x: e.clientX,
            y: e.clientY
        });
    }
}

Limit event frequency

class ThrottledInput extends Multisynq.View {
    init() {
        this.lastMove = 0;
        document.addEventListener('mousemove', this.handleMouseMove);
    }
    
    handleMouseMove(e) {
        const now = Date.now();
        if (now - this.lastMove < 16) return; // ~60fps max
        
        this.lastMove = now;
        this.publish("input", "mouse-move", {
            x: e.clientX,
            y: e.clientY
        });
    }
}

Group related events

class BatchedUpdates extends Multisynq.Model {
    init() {
        this.pendingUpdates = [];
        this.batchTimer = null;
    }
    
    queueUpdate(update) {
        this.pendingUpdates.push(update);
        
        if (!this.batchTimer) {
            this.batchTimer = this.future(100).processBatch();
        }
    }
    
    processBatch() {
        if (this.pendingUpdates.length > 0) {
            this.publish("batch", "updates", this.pendingUpdates);
            this.pendingUpdates = [];
        }
        this.batchTimer = null;
    }
}

Next Steps

Writing a Multisynq Model

Learn how to build robust, event-driven models

Writing a Multisynq View

Master view development and user interaction

Snapshots

Understand state persistence and recovery

Sim Time & Future

Master time-based behaviors and scheduling

Events are the nervous system of Multisynq applications. Understanding when and how to use them effectively is crucial for building responsive, maintainable multiplayer experiences.

Get Started

Tutorials

Conceptual

Essentials

AI Development

Core Event API

Handler Requirements

Event Routing Patterns

Scopes and Namespacing

Practical Examples

Best Practices

🎯 Targeted Communication

📦 Small Payloads

🔄 Avoid Chains

🧹 Clean Up

Common Patterns

Event Debugging

Performance Considerations

Next Steps

Writing a Multisynq Model

Writing a Multisynq View

Snapshots

Sim Time & Future

Get Started

Tutorials

Conceptual

Essentials

AI Development

​Core Event API

​Handler Requirements

​Event Routing Patterns

​Scopes and Namespacing

​Practical Examples

​Best Practices

🎯 Targeted Communication

📦 Small Payloads

🔄 Avoid Chains

🧹 Clean Up

​Common Patterns

​Event Debugging

​Performance Considerations

​Next Steps

Writing a Multisynq Model

Writing a Multisynq View

Snapshots

Sim Time & Future

Core Event API

Handler Requirements

Event Routing Patterns

Scopes and Namespacing

Practical Examples

Best Practices

Common Patterns

Event Debugging

Performance Considerations

Next Steps