AVR game

Read everything and still stuck? Try the FAQ.

What is an AVRG?
Instead of a game that takes over the whole screen, AVRGs are games that take place in Whirled rooms. Imagine playing hide n' seek inside a Whirled room, or a game that involves exploring the rooms of the Whirled. It's like an MMO in Whirled.

Still don't get it? Try playing some of the AVRGs that we've created. (The links below will take you to the rooms the games are installed in, once there, just click the furniture associated with the game)
 * Bella Bingo (instructions)
 * Ghosthunters (instructions)
 * Pookah Rainbow (instructions)

Technical Explanation
AVRG stands for "Alternative Virtual Reality Game". This is a play on words derived from "Alternative Reality Game" or ARG. This is a game that takes place in your "real life" via phone calls, physical clues etc. An AVRG takes place within the "real world" of Whirled, which is virtual, hence the pun.

Unlike a "lobbied" or "seated" game, an AVR game takes place in a room and players continue to see their avatars and other surroundings during the game. All user interface elements are shown as an overlay on top of the rest of the room. Because dealing with rooms and avatars is vastly more complicated than the relatively isolated user interface of a lobbied game, the AVR game API is much bigger.

Lobbied games do not require a server agent to work, whereas AVR games do. This is partially due to the benefit of hindsight: we learned from experience that when creating a client-only game, it was extremely complicated to cope with disconnections and nigh on impossible to manage latency. Using a server agent eliminates many intractable problems but also opens the door to other complexities.

We are hoping some day to make AVR games even more full-featured, allowing them to control more aspects of the user experience such as the scale of the room and the user interface surrounding the main panel.

Examples
Three Rings have produced three AVR games at the time of this writing, you can try them out in Whirled. You have to click on the furniture to play:
 * Bingo (Source Code)
 * Ghosthunters (Source Code)
 * Pookah Rainbow (Source Code)

Create an empty project
In order to start making an AVRG, you need to download the SDK and create a new AVRG project. Run  on Windows, or run   in the SDK root directory using a shell prompt (general documentation on how to set up your development environment can be found on the SDK page). You will be prompted for the name of your project, here's some sample output: Buildfile: build.xml

prepare-flex: [copy] Copying 1 file to /export/whirled/dist/sdk/whirled/etc [copy] Copying 1 file to /export/whirled/dist/sdk/whirled/etc

newproject: [newproject] What type of project would you like to create? [newproject] 1 - Avatar [newproject] 2 - Game [newproject] 3 - Pet [newproject] 4 - Furni [newproject] 5 - Toy [newproject] 6 - Backdrop [newproject] 7 - AVRG [newproject] Enter the number [1-7]? 7 [newproject] Please enter the name of your AVRG project. [newproject] For example, BestAVRGEver: MyFirstAVRG [newproject] Your main class will be called: [newproject]  MyFirstAVRG.as [newproject] Is this OK? [y/n] y [newproject]  Creating 'myfirstavrg/build.xml'. [newproject]  Creating 'myfirstavrg/build.bat'. [newproject]  Creating 'myfirstavrg/MyFirstAVRG.as'. [newproject]  Creating 'myfirstavrg/Server.as'. [newproject] Done! Your new project has been created in 'myfirstavrg'.

BUILD SUCCESSFUL Total time: 7 seconds

Build the project
Then go into the new directory and build the game using  on Windows or running   from a shell prompt. If there are any errors, chances are it is due to errors in your dev environment configuration. Check the SDK page for detailed instructions.

If all goes you well, you should see two new files in the game directory. The .swf file is the client code and will be downloaded by a Whirled user that chooses to play your AVR game. This is usually done by clicking a piece of furniture in a room that you create, though users can also buy a copy of your game and put it in other rooms. The .abc file contains your agent and will be downloaded and executed by the Whirled server's action script interpreter.

Upload to www.whirled.com
Unlike lobbied games, there is no builtin test environment for AVRGs. So the next step is to upload an in developement version of your game. Details on using the game upload page can be found here. For AVRGs, you must do the following:
 * Select "AVRG" in the "Game Type" menu
 * Upload your .abc file in the "Server Agent" file box
 * Type in your server class name if you are using a package or some other class name besides "Server". This step is not necessary for uploading a newly created AVRG project.

Once the game is uploaded, go to a room that you own and place the game in your room using the "Stuff" tab above the flash window and clicking on games. Since you just created it, it should be at the beginning of the list. Click "Add to room" and close the stuff panel using the small "x" in the top right corner. You should now be able to click the new furniture icon in the room. Your avatar should get a game icon over its head and you should see a small version of the icon in the toolbar.

Change, test, debug - the endless cycle
After getting started with a new, empty project, its time to start developing! Make changes to the project code, graphics and sound and follow the above steps to re-upload new versions and test it. At some point, you may need to invite some friends to your room to help test it out.

