> For the complete documentation index, see [llms.txt](https://tivet.gitbook.io/tivet-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://tivet.gitbook.io/tivet-docs/build-with-actors/create-and-manage-actors.md).

# Create & Manage Actors

***

### Actor tags <a href="#actor-tags" id="actor-tags"></a>

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)`](https://jsr.io/@rivet-gg/actor-client/doc/~/Client.prototype.get)
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 <a href="#common-tag-patterns" id="common-tag-patterns"></a>

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

Party CodeChat&#x20;

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

***

### Client <a href="#client" id="client"></a>

Clients are used to connect & manage actors.

To create a new client, write:

```
import { Client } from '@tivet-gg/actor-client';
const client = new Client(/* CONNECTION ADDRESS */);
```

Documentation

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!');
```

Documentation

Explicitly 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();
```

Documentation

Connects to an actor based on its ID.

It's recommended to use tags instead of using actor IDs directly.

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 <a href="#options" id="options"></a>

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

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

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

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

***

### Shutdown actor <a href="#shutdown-actor" id="shutdown-actor"></a>

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