SDK Application Structure

A typical SDK application has the following organization:

1. Initialization
   1. Call aw_init to initialize the API
   2. Call aw_event_set to install event handlers
   3. Call aw_create to create one or more instances
   4. Call aw_login for each instance to log that instance into Active Worlds
   5. Call aw_enter for each instance to enter that instance into a world
2. Event Loop
   1. Call aw_wait and respond to events
3. Shut Down
   1. Call aw_destroy to destroy each instance
   2. Call aw_term to shutdown the API

Applications do not necessarily need to follow this structure. However all applications must call aw_init before calling any other API methods and call aw_create at least once in order to create an instance.

An instance refers to a single login session within Active Worlds. Each session has a single connection to the universe server as well as an additional optional connection to a single world server. For example, each time you run the Active Worlds Browser it creates one instance for your login session. A single instance can only be at a single location in a single world at any one time, however an SDK application can create and manage many instances at once.

Instances are allocated and initialized for the application by aw_create, and are destroyed by aw_destroy. Applications that only use a single instance (the "typical" case) are the easiest to write and do not need to worry about storing or managing the instance handle that is returned by aw_create. Applications that use multiple instances need to keep track of the instance handles returned by aw_create and must use aw_instance_set to specify which instance each particular operation is intended for.

Example: Botware Inc. wants to have two bots in their world stationed at two different locations, but which share common knowledge of which users have spoken to which bot. Botware implements their bots using a single SDK application which calls aw_create, aw_login, and aw_enter twice, once for each bot.

An instance must have an owner. An owner is the Active Worlds citizen who owns and is responsible for the instance. The owner is identified during the call to aw_create by his or her citizen number and privilege password. Keep in mind that a single citizen can only have a limited number of bot instances running in the universe at any one time (typically the limit is 3 although it can be adjusted by the universe administrator.) The instance owner's citizen number is used to determine permissions and object ownership (if the SDK application builds objects) as if the instance were a regular citizen. Note that an owner does not need to be logged in in order for his or her bots to run.

Example: Botware Inc. would like their bots to be able to modify signs in their world to point to different advertisers, but they don't want the public to be able to build in their world. To do this, they have their bots log in as owned by citizen Botware, who has build rights in their world according to the world options.

Note that SDK applications are neither citizens nor tourists, they are a separate class of Active Worlds user. Typically, we just refer to them as "bots."