Gift giving AVRG (ActionScript tutorial)

ActionScript Tutorial
Create a smiple gift-giving AVR game using AS3.
Difficulty Level
Intermediate
Requirements
ActionScript 3.0, Whirled SDK
Other Information

This tutorial contains step-by-step directions for creating an AVR game to use as a gift or souvenir dispenser. You will need to have created an item to use as a gift.

Gift dispenser games that are not actual games are not eligible for the Bling Pool. Keep them as "Hidden" under the genre selection.

Prerequisites

Set up Java and Ant - If you're using Windows, you won't need Ant.
Set up the Flex SDK and the debug Flash player
Download and test the Whirled SDK

Set Up Your New Game

Windows

To create your new game, go to the Whirled SDK directory and double click on the the newproject.bat file to run it.

If this is the first time you are using the SDK, it will ask you to configure the directory of your Flex SDK and your Flash Standalone Player. A dialog box will pop up allowing you to specify that information and then you will proceed to creating your new project.

<actionscript>Unable to locate tools.jar. Expected to find it in C:\Program Files\Java\jre6\lib\tools.jar Buildfile: build.xml

prepare-flex:

    [copy] Copying 1 file to C:\whirled\etc
    [copy] Copying 1 file to C:\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 </actionscript>

Don't worry if you get that tools.jar error, it does not affect anything.

Next, you will be asked to name your project:

<actionscript>[newproject] Please enter the name of your AVRG project. [newproject] For example, BestAVRGEver: GiftGame</actionscript>

Then you will confirm the new project name: <actionscript>[newproject] Your main class will be called: [newproject] GiftGame.as [newproject] Is this OK? [y/n] y </actionscript>

and the tool will do the rest for you: <actionscript>[newproject] Creating 'giftgame\build.xml'. [newproject] Creating 'giftgame\build.bat'. [newproject] Creating 'giftgame\GiftGame.as'. [newproject] Creating 'giftgame\Server.as'. [newproject] Done! Your new project has been created in 'giftgame'.

BUILD SUCCESSFUL Total time: 5 minutes 10 seconds Press any key to continue . . . </actionscript>

Your new project will have been created in the Whirled SDK directory in a subdirectory named giftgame. You will find the file GiftGame.as in that directory.

UNIX and Mac

To create your new game, change to the whirled directory and run the ant newgame task:

  % cd whirled
  % ant newgame

If this is the first time you are using the SDK, it will ask you to configure the directory of your Flex SDK and your Flash Standalone Player. A dialog box will pop up allowing you to specify that information and then you will proceed to creating your new project.

Next, you will be asked if you want to employ a server agent for your game (the url it provides is to here and explains how to use server agents): <actionscript>newgame: [newproject] Whirled games can optionally employ a server agent. This is [newproject] recommended for multi-player games, but is more complicated to [newproject] write. For more information, see: [newproject] [newproject] http://wiki.whirled.com/Server_agent [newproject] [newproject] Do you want your game to employ a server agent? [newproject] Enter [y/n]: y</actionscript> Next, you will be asked to name your project:

<actionscript>[newproject] Please enter the name of your Game project. [newproject] For example, BestGameEver: GiftGame

[newproject] Your main class will be called: [newproject] GiftGame.as [newproject] Is this OK? [y/n] y</actionscript>

and the tool will do the rest for you: <actionscript>[newproject] Creating 'giftgame/build.xml'. [newproject] Creating 'giftgame/GiftGame.as'. [newproject] Creating 'giftgame/Server.as'. [newproject] Done! Your new project has been created in 'GiftGame'. </actionscript>

Your new project will have been created in the directory giftgame. You will find the file GiftGame.as in that directory.

Build a First Version to Upload

To compile it in UNIX or Mac, run ant at the command prompt:

For Windows, simply double click build.bat.

This will produce two output files called GiftGame.swf and GiftGame.abc in the same directory.

Note: For Windows users, using build.bat will show an error about "test-avrg", but it won't affect anything and it will still generate the needed .swf and .abc files. If you don't want to see that error, you should install Apache Ant by following the instructions here and use ant in the command line prompt in your giftgame directory instead of build.bat.

