Actors: Beispielabläufe

Nutze diese Beispielabläufe als Ausgangspunkt für deine Implementierung.

Einen Client mit einer Session verbinden

Wenn das Frontend einer Live-Session beitreten, Nachrichten vom Actor empfangen und Nachrichten an den Actor senden soll, verbinde einen Client mit einer Actor-Session. So verbindest du einen Client mit einer Session:

Rufe base44.actors.ActorName(sessionId) auf, um die Session auszuwählen.
Rufe .connect() auf, um die WebSocket-Verbindung zu öffnen.
Rufe conn.subscribe() auf, um einen Listener für Nachrichten vom Actor zu registrieren.
Rufe conn.send() auf, um eine Nachricht an den Actor zu senden.

Das folgende Beispiel verbindet sich mit einer chatRoom-Actor-Session, hört auf Nachrichten und sendet eine Nachricht:

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" });

Mehr über Verbindungen erfährst du unter Verbindungen.

Ticks ausführen

Wenn sich Arbeit in einem Intervall wiederholen soll, während Clients in der Session sind, führe Ticks aus. Beispiele sind das Broadcasten des Spielzustands oder das Aktualisieren eines Runden-Timers. So führst du Ticks aus:

Setze tickIntervalMs auf die Intervalllänge in Millisekunden.
Implementiere shouldTick() so, dass es true zurückgibt, um weiter zu ticken, und false, um zu stoppen.
Führe in handleTick() die Arbeit für jedes Intervall aus.

Das folgende Beispiel tickt jede Sekunde, solange mindestens zwei Clients in der Session sind. Bei jedem Tick sendet es einen Countdown per Broadcast:

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

Mehr über Ticks erfährst du unter Timer-Handler und Einstellungen.

Wakes planen

Wenn Arbeit einmalig zu einem bestimmten Zeitpunkt laufen soll, egal ob die Session aktiv oder inaktiv ist, plane einen Wake. Beispiele sind das Beenden eines Zugs nach 30 Sekunden oder das Schließen einer leeren Lobby. So planst du einen Wake:

Rufe schedule() mit einem Schlüssel und einem Zeitpunkt auf, um den Wake zu planen.
Prüfe in handleWake() den Schlüssel und führe die Arbeit für diesen Wake aus.
Wenn der Wake nicht mehr gilt, rufe cancelSchedule() mit dem Schlüssel auf.

Das folgende Beispiel plant ein Zug-Timeout, wenn ein Zug beginnt. Wenn das Timeout ausgelöst wird, sendet es eine Nachricht per Broadcast:

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" });
    }
  }
}

Mehr über Wakes erfährst du unter Timer-Handler und Einstellungen.

Client-Verbindungen verwalten

Wenn du festlegen musst, wer einer Session beitreten darf, einem bestimmten Client antworten oder alle Clients in der Session erreichen willst, verwalte Client-Verbindungen. So verwaltest du Client-Verbindungen:

Prüfe in handleConnect() die Eigenschaft conn.identity und rufe conn.reject() auf, um einen Client abzulehnen.
Rufe conn.send() auf, um nur diesem Client zu antworten.
Rufe in handleMessage() broadcast() auf, um jeden verbundenen Client zu erreichen. Um den Absender zu identifizieren, füge Felder aus conn in die Nachricht ein.

Das folgende Beispiel lehnt anonyme Clients ab, sendet dem verbindenden Client den Verlauf und sendet Nachrichten mit der Nutzer-ID des Absenders per Broadcast:

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

Mehr über Verbindungen erfährst du unter Verbindungen.

Session-Daten persistieren

Wenn Werte eine Leerlaufphase überstehen müssen, persistiere Session-Daten. Beispiele sind ein Spielbrett, eine Verlaufsliste oder der aktuelle Zug. So persistierst du Session-Daten:

Lade in handleStart() Werte aus this.storage in Klassenfelder.
Rufe nach jeder Änderung this.storage.put() auf, um den aktualisierten Wert zu speichern.
Um die Session zurückzusetzen, rufe this.storage.delete() oder this.storage.deleteAll() auf.

Das folgende Beispiel lädt beim Start ein Spielbrett und speichert es nach jedem Zug. Wenn der letzte Client die Verbindung trennt, leert es den Speicher:

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();
  }
}

Mehr über Speicher erfährst du unter Speicher.

Entitätsdaten aus einer Session schreiben

Wenn die Session App-Datensätze erstellen oder aktualisieren muss, schreibe Entitätsdaten. Beispiele sind ein Endstand oder eine abgeschlossene Bestellung. So schreibst du Entitätsdaten aus einer Session:

Validiere die eingehende Nachricht vor dem Schreiben.
Lies die Nutzer-ID aus conn.identity.userId.
Verwende this.client.asServiceRole für erweiterten Zugriff. Schreibe mit einem stabilen Schlüssel, etwa der Session-ID. So aktualisiert ein wiederholter Handler denselben Datensatz.

Das folgende Beispiel speichert einen Endstand für den authentifizierten Client. Ein späteres Speichern für dieselbe Session aktualisiert diesen Datensatz:

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

Mehr über den Zugriff auf Entitäten erfährst du unter Zugriff auf Entitäten.

Eine Backend-Funktion für Aufgaben mit Secrets aufrufen

Actors können App-Secrets mit secrets.get() lesen. Wenn ein Handler eine Aufgabe mit einem Secret ausführen muss, etwa eine externe API mit einem API-Schlüssel aufrufen, empfehlen wir den Aufruf einer Backend-Funktion. Die Funktion liest das Secret und gibt das Ergebnis zurück, niemals das Secret. So rufst du eine Backend-Funktion aus einem Actor auf:

Erstelle eine Backend-Funktion, die das Secret mit secrets.get() liest, die Aufgabe erledigt und das Ergebnis zurückgibt.
Rufe in einem Handler this.client.functions.invoke() mit dem Funktionsnamen und den zu sendenden Daten auf.
Verwende das Ergebnis in deiner Session, etwa indem du es per Broadcast an verbundene Clients sendest.

Das folgende Beispiel zeigt eine Backend-Funktion, die einen API-Schlüssel liest und eine Übersetzung zurückgibt:

// 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 });
}

Das folgende Beispiel ruft diese Funktion aus einem Actor auf und sendet das Ergebnis per Broadcast:

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

Siehe auch

Actors – Übersicht: Konzepte und Terminologie
Einen Actor erstellen: Actor-Dateien und eine minimale Klasse
Actors – Dateien und Code: Vollständige API der Backend-Klasse
actors deploy: Lokale Actors deployen

Diese Seite wurde mit KI übersetzt. Die genauesten und aktuellsten Informationen findest du in der englischen Version.

Übersicht

Schnellstarts

Projekt

KI-Entwicklungstools

Ressourcen

Einen Client mit einer Session verbinden

Ticks ausführen

Wakes planen

Client-Verbindungen verwalten

Session-Daten persistieren

Entitätsdaten aus einer Session schreiben

Eine Backend-Funktion für Aufgaben mit Secrets aufrufen

Siehe auch

​Einen Client mit einer Session verbinden

​Ticks ausführen

​Wakes planen

​Client-Verbindungen verwalten

​Session-Daten persistieren

​Entitätsdaten aus einer Session schreiben

​Eine Backend-Funktion für Aufgaben mit Secrets aufrufen

​Siehe auch

Einen Client mit einer Session verbinden

Ticks ausführen

Wakes planen

Client-Verbindungen verwalten

Session-Daten persistieren

Entitätsdaten aus einer Session schreiben

Eine Backend-Funktion für Aufgaben mit Secrets aufrufen

Siehe auch