Debugging the server agent can be tricky. Just like for lobbied games, the server records all of your calls to the builtin actionscript "trace" function. However, AVRGs do not have the well-defined concept of a single "game". Therefore, the server stores the logs periodically. For an in-development the game, this is done every couple of minutes. So you can try something in your game, then visit the "Logs" tab on the game info page to see what the trace output was. See here to find your logs.

Attach to a group and release
AVR games are intrinsically tied to rooms. If you click on the big "PLAY" button for Bella Bingo for example, it takes you to the Bella hallway. Before releasing (i.e. listing) your game, you need to create a group to showcase the game and place your game furniture at various spots in the group. Once you've created the group, attach it to your game in the game editing page (same as the game upload page). Now when a user wants to "PLAY" your game, they will be directed to the main room of the group.

Now the game is ready to list. It will then appear on the games page for everyone to see.

Updating after a release
You will almost certainly want to make changes to your game after it is released. In order to do this, you just re-list the current in-development version of the game. The biggest difference is that now your game is more publicly visible and therefore there may be some people enjoying the game when you want to replace the code. Whenever a game is changed, all current players will be abruptly evicted and the server agent will restart, so be careful. (Yes, this is on our wish list of things to improve).

The API
You can find the full API docs here on the whirled website.

As mentioned before, AVR games require a server component and a client component. Therefore the API is split along those lines and there are two top level controls (as opposed to lobbied games which just have one top-level control and some special methods in various places).

Your client-side .swf will instantiate AVRGameControl to communicate with the Whirled client and server code.

Your server agent .abc file will instantiate AVRServerGameControl to communicate with the Whirled server code and the clients of you game.

Server-only and client-only functionality
Some features and functionality in the API are available only to the server agent and others are available only to clients. To model this, the API representation of some of the controls are divided into 3 classes each. One base class for shared methods, a subclass for client-only methods and another subclass for server-only methods:

Game control
Client: ctrl.game

Server: ctrl.game

The  member allows the client and server to access the AVR game's own private property space. The client has read-only access the the server has read-write access.

Level and item packs are accessed through the  control. These are uploaded and assigned to a game just like they are for lobbied games.

The server agent may send messages via the game control as well as listen for events when a player joins and leaves the game. Unlike lobbied games, the game keeps right on going as players come and go. In fact, the server agent only shuts down if no one has been playing the game for a certain period of time.

When the server agent sends a message, all players in the game will receive the message if they listen for the event . Use game-wide messages with care.

Player control
Client: ctrl.player

Server: ctrl.getPlayer(playerId)

Note that the client only has access to one player, the local player, while the server can access any player that's in the game. Trying to access any other player will result in an error.

The  member allows the client and server to access the private property space of a player. Both client and server have write access.

Using the methods in the player control, your game can detect the presence of a player trophy, access item packs and level packs and cause avatars to perform actions, change state or move to a new location.

Use the completeTask method to award coins to a player and the deactivateGame method when the player has finished playing, for example pressing the quit button in the UI.

The server agent may also send a private message to a specific player. The client is notified of the message by listening for message events on the player control.

Room control
Client: ctrl.room

Server: ctrl.getRoom(roomId)

Note that clients only have access to the current room occupied by the local player, while server agents can access any room in the game. Any attempt to access a room not in the game results in an error.

The  member allows the client and server to access the room's property space that is private to this game. Clients may read the properties and the server agent may read and write.

The client and server use the room control to access the set of players that are in the room and listen for notifications when players enter and leave. The may also receive notifications when an avatar changes state or location or when a MOB has been spawned.

The server agent may also use the room control to spawn and despawn MOBs and send messages to all the players in a room. Clients can receive the message by listening for the event on the room control.

MOB control
Client: ctrl.room.getMobSubControl(id)

Server: ctrl.getRoom(roomId).getMobSubControl(id)

See Mobs for more information.

The server agent can spawn and despawn mobs using the. A record of the mob is stored on the Whirled server and once the mob is created the control becomes available.

Both the client and the server use the MOB control to detect appearance changes.

The server may also move the MOB to a new location.

The client may access the underyling display object (that it creates via the ), set and remove a decoration or change the hot spot.

Local control
Client: ctrl.local

Server: N/A

The local control contains various methods that only make sense for the client. They are mostly to do with display objects and pixel coordinates.

It is important that games using MOBs provide a callback for creating mob sprites using setMobSpriteExporter.

Game that use non-rectangular interfaces should also provide a callback for pixel hit tests using setHitPointTester so that the room interface that appears behind the game can still intercept clicks.

Agent control
Client: ctrl.agent

Server: N/A

The agent control allows the client to send messages to the server agent. The server agent received messages by listening for the event on the game control.

Property Spaces
All property spaces in the Whirled API work the same way, allowing plain actionscript  instances to be assigned to named slots and also providing   and   for optimally setting a single element in a container. Read-only access to a property space is provided by PropertyGetSubControl and write access by PropertySubControl Any property reader can also listen for property changes and element changes on the props control.

In the AVRG API, properties are embedded in the object they represent using a  member. The type of the member determines whether the caller can read only or both read and write.