Canvas Client

Feature: Canvas Client

The CanvasClient is the primary integration point for applications. It manages the network connection, session state, and synchronizes the local simulation with the authoritative Canvas Server.

Key Concepts

• Gateway: Acts as the single entry point for all network interactions (Session, Assets, Scene).
• State Machine: Manages the complex lifecycle of connecting, handshaking, and syncing.
• Thread Safety: Designed for integration into a single-threaded main loop (the “Application Loop”).

Usage

1. Initialization

The client is lightweight and can be instantiated on the stack or as a member of your Application class.

#include <EntropyCanvas/Network/CanvasClient.h>

CanvasClient client;

2. Connection

Use CanvasDiscovery to find local instances (like the Portal or a background daemon) or connect to a known endpoint.

// Auto-connect to the first available local instance
auto instances = CanvasDiscovery::findLocal();
if (!instances.empty()) {
    client.connect(instances[0].endpoint);
}

3. The Application Loop

The critical integration point is the poll() method, which must be called once per frame. This dispatches network events to your main thread.

while (app.isRunning()) {
    // 1. Process incoming network packets
    client.poll();

    // 2. Sync local changes to the network
    client.syncWorld(myFlecsWorld);

    // 3. Render
    app.render();
}