Upload Your GiftGame

The game doesn't do anything, but you should upload it so you can prepare some other things.

In Whirled, proceed to Games → My Games. Click the Create button to get the game uploading interface.

The game uploading interface.
1. Select In-Whirled Game.
2. Under Game Name, type "Gift Game"
3. Under Thumbnail Media, click Browse..., and select your image file. This thumbnail is used to represent the game in My Games and is the icon that shows up over players' avatars and in the room icon bar.
4. Under Client Code, click Browse..., and select your GiftGame.swf file in the file system browser that appears. When the file has finished uploading, you should see a SWF id show up (e.g. 031c99dbf403923daad884fb562bd7f0d83d555x.swf) in the Client Code section.
5. Confirm that you own the copyrights to the item or have authorization to upload it.
6. Click on the Save button and your browser will switch to the Edit Game interface where you can configure your game.

Fill in the tabs with the appropriate values:

Info Tab
    Name: Gift Game (or whatever name you want to give it)
    Genre: Hidden
    Description: Enter a description of your gift game.
    Group: Choose the Group to associate with the game (or none).
    Screenshot: For now, this will have to stay blank.

Code Tab
    Server Agent Code: Select your "GiftGame.abc" file.

Save your changes.

Create the Required Game Items

There are a few other things you need to create that are associated with your game for it to work as a gift giver.

Create a Launcher

You will need to create a launcher for your game as well:

Choose Games → My Games to see the Games you own.
Click the Edit link for your Gift Game.
Select the "Launchers" tab.
Click on the "Create" button to get the launcher creation interface.

Launcher interface.
1. Click on the Name field and enter a name for your launcher. Something like Gift Game will be fine.
2. Click Upload a new file in Furniture Media and find the image or SWF file for your launcher. This is what will be seen in the room when a player adds it there.
3. Click Upload a new file in Thumbnail Media and find the bitmap (png, jpg or gif; max. 80x60) file for your launcher's icon. This will be shown in the shop and in the Stuff tab of players who have the launcher.
4. Click on the Description field and enter a description of your launcher. This is only required if you plan to sell it in the shop.
5. Confirm that you own the copyrights to the item or have authorization to upload it.
You can then click on Save to put your launcher in your inventory for use.

Create a Trophy

You'll need a trophy to associate with your gift if you want to limit it to one gift per player.

Choose Games → My Games to see the Games you own.
Click the Edit link for your Gift Game.
Select the "Trophy Sources" tab.
Click on the "Create" button to get the trophy source creation interface.

Trophy source interface.
1. Click on the Name field and enter a name for your trophy. This is the name that is displayed under the trophy image on a player's trophy page.
2. Click on the Identifier field and enter an identifier for your trophy. This string is used to identify this trophy in your game code. For this tutorial, you should just pick something that describes the trophy you want to give, such as trophyone.
3. Click on the Order field and enter a number. This number will be used to sort your trophies into a particular order on your game's detail page, lowest to highest.
4. Check Secret if you wish for the description the trophy to not be shown until the player has earned the trophy themself.
5. Click Upload a new file in Trophy Image and find the image file for your trophy (png, jpg or gif; max. 60x60). This is the image that will be seen on the player's trophy page when they win it.
6. Click on the Description field and enter a description of your trophy. This is only required if you plan to sell it in the shop.
7. Confirm that you own the copyrights to the item or have authorization to upload it.
You can then click on Save to add your trophy source to the Trophy Sources tab.

Next, you will need to activate the trophy by publishing it. Click on "view" for the trophy and click on the "List Item" link so it is added to the Shop. The trophies will not be visible items in the Shop. This makes the trophy accessible to the game.

Create a Prize

Your gift will need to be added to the game as a prize. First, you need to upload an item that will be your prize. List the item in the shop (can be hidden) and take note of the item's shop ID (http://www.whirled.com/#shop-l_5_347 has 347 as its shop ID). The item that is used as a prize needs to be uploaded & listed by you.

Choose Games → My Games to see the Games you own.
Click the Edit for your Gift Game.
Select the "Prizes" tab.
Click on the "Create" button to get the prize creation interface.

