Actors: Sample Flows

Use these sample flows as a starting point for your implementation.

Connect a client to a session

When the frontend needs to join a live session, receive messages from the actor, and send messages to the actor, connect a client to an actor session. To connect a client to a session:

Call base44.actors.ActorName(sessionId) to select the session.
Call .connect() to open the WebSocket connection.
Call conn.subscribe() to register a listener for messages from the actor.
Call conn.send() to send a message to the actor.

The following example connects to a chatRoom actor session, listens for messages, and sends a message:

const conn = base44.actors.chatRoom("lobby-1").connect();

conn.subscribe((msg) => {
  if (msg.type === "message") console.log(msg.text);
});

conn.send({ type: "message", text: "Hello" });

To learn more about connections, see connections.

Run ticks

When work needs to repeat on an interval while clients are in the session, run ticks. Examples include broadcasting game state or updating a round timer. To run ticks:

Set tickIntervalMs to the interval length in milliseconds.
Implement shouldTick() to return true to keep ticking and false to stop.
In handleTick(), run the work for each interval.

The following example ticks every second while at least two clients are in the session, broadcasting a countdown each tick:

export default class Game extends Actor<Incoming, Outgoing> {
  tickIntervalMs = 1000;
  countdown = 60;

  shouldTick() {
    return this.getConnections().length >= 2;
  }

  async handleTick() {
    this.countdown--;
    this.broadcast({ type: "tick", countdown: this.countdown });
  }
}

To learn more about ticks, see timer handlers and settings.

Schedule wakes

When work needs to run once at a specific time, whether the session is active or idle, schedule a wake. Examples include ending a turn after 30 seconds or closing an empty lobby. To schedule a wake:

Call schedule() with a key and a time to arm the wake.
In handleWake(), check the key and run the work for that wake.
When the wake no longer applies, call cancelSchedule() with the key.

The following example schedules a turn timeout when a turn starts and broadcasts a message when the timeout triggers:

export default class Game extends Actor<Incoming, Outgoing> {
  async handleMessage(_conn, msg) {
    if (msg.type === "start-turn") {
      await this.schedule("turn-timeout", Date.now() + 30_000);
    }
    if (msg.type === "end-turn") {
      await this.cancelSchedule("turn-timeout");
    }
  }

  async handleWake(key: string) {
    if (key === "turn-timeout") {
      this.broadcast({ type: "timeout" });
    }
  }
}

To learn more about wakes, see timer handlers and settings.

Manage client connections

When you need to decide who can join a session, reply to a specific client, and reach every client in the session, manage client connections. To manage client connections:

In handleConnect(), check conn.identity and call conn.reject() to refuse a client.
Call conn.send() to reply to only that client.
In handleMessage(), call broadcast() to reach every connected client. To identify the sender, include fields from conn in the message.

The following example rejects anonymous clients, sends history to the connecting client, and broadcasts messages with the sender’s user ID:

async handleConnect(conn) {
  if (conn.identity.type === "anonymous") {
    conn.reject(401, "Login required");
    return;
  }
  conn.send({ type: "history", messages: this.messages });
}

async handleMessage(conn, msg) {
  this.broadcast({ type: "message", from: conn.identity.userId, text: msg.text });
}

To learn more about connections, see connections.

Persist session data

When values need to survive an idle period, persist session data. Examples include a board, a history list, or the current turn. To persist session data:

In handleStart(), load values from this.storage into class fields.
After each change, call this.storage.put() to save the updated value.
To reset the session, call this.storage.delete() or this.storage.deleteAll().

The following example loads a board on start, saves it after each move, and clears storage when the last client disconnects:

async handleStart() {
  this.board = (await this.storage.get<Board>("board")) ?? newBoard();
}

async handleMessage(_conn, msg) {
  applyMove(this.board, msg.move);
  await this.storage.put("board", this.board);
}

async handleClose(_conn) {
  if (this.getConnections().length === 0) {
    await this.storage.deleteAll();
  }
}

To learn more about storage, see storage.

Write entity data from a session

When the session needs to create or update app records, write entity data. Examples include a final score or a completed order. To write entity data from a session:

Validate the incoming message before writing.
Read the user ID from conn.identity.userId.
Use this.client.asServiceRole for elevated access. Write with a stable key, such as the session ID, so a repeated handler updates the same record.

The following example saves a final score for the authenticated client. A later save for the same session updates that record:

async handleMessage(conn, msg) {
  if (msg.type !== "save-score" || conn.identity.type !== "authenticated") return;
  if (typeof msg.score !== "number") return;

  const fields = {
    sessionId: this.instanceId,
    userId: conn.identity.userId,
    score: msg.score,
  };
  const [existing] = await this.client.asServiceRole.entities.Score.filter({
    sessionId: this.instanceId,
  });

  if (existing) {
    await this.client.asServiceRole.entities.Score.update(existing.id, fields);
  } else {
    await this.client.asServiceRole.entities.Score.create(fields);
  }
}

To learn more about entity access, see entity access.

Call a backend function for secret work

Actors can read app secrets with secrets.get(). When a handler needs work that uses a secret, such as calling an external API with an API key, we recommend calling a backend function. The function reads the secret and returns the result, never the secret. To call a backend function from an actor:

Create a backend function that reads the secret with secrets.get(), does the work, and returns the result.
In a handler, call this.client.functions.invoke() with the function name and the data to send.
Use the result in your session, such as broadcasting it to connected clients.

The following example shows a backend function that reads an API key and returns a translation:

// base44/functions/translateText/entry.ts
import { secrets } from "base44:runtime";

export default async function (req: Request): Promise<Response> {
  const { text } = await req.json();
  const apiKey = secrets.get("TRANSLATE_API_KEY");

  const res = await fetch("https://api.example.com/translate", {
    method: "POST",
    headers: { Authorization: `Bearer ${apiKey}` },
    body: JSON.stringify({ text }),
  });
  const { translation } = await res.json();

  return Response.json({ translation });
}

The following example calls that function from an actor and broadcasts the result:

export default class ChatRoom extends Actor<Incoming, Outgoing> {
  async handleMessage(_conn, msg) {
    const result = await this.client.functions.invoke("translateText", { text: msg.text });
    this.broadcast({ type: "message", text: result.data.translation });
  }
}

Overview

Quickstarts

Project

AI Development Tools

Resources

Connect a client to a session

Run ticks

Schedule wakes

Manage client connections

Persist session data

Write entity data from a session

Call a backend function for secret work

See also

​Connect a client to a session

​Run ticks

​Schedule wakes

​Manage client connections

​Persist session data

​Write entity data from a session

​Call a backend function for secret work

​See also

Connect a client to a session

Run ticks

Schedule wakes

Manage client connections

Persist session data

Write entity data from a session

Call a backend function for secret work

See also