146 lines
4.6 KiB
Markdown
146 lines
4.6 KiB
Markdown
# Realtime
|
|
|
|
> Source: `src/content/docs/actors/events.mdx`
|
|
> Canonical URL: https://rivet.dev/docs/actors/events
|
|
> Description: Events enable realtime communication from actors to clients. While clients use actions to send data to actors, events allow actors to push updates to connected clients instantly.
|
|
|
|
---
|
|
Events can be sent to clients connected using `.connect()`. They have no effect on [low-level WebSocket connections](/docs/actors/websocket-handler).
|
|
|
|
For worked realtime patterns, see the cookbook: [Live Cursors and Presence](/cookbook/live-cursors/) and [Chat Room](/cookbook/chat-room/).
|
|
|
|
## Publishing Events from Actors
|
|
|
|
### Broadcasting to All Clients
|
|
|
|
Define event names and payload types with `events` and `event()`, then use `c.broadcast(eventName, ...args)` to send events to all connected clients:
|
|
|
|
### Sending to Specific Connections
|
|
|
|
Send events to individual connections using `conn.send(eventName, ...args)`:
|
|
|
|
Send events to all connections except the sender:
|
|
|
|
## Subscribing to Events from Clients
|
|
|
|
Clients must establish a connection to receive events from actors. Use `.connect()` to create a persistent connection, then listen for events.
|
|
|
|
### Basic Event Subscription
|
|
|
|
Use `connection.on(eventName, callback)` to listen for events:
|
|
|
|
```tsx React @nocheck
|
|
import { useState } from "react";
|
|
import { useActor } from "./rivetkit";
|
|
|
|
function ChatRoom() {
|
|
const [messages, setMessages] = useState<Array<{id: string, userId: string, text: string}>>([]);
|
|
|
|
const chatRoom = useActor({
|
|
name: "chatRoom",
|
|
key: ["general"]
|
|
});
|
|
|
|
// Listen for events
|
|
chatRoom.useEvent("messageReceived", (message) => {
|
|
setMessages(prev => [...prev, message]);
|
|
});
|
|
|
|
// ...rest of component...
|
|
}
|
|
```
|
|
|
|
### One-time Event Listeners
|
|
|
|
Use `connection.once(eventName, callback)` for events that should only trigger once:
|
|
|
|
```tsx React @nocheck
|
|
import { useState, useEffect } from "react";
|
|
import { useActor } from "./rivetkit";
|
|
|
|
function GameLobby() {
|
|
const [gameStarted, setGameStarted] = useState(false);
|
|
|
|
const gameRoom = useActor({
|
|
name: "gameRoom",
|
|
key: ["room-456"],
|
|
params: {
|
|
playerId: "player-789",
|
|
role: "player"
|
|
}
|
|
});
|
|
|
|
// Listen for game start (only once)
|
|
useEffect(() => {
|
|
if (!gameRoom.connection) return;
|
|
|
|
const handleGameStart = () => {
|
|
console.log('Game has started!');
|
|
setGameStarted(true);
|
|
};
|
|
|
|
gameRoom.connection.once('gameStarted', handleGameStart);
|
|
}, [gameRoom.connection]);
|
|
|
|
// ...rest of component...
|
|
}
|
|
```
|
|
|
|
### Removing Event Listeners
|
|
|
|
Use the callback returned from `.on()` to remove event listeners:
|
|
|
|
```tsx React @nocheck
|
|
import { useState, useEffect } from "react";
|
|
import { useActor } from "./rivetkit";
|
|
|
|
function ConditionalListener() {
|
|
const [isListening, setIsListening] = useState(false);
|
|
const [messages, setMessages] = useState<string[]>([]);
|
|
|
|
const chatRoom = useActor({
|
|
name: "chatRoom",
|
|
key: ["general"]
|
|
});
|
|
|
|
useEffect(() => {
|
|
if (!chatRoom.connection || !isListening) return;
|
|
|
|
// Add listener
|
|
const unsubscribe = chatRoom.connection.on('messageReceived', (message) => {
|
|
setMessages(prev => [...prev, message.text]);
|
|
});
|
|
|
|
// Cleanup - remove listener when component unmounts or listening stops
|
|
return () => {
|
|
unsubscribe();
|
|
};
|
|
}, [chatRoom.connection, isListening]);
|
|
|
|
// ...rest of component...
|
|
}
|
|
```
|
|
|
|
## Debugging
|
|
|
|
- `GET /inspector/connections` shows active connections and connection metadata.
|
|
- Use this to confirm clients are connected before expecting broadcasts.
|
|
- `GET /inspector/summary` provides connections, RPCs, and queue size in one response.
|
|
- In non-dev mode, inspector endpoints require authorization.
|
|
|
|
## More About Connections
|
|
|
|
For more details on actor connections, including connection lifecycle, authentication, and advanced connection patterns, see the [Connections documentation](/docs/actors/connections).
|
|
|
|
## API Reference
|
|
|
|
- [`RivetEvent`](/typedoc/interfaces/rivetkit.mod.RivetEvent.html) - Base event interface
|
|
- [`RivetMessageEvent`](/typedoc/interfaces/rivetkit.mod.RivetMessageEvent.html) - Message event type
|
|
- [`RivetCloseEvent`](/typedoc/interfaces/rivetkit.mod.RivetCloseEvent.html) - Close event type
|
|
- [`UniversalEvent`](/typedoc/interfaces/rivetkit.mod.UniversalEvent.html) - Universal event type
|
|
- [`UniversalMessageEvent`](/typedoc/interfaces/rivetkit.mod.UniversalMessageEvent.html) - Universal message event
|
|
- [`UniversalErrorEvent`](/typedoc/interfaces/rivetkit.mod.UniversalErrorEvent.html) - Universal error event
|
|
- [`EventUnsubscribe`](/typedoc/types/rivetkit.client_mod.EventUnsubscribe.html) - Unsubscribe function type
|
|
|
|
_Source doc path: /docs/actors/events_
|