Create & Manage Actors

This guide will walk through creating & managing Rivet Actors.

Actor tags

Tags are simple key-value pairs attached to every actor. Tags serve two purposes:

1. Actor Discovery: Find specific actors using client.get(tags, opts)
2. Organization: Group actors for monitoring & administration purposes

When choosing tags, follow these best practices:

• Keep values short and concise
• Use consistent naming patterns
• Avoid storing sensitive information

The name tag is required and specifies which type of actor to spawn.

Common tag patterns

The following examples show different ways tags can be used to organize actors:

// Connect to a game server using a party code
const gameServer = await client.get<GameServer>({
  name: 'game_server',
  partyCode: 'ABCDEF'
});

Client

Clients are used to connect & manage actors.

To create a new client, write:

import Client from '@rivet-gg/actor-client';
const client = new Client(/* CONNECTION ADDRESS */);

client.get(tags, opts)

client.get(tags) attempts to find an existing actor matching the provided tags. If no matching actor is found, it creates a new one with those tags.

const room = await client.get<ChatRoom>({
  name: 'chat_room',
  // Get or create the actor for the channel `random`
  channel: 'random'
});

// This actor will have the tags: { name: 'chat_room', channel: 'random' }
await room.sendMessage('Hello, world!');

client.create(opts)

To explicitly create a new actor, use client.create(tags). This will create a new actor with the provided tags.

// Create a new document actor
const doc = await client.create<MyDocument>({
  create: {
    tags: {
      name: 'my_document',
      docId: '123'
    }
  }
});

await doc.doSomething();

client.getWithId(id, opts)

Each actor has a unique identifier that can be used instead of tags. To get an actor by its ID, use client.getWithId(id).

It's recommended to use tags instead of using actor IDs directly (e.g. see docId above).

For example:

// Get the actor with the given ID
const myActorId = '55425f42-82f8-451f-82c1-6227c83c9372';
const doc = await client.getWithId<MyDocument>(myActorId);

await doc.doSomething();

Options

opts.parameters

All client methods accept a parameters property. This can be used to pass information about the current connection, such as authentication tokens or usernames.

For example:

const actor = await client.get<Example>(
  { name: 'example' },
  {
    parameters: { authToken: 'supersekure' }
  }
);

This is available on client.get, client.create, and client.getWithId.

Read more about parameters & connections here.

opts.create.tags

When creating an actor, you can specify additional tags beyond those used for querying. If opts.create.tags is not provided, the query tags will be used. For example:

const actor = client.get<MyDocument>(
  // Tags used to find the actor
  {
    name: 'my_document',
    document_id: 'budget_2024'
  },
  {
    create: {
      // Tags assigned if a new actor is created
      tags: {
        name: 'my_document',
        workspace_id: 'team_alpha',
        document_id: 'budget_2024'
      }
    }
  }
);

This is available on client.get and client.create.

opts.create.region

By default, actors are created in the region with the lowest latency for the client. You can override this by specifying create.region:

const actor = client.get(
  { name: 'example' },
  {
    create: {
      region: 'atl'
    }
  }
);

This is available on client.get and client.create.

opts.noCreate

To prevent creating a new actor if it does not exist, pass the noCreate option. For example:

// Get the actor, do not create
const doc = await client.get<MyDocument>({ name: 'my_document', docId: '123' }, { noCreate: true });

await doc.doSomething();

This is available only on client.get.

Shutdown actor

For security reasons, actors must be shut down from within the actor itself using this._shutdown(). For example:

export default class Example extends Actor {
  // client will call this rpc to shut down actor
  myShutdownRpc(rpc: Rpc<Example>) {
    this._shutdown();
  }
}

Read more about the actor lifecycle.