> ## Documentation Index
> Fetch the complete documentation index at: https://docs.base44.com/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Internal links on these pages omit the .md extension. Append .md to a docs page URL, or send an Accept: text/markdown header, to get that page as markdown.

# Actors – Übersicht

> Erfahre, wie Actors gemeinsame Live-Sessions mit Echtzeitnachrichten und Timern ausführen

<div className="dev-docs-banner">
  <div className="dev-docs-banner-content">
    <div className="dev-docs-banner-title">
      Du siehst gerade die Entwicklerdokumentation
    </div>

    <div className="dev-docs-banner-text">
      Diese Dokumentation richtet sich an Entwickler, die mit der Base44-Entwicklerplattform arbeiten.
    </div>
  </div>
</div>

Ein Actor ist ein langlaufender Backend-Prozess, mit dem sich mehrere Clients gleichzeitig verbinden.

Mit Actors kannst du Live-Session-Instanzen bauen, die folgende Funktionen unterstützen:

* **Echtzeitnachrichten:** Sende und empfange Nachrichten mit Clients über WebSockets.
* **Persistenter Speicher:** Erhalte den Session-Zustand über Leerlaufphasen hinweg.
* **Geplante Arbeit:** Führe Logik in einem festen Intervall oder zu einem bestimmten Zeitpunkt aus.

Verwende Actors für Funktionen, bei denen mehrere Clients Echtzeit-Updates und Interaktion brauchen, etwa einen Chatraum oder ein Multiplayer-Spiel.

## Actors

[`Actor`](/de/developers/backend/resources/actors/reference) ist die Klasse, die du in deinem Backend erweiterst.

Die Actor-Klasse definiert das Verhalten einer Live-Session. Mit Actors kannst du:

