SDK Multiple Instances

The Active Worlds SDK can support multiple simultaneous instances. This means it is possible to write an SDK application that creates and manipulates dozens or even hundreds of bots at once. The only practical limit on the number of instances is the limit on the number of bots that a citizen can have running in the universe at one time.

Each call to aw_create returns a separate instance handle. Multi-instance applications should save this handle and pass it back to the SDK via aw_instance_set before calling any method, to indicate which instance the call is for.

The Current Instance

At any given moment, one instance is always the current instance. In multi-instance applications, the current instance is changing constantly, in response to calls to the API and also in response to events. At any given time the application can query the current instance by calling aw_instance, and change the current instance by calling aw_instance_set. All API methods operate on the current instance, which means a multi-instance application must typically call aw_instance_set before any other method in order to indicate which instance the call is for.

Example

The code sample below demonstrates how an application might create three different bots at once and have each bot introduce itself. Error checking code has been removed for clarity.

#define LOGIN_OWNER 1
#define LOGIN_NAME "mybot"
#define LOGIN_PASSWORD "myprivpass"
#define ENTER_WORLD "myworld"
#define N_INSTANCES 3

void* instances[N_INSTANCES];
int i;
char buf[256];

for (i = 0; i < N_INSTANCES; i++)
{
  aw_create (NULL, 0, &instances[i]);

  aw_int_set (AW_LOGIN_OWNER, LOGIN_OWNER);
  sprintf (buf, "%s %d", LOGIN_NAME, i);
  aw_string_set (AW_LOGIN_NAME, buf);
  aw_string_set (AW_LOGIN_PRIVILEGE_PASSWORD, LOGIN_PASSWORD);
  aw_login ();

  aw_enter (ENTER_WORLD);
  aw_state_change ();
  aw_wait (0);
}

for (i = 0; i < N_INSTANCES; i++)
{
  aw_instance_set (instances[i]);
  sprintf (buf, "Hello, I'm bot #%d", i);
  aw_say (buf);
}