Abstract class representing a Rivet Actor. Extend this class to implement logic for your actor.
Actor(config?: Partial<ActorConfig>)
This constructor should never be used directly.
Constructed in Actor.start.
Represents the actor's state, which is stored in-memory and persisted automatically. This allows you to work with data without added latency while still being able to survive crashes & upgrades. Must define _onInitialize
to create the initial state. For more details, see the State Documentation.
Represents the parameters passed when a client connects to the actor. These parameters can be used for authentication or other connection-specific logic. For more details, see the Connections Documentation.
Represents the state of a connection, which is initialized from the data returned by _onBeforeConnect
. This state can be accessed in any actor method using connection.state
. For more details, see the Connections Documentation.
Sets the current state.
This property will automatically be persisted.
_connections: Map<ConnectionId, Connection<this>>
Gets the map of connections.
_kv: Kv
Gets the KV state API. This KV storage is local to this actor.
_log: Logger
Gets the logger instance.
_broadcast<Args extends Array<unknown>>(name: string,...args: Args,): void
Broadcasts an event to all connected clients.
_onBeforeConnect(opts: OnBeforeConnectOptions<this>): ConnState | Promise<ConnState>
Called whenever a new client connects to the actor. Clients can pass parameters when connecting, accessible via opts.parameters
.
The returned value becomes the connection's initial state and can be accessed later via connection.state
.
Connections cannot interact with the actor until this method completes successfully. Throwing an error will abort the connection.
_onConnect(connection: Connection<this>): void | Promise<void>
Executed after the client has successfully connected.
Messages will not be processed for this actor until this method succeeds.
Errors thrown from this method will cause the client to disconnect.
_onDisconnect(connection: Connection<this>): void | Promise<void>
Called when a client disconnects from the actor. Use this to clean up any connection-specific resources.
_onInitialize(): State | Promise<State>
Hook called when the actor is first created. This method should return the initial state of the actor. The state can be access with this._state
.
Hook called after the actor has been initialized but before any connections are accepted. If the actor crashes or is upgraded, this method will be called before startup. If you need to upgrade your state, use this method.
Use this to set up any resources or start any background tasks.
_onStateChange(newState: State): void | Promise<void>
Hook called whenever the actor's state changes. This is often used to broadcast state updates.
_runInBackground(promise: Promise<void>): void
Runs a promise in the background.
This allows the actor runtime to ensure that a promise completes while returning from an RPC request early.
_saveState(opts: SaveStateOptions): Promise<void>
Forces the state to get saved.
This is helpful if running a long task that may fail later or when running a background job that updates the state.
start(ctx: ActorContext): Promise<void>
Called by Rivet runtime to start a new actor. This class must use export default
in order to be called automatically.
This should never be used directly.