* **[Verbindungen verwalten](#connections):** Akzeptiere oder lehne einen Client ab, der sich mit der Session verbindet, und identifiziere, wer sich verbindet.
* **[Nachrichten verarbeiten](#realtime-messages):** Empfange eine Nachricht von einem Client, aktualisiere den Session-Zustand und antworte einem Client oder sende an alle.
* **[Arbeit planen](#scheduled-work):** Führe Logik in einem Intervall oder zu einem geplanten Zeitpunkt aus.

## Sessions

Eine Session ist eine laufende Instanz eines Actors. Sie wird durch den Actor-Namen und eine von dir gewählte Session-ID identifiziert.\
Jede Session verwaltet ihren eigenen Zustand, Speicher und ihre Client-Verbindungen unabhängig.

### Verbindungen

Eine Verbindung steht für den WebSocket eines Clients zu einer Session. Jeder Client, der beitritt, erhält eine eigene Verbindung. Ein Actor nutzt diese Verbindung, um zu erkennen, wer sich verbindet, Client-Verbindungen zu verwalten und Nachrichten zu senden.

Mehr dazu unter [Verbindungen](/de/developers/backend/resources/actors/reference#connections). Einen Beispielablauf findest du unter [Client-Verbindungen verwalten](/de/developers/backend/resources/actors/sample-flows#manage-client-connections).

### Aktive und inaktive Sessions

Eine Session ist immer in einem der folgenden Zustände:

* **Aktiv:** Die Session ist live und verarbeitet Ereignisse. Eine Session wird aktiv, wenn sich ein Client verbindet, wenn ein Client einer inaktiven Session eine Nachricht sendet oder wenn eine geplante Wake-Zeit erreicht ist.
* **Inaktiv:** Die Session verarbeitet keine Ereignisse. Eine Session wird kurz nach ihrer letzten Nachricht inaktiv, sobald alle geplante Arbeit stoppt. Die Session behält ihre [gespeicherten Daten](#storage), geplanten Zeiten und offenen Verbindungen, bis sie wieder aktiv wird.

Wenn eine Session inaktiv wird, bleiben Clients mit offenen Verbindungen verbunden. Ihre nächste Nachricht oder ein geplanter [Wake](#wakes) aktiviert die Session wieder.

## Client

Verwende [`base44.actors`](/de/developers/references/sdk/docs/type-aliases/actors) im JavaScript SDK, um einen Client mit einer Actor-Session zu verbinden und Nachrichten auszutauschen.

Das Actors-SDK unterstützt folgende Funktionen:

* **Verbinden:** Öffne eine WebSocket-Verbindung zu einer Session.
* **Abonnieren:** Empfange Nachrichten vom Actor.
* **Senden:** Sende Nachrichten an den Actor.
* **Schließen:** Schließe die WebSocket-Verbindung zum Actor.

Mehr dazu unter [Einen Client mit einer Session verbinden](/de/developers/backend/resources/actors/sample-flows#connect-a-client-to-a-session).

## So interagieren Actors und Clients

Das folgende Diagramm zeigt die allgemeine Interaktion zwischen einem Client und einem Actor:

```mermaid theme={null}
sequenceDiagram
    participant C as Client
    participant A as Actor

    C->>A: 1. connect(sessionId)
    A->>A: 2. handleStart()
    A->>A: 3. handleConnect(conn)
    C->>A: 4. send(data)
    A->>A: 5. handleMessage(conn, msg)
    A-->>C: 6. broadcast(data)
    C->>A: 7. close()
    A->>A: 8. handleClose(conn)
```

1. Der Client verbindet sich über einen WebSocket mit dem Actor.
2. Die Session wird aktiviert. [`handleStart()`](/de/developers/backend/resources/actors/reference#lifecycle-handlers) läuft beim ersten Start und bei jeder Aktivierung aus dem Leerlauf.
3. Der Actor verarbeitet die Verbindung. Du kannst die Identität des Clients prüfen und die Verbindung ablehnen oder den aktuellen Zustand senden.
4. Der Client sendet eine Nachricht.
5. Der Actor verarbeitet die Nachricht. Du kannst das Format und die Berechtigungen des Absenders prüfen, bevor du den Session-Zustand änderst.
6. Der Actor sendet das Update per Broadcast an jeden verbundenen Client oder antwortet nur dem Absender.
7. Der Client schließt die Verbindung.
8. Der Actor verarbeitet den Verbindungsabbruch. Du kannst verbindungsbezogenen Zustand entfernen.

## Echtzeitnachrichten

Jeder verbundene Client gehört zu einer Session und kann über WebSockets Nachrichten in Echtzeit senden. Clients können mit [`subscribe()`](/de/developers/references/sdk/docs/type-aliases/actors#subscribe) auch auf eingehende Nachrichten hören.

<Note>
  Base44 bietet mehrere Echtzeitfunktionen mit abonnementbasiertem Listener:

  * Actor-[`subscribe()`](/de/developers/references/sdk/docs/type-aliases/actors#subscribe) hört auf Nachrichten, die der Actor an verbundene Clients sendet.
  * Entity-[`subscribe()`](/de/developers/references/sdk/docs/type-aliases/entities#subscribe) hört auf Änderungen an App-Entitäten.

  Prüfe, welchen Dienst du verwendest, damit du die erwarteten Ereignisse erhältst.
</Note>

Mit Echtzeitnachrichten kannst du:

* Einem bestimmten Client antworten.
* An alle verbundenen Clients senden.
* Die aktuell verbundenen Clients auflisten.
* Jeden Client identifizieren und prüfen, ob er angemeldet ist.

Mehr dazu unter [Verbindungen](#connections). Einen Beispielablauf findest du unter [Client-Verbindungen verwalten](/de/developers/backend/resources/actors/sample-flows#manage-client-connections).

## Nachrichtentypen

Ein Client und ein Actor tauschen Nachrichten über eine Verbindung aus. Nachrichten gehören zu folgenden Typen:

* **Eingehende Nachrichten:** Was ein verbundener Client an den Actor sendet, etwa einen Text, einen Spielzug oder eine Stimme. Der Client sendet sie mit [`send()`](/de/developers/references/sdk/docs/type-aliases/actors#send). Der Actor empfängt sie in [`handleMessage()`](/de/developers/backend/resources/actors/reference#lifecycle-handlers).
* **Ausgehende Nachrichten:** Was der Actor an verbundene Clients sendet, etwa eine Antwort an einen Client, einen Broadcast an alle verbundenen Clients oder das aktuelle Spielbrett, wenn jemand beitritt. Der Actor sendet sie mit [`conn.send()`](/de/developers/backend/resources/actors/reference#connections) oder `broadcast()`. Der Client empfängt sie in einem [`subscribe()`](/de/developers/references/sdk/docs/type-aliases/actors#subscribe)-Callback.

Wir empfehlen, deine Nachrichten zu typisieren, damit Actor und Client dieselbe Struktur jeder Nachricht verwenden:

* **Backend:** Übergib die Typen `Incoming` und `Outgoing` als Generics an die Klasse `Actor`. Ein vollständiges Beispiel findest du unter [Einen Actor erstellen](/de/developers/backend/resources/actors/create-actor).
* **Client:** Erweitere das Interface [`ActorRegistry`](/de/developers/references/sdk/docs/type-aliases/actors#actorregistry) mit denselben Strukturen. So prüft TypeScript die Typen von `send()` und `subscribe()`.

## Speicher

Actors bieten mehrere Speicheroptionen, je nachdem, wie deine Session Daten nutzt und aufbewahrt:

* **[In-Memory-Speicher](#in-memory-storage):** Arbeitszustand in Klassenfeldern, solange die Session aktiv ist. Er wird zurückgesetzt, wenn die Session inaktiv wird.
* **[Persistenter Speicher](#persistent-storage):** Ein Key-Value-Speicher für Daten, die erhalten bleiben müssen, wenn die Session inaktiv wird.

### In-Memory-Speicher

Klassenfelder enthalten den Arbeitszustand, solange die Session aktiv ist, etwa das aktuelle Spielbrett oder einen Runden-Timer. Verwende In-Memory-Speicher, wenn sich deine Daten häufig ändern und beim Leerlauf nicht erhalten bleiben müssen, etwa ein Live-Spielstand oder eine Cursorposition.

Wenn eine Session inaktiv wird, werden Klassenfelder zurückgesetzt.

### Persistenter Speicher

Jede Session hat ihren eigenen Key-Value-Speicher, den du vollständig verwalten kannst.
Verwende persistenten Speicher, wenn deine Daten erhalten bleiben müssen, wenn die Session inaktiv wird, etwa ein Chatverlauf oder ein Spielbrett.

Um Daten zu speichern, die in der gesamten App verfügbar sind, verwende [Entitäten](/de/developers/backend/resources/entities/overview).

Mehr über Actor-Speicher erfährst du unter [Speicher](/de/developers/backend/resources/actors/reference#storage).

### Zustand wiederherstellen

Wenn eine Session inaktiv wird, wird der In-Memory-Zustand zurückgesetzt. Persistenter Speicher bleibt erhalten. Die Session lädt die gespeicherten Daten bei der Aktivierung aber nicht automatisch zurück in den Arbeitsspeicher.

Verwende [`handleStart()`](/de/developers/backend/resources/actors/reference#lifecycle-handlers), um persistente Daten wiederherzustellen, etwa den Chatverlauf oder das Spielbrett.

Einen Beispielablauf findest du unter [Session-Daten persistieren](/de/developers/backend/resources/actors/sample-flows#persist-session-data).

## Geplante Arbeit

Actors bieten Funktionen, mit denen eine Session Logik nach Zeitplan ausführt, unabhängig von Client-Nachrichten:

* **[Ticks](#ticks):** Führe Code in einem Intervall aus und halte die Session aktiv, solange sie sich wiederholen.
* **[Wakes](#wakes):** Führe Code einmalig zu einem von dir gewählten Zeitpunkt aus, egal ob die Session aktiv oder inaktiv ist.

### Ticks

Ticks führen Code in einem Intervall aus und halten die Session aktiv, solange sie sich wiederholen.

Verwende [`shouldTick()`](/de/developers/backend/resources/actors/reference#timer-handlers-and-settings), um die Bedingungen für das Ticken festzulegen.
Ein Actor wertet `shouldTick()` nach jeder Verbindung, Nachricht, Trennung und jedem Tick neu aus. So stoppt das Ticken, sobald die Bedingung nicht mehr erfüllt ist.

<Note>
  Ticken erfordert mindestens einen verbundenen Client.
</Note>

Mit Ticks kannst du:

* Die Länge jedes Intervalls wählen.
* Eine Bedingung definieren, die das Ticken startet und stoppt, etwa „mindestens zwei Spieler sind in der Session“.
* Den Code schreiben, der in jedem Intervall läuft.

Verwende Ticks, um eine Session aktiv zu halten, auch wenn Clients keine Nachrichten senden, etwa um einen Runden-Timer zu aktualisieren.

Mehr über Ticks erfährst du unter [Timer-Handler und Einstellungen](/de/developers/backend/resources/actors/reference#timer-handlers-and-settings). Einen Beispielablauf findest du unter [Ticks ausführen](/de/developers/backend/resources/actors/sample-flows#run-ticks).

### Wakes

Ein Wake läuft einmalig zu einem von dir gewählten Zeitpunkt, egal ob die Session aktiv oder inaktiv ist.

Mit Wakes kannst du:

* Festlegen, wann ein Wake läuft.
* Logik implementieren, die beim Wake ausgeführt wird.

Verwende einen Wake, um eine einmalige Aktion zu planen. Beispiele sind das Beenden eines Spielzugs, das Schließen einer leeren Lobby, eine Erinnerung oder der Start eines Ereignisses zu einem bestimmten Zeitpunkt.

Mehr über Wakes erfährst du unter [Timer-Handler und Einstellungen](/de/developers/backend/resources/actors/reference#timer-handlers-and-settings). Einen Beispielablauf findest du unter [Wakes planen](/de/developers/backend/resources/actors/sample-flows#schedule-wakes).

## Einen Actor deployen

Deploye Actors mit [`actors deploy`](/de/developers/references/cli/commands/actors-deploy). Um alle Projektressourcen auf einmal zu pushen, verwende [`deploy`](/de/developers/references/cli/commands/deploy). Beim Deployen werden Remote-Actors hinzugefügt und aktualisiert. Die übrigen bleiben unverändert.

## Einen Actor löschen

So löschst du einen Actor:

* Führe [`actors delete`](/de/developers/references/cli/commands/actors-delete) aus, um den Remote-Actor aus Base44 zu löschen.
* Lösche das Actor-Verzeichnis aus deinem lokalen Projekt.

<Note>
  Wenn du den Actor nicht aus deinem lokalen Projekt löschst, erstellt und deployt das nächste [`actors deploy`](/de/developers/references/cli/commands/actors-deploy) oder [`deploy`](/de/developers/references/cli/commands/deploy) den Actor erneut in deinem Base44-Projekt.
</Note>

## Siehe auch

* [Einen Actor erstellen](/de/developers/backend/resources/actors/create-actor): Actor-Dateien und eine minimale Klasse
* [Actors – Beispielabläufe](/de/developers/backend/resources/actors/sample-flows): Lebenszyklus, Timer, Verbindungen, Speicher, Entitäten und Backend-Funktionen
* [Actors – Dateien und Code](/de/developers/backend/resources/actors/reference): Vollständige API der Backend-Klasse
* [`actors` SDK-Referenz](/de/developers/references/sdk/docs/type-aliases/actors): API des Client-SDK

<Note>Diese Seite wurde mit KI übersetzt. Die genauesten und aktuellsten Informationen findest du in der [englischen Version](/). </Note>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.