Prize creation interface.
1. Click on the Name field and enter a name for your prize.
2. Click on the Identifier field and enter an identifier for your prize. This string is used to identify this prize in your game code. For this tutorial, you should just pick something that describes the gift you want to give, such as prizeone.
3. Use the dropdown menu in Prize Type to indicate what type of item your prize is. It can be: Avatar, Furniture, Backdrop, Toy, Pet, Launcher, Level Pack, Item Pack, Image, Audio, Video, or Prop.
4. Click on the Prize Shop ID field and enter the shop ID number. For example, http://www.whirled.com/#shop-l_5_347 has 347 as its shop ID.
5. Confirm that you own the copyrights to the item or have authorization to upload it.
You can then click on Save to add your prize to the Prizes tab.

Once all the desired prizes have been created, the prizes should be shown on the Trophy Sources tab. You will need to click "View" for each prize and "List item" in order to publish them so they are accessible by your game. The prizes will not be visible items in the Shop.

Change the Game to Award the Trophy & Prize

Now that you have created your trophy and prize with associated identifiers, you can code them into your game. Open the server.as file and replace the code in there with:

<actionscript> //

     // $Id$
     //
     // The server agent for GiftGame - an AVR game for Whirled

     package {

     import com.whirled.ServerObject;
     import com.whirled.avrg.AVRServerGameControl;
     import com.whirled.avrg.*;

     /**
      * The server agent for GiftGame. Automatically created by the
      * whirled server whenever a new game is started.
      */
     public class Server extends ServerObject
     {
         /**
          * Constructs a new server agent.
          */
         public function Server ()
         {
             _control = new AVRServerGameControl(this);
             trace("souvinerAVRG server agent reporting for duty!");

             _control.game.addEventListener(AVRGameControlEvent.PLAYER_JOINED_GAME, tryGiveStuff);
            
             function tryGiveStuff(event:AVRGameControlEvent) :void {
                 var player:PlayerSubControlServer = _control.getPlayer(event.value as int);
                
                 if (!player.holdsTrophy("trophyone")) {
                     player.awardTrophy("trophyone");
                     player.awardPrize("prizeone");
                 }
             }
         }

         protected var _control :AVRServerGameControl;
     }

</actionscript>

Save your changes to the Server.as file.

Build Your Updated Game

Now you need to build a new copy of your game and update it in Whirled.

To compile it in UNIX or Mac, run ant at the command prompt:

For Windows, simply double click build.bat.

This will produce two new copies of the output files called GiftGame.swf and GiftGame.abc in the same directory.

Note: For Windows users, using build.bat will show an error about "test-avrg", but it won't affect anything and it will still generate the needed .swf and .abc files. If you don't want to see that error, you should install Apache Ant by following the instructions here and use ant in the command line prompt in your giftgame directory instead of build.bat.

Choose Games → My Games to see the Games you own.
Click the Edit link for your Gift Game.
Select the "Code" tab.
Click the browse button next to "Client Code" and upload the new copy of GiftGame.swf.
Click the browse button next to "Server Agent Code" and upload the new copy of GiftGame.abc.
Click on the save button to save your changes.

Test Your Gift Game

Check and see if your gifting game works:

Choose Games → My Games to see the Games you own.
Click on the orange Play button for your Gift Game.

If you get the trophy and the prize, your game works! You can add the launcher to a room to give away your gift now.

Gift giving AVRG (ActionScript tutorial)

Contents

Prerequisites

Set Up Your New Game

Windows

UNIX and Mac

Build a First Version to Upload

Upload Your GiftGame

Create the Required Game Items

Create a Launcher

Create a Trophy

Create a Prize

Change the Game to Award the Trophy & Prize

Build Your Updated Game

Test Your Gift Game

Other Links

Navigation menu

Gift giving AVRG (ActionScript tutorial)

Prerequisites

Set Up Your New Game

Windows

UNIX and Mac

Build a First Version to Upload

Upload Your GiftGame

Create the Required Game Items

Create a Launcher

Create a Trophy

Create a Prize

Change the Game to Award the Trophy & Prize

Build Your Updated Game

Test Your Gift Game

Other Links

Navigation menu

Search