Multiplayer game in AS3 with Smartfox

From GatchaWiki

Jump to: navigation, search

Contents

Getting started

What you need to create multiplayer Actionscript 3.0 games for Gatcha:

  • Actionscript 3.0 knowledge for client side programming.
  • Actionscript 1.0 or Java knowledge for server side programming.
  • Installed and configured Smartfox server for local development. (Free version is available and will do just fine)
  • Adobe Flash CS3 or CS4.
  • The Gatcha swc library which can be downloaded here.
  • The Smartfox Actionscript 3.0 library which can be downloaded here. Both a swc library and source code is available.

This article covers:

  • Setting up your project for Gatcha multiplayer game development in Actionscript 3.0.
  • All Multiplayer API calls to and from the wrapper.

This article does not cover:

  • Installing and configuring the SmartFox Server. Have a look at the Smartfox Documentation.
  • Documentation about SmartFox API. Again; Smartfox Client API Documentation and SmartFox AS1 Server Documentation.

How it works

As with Gatcha singleplayer games, the game is also loaded inside another flash container, and communication still works the same way through the Flash Event system. These events are also in the GameEvent class which is at your disposal when you download and install the Gatcha swc library. Connecting, logging in, room creation and room management with Smartfox is all handled by the wrapper (except during local development!). If you are familiar with Smartfox, you know that all calls with the Smartfox server go through the SmartFoxClient class. This class is instantiated by the wrapper and you can ask for a reference to that client through the Gatcha API. Basicly all you need to worry about is listening & dispatching the right SmartFox events and Gatcha GameEvents.

A game must also have a room extension which will be instantiated on the SmartFox server each time a game room is created. This extension is required even if you do not wish to program game logic on the server. However we recommend that you use it to store the current status of the game and score to avoid synchronization bugs between the connected clients. You can also update the score of the game to the Gatcha api from there. It is also possible to do this from the game client though. It's not possible to create a zone extension for your game as it is in use by the wrapper. You can choose to write your room extension either in Actionscript 1.0 or Java.

As said, the wrapper connects and logs in the player automatically. The player is put inside a "Lobby" room. This is a non game room where all players are gathered when they are not playing or waiting for a game to start. From there, they can either join/start a public room or create a private room which is only accessible through invites from people inside the room. Once the player joins/creates a room, the wrapper overlays a screen showing some information about the current game room; Who is ready to play and who can be invited to join. Once the creator of the room decides to start the game (or automatically when the room is full) the screen fades away to show the game swf. After the game is over, a "play again" GameEvent can be dispatched to show the overlay again and start a new game.

File:WrapperWaitingScreen.jpg

Downloads

Including the class library inside Flash CS3 or Flash CS4

Explained here. You can install the SmartFox swc exactly the same way.

Sending events to the Gatcha game API through Flash Events

If you are not familiar with the GameEvent class for the wrapper, have a look at the Singleplayer documentation.

Getting the SmartFoxClient instance

MULTIPLAYER_GIVE_SMARTFOXCLIENT

This event request the SmartFoxClient instance from the wrapper. Remember to only dispatch this event if the game is loaded inside the wrapper. If you are developing locally, you have to instantiate your own SmartFoxClient instance, connect with your local SmartFox server, login, create a new room, and join that room. Yes, the whole nine yards... Have a look at the example on how to do that. 

dispatchEvent(new GameEvent(GameEvent.MULTIPLAYER_GIVE_SMARTFOXCLIENT));

Auto search a public room

MULTIPLAYER_JOIN_AWESOME_ROOM

This event is a request to join a public room. The server will look for the best room currently available for that player. If none can be found, a new empty room is created. 

dispatchEvent(new GameEvent(GameEvent.MULTIPLAYER_JOIN_AWESOME_ROOM));

Exiting a game

MULTIPLAYER_JOIN_LOBBY

This event is a request to join the lobby and thus leaving a game room. The wrapper has a "leave" button implemented but you can use this event to gain the same result from inside the game. 

dispatchEvent(new GameEvent(GameEvent.MULTIPLAYER_JOIN_LOBBY));

Creating a private room

MULTIPLAYER_CREATE_ROOM

This request creates a game room on the SmartFox server. Pass on the room details in the data property as an Object with following properties:

  • name:String A unique name for a room. Tip: Use the creator's user id or the current time to create a unique name.
  • password:String A password is required if you create a private room. Inviting other players is handled by the wrapper so you don't need to worry about that.
  • minUsers:int The minimum amount of players required to be able to start a game. When this number of players is reached, the wrapper will show a "start" button and the creator of that room will have the choice to start the game or wait for more players.
  • maxUsers:int The maximum amount of players for the game. When this number is reached, the wrapper shows the "start" button and will count down from 10s. Upon reaching 0, the game will be started automatically.
  • maxSpectators:int The number of spectators that can join this game room. 
dispatchEvent(new GameEvent(GameEvent.MULTIPLAYER_CREATE_ROOM, roomProperties));

Posting a ranking

MULTIPLAYER_UPDATE_RANKINGS

This event is dispatched to update the result of a game round. Actual scores are never posted, but instead a ranking (position) of the players is sent to the server by setting an Array with the player's gatcha id's in the GameEvent's data property. There are 2 ways to update rankings:

  1. An update is sent each time a player is killed or has lost during the game:
    1. Example: After 10seconds in the game player 1 is killed. The GameEvent is dispatched with data property set to [player1's gatcha id]. After 40 seconds, the 2nd player's gatcha id is sent, and so on until all player id's have been sent.
  2. A complete ranking table is sent at the end of the game.
    1. Example 1: At the end of a game Player 3 finishes first, then Player 1 and Player 2 is last, you would send an Array: [Player3, Player1, Player2]
    2. Example 2: At the end of a game Player 2 has finished first, Player 1 and 4 are tied on position 2 and player 3 is the last one. You would send an Array that looks like this: [Player2,[Player1,Player4], Player3] 
dispatchEvent(new GameEvent(GameEvent.MULTIPLAYER_UPDATE_RANKINGS, rankingsArray));

You can also update the rankings via the Room extension by sending an internal request to the zone extension in Actionscript: 

var zone = _server.getCurrentZone();
var targetExtension = zone.getExtension("zoneExtension");
targetExtension.handleInternalRequest({command:"extensionUpdateRatings", room:_server.getCurrentRoom(), rankings:[player1ID, player2ID]});

Ending a game

MULTIPLAYER_END_GAME

This event has to be dispatched when the game ends. It notifies the wrapper and resets certain components if the user wishes to play again. 

dispatchEvent(new GameEvent(GameEvent.MULTIPLAYER_END_GAME));

Play again

MULTIPLAYER_PLAY_AGAIN

This event is dispatched if the player(s) wish to play another game. The wrapper overlays a screen and waits for the minimum amount of players to be connected and ready before it can start another round. 

dispatchEvent(new GameEvent(GameEvent.MULTIPLAYER_PLAY_AGAIN));

Callback events from the wrapper to the game

If you are not familiar with callbacks from the wrapper, have a look at the Singleplayer documentation.

Callback for MULTIPLAYER_GIVE_SMARTFOXCLIENT

MULTIPLAYER_GIVE_SMARTFOXCLIENT_RESULT

This is the event that is dispatched by the wrapper to the game. The data property contains the SmartFoxClient instance. 

addEventListener(GameEvent.MULTIPLAYER_GIVE_SMARTFOXCLIENT_RESULT, giveSmartFoxClientResultHandler);

Callbacks for MULTIPLAYER_JOIN_AWESOME_ROOM

MULTIPLAYER_JOIN_AWESOME_ROOM_RESULT

This event is the callback when the request to join a public room was successful. 

addEventListener(GameEvent.MULTIPLAYER_JOIN_AWESOME_ROOM_RESULT, joinAwesomeRoomResultHandler);

MULTIPLAYER_JOIN_AWESOME_ROOM_FAIL

This event is the callback when the request to join a public room was not successful. see data property for more information. 

addEventListener(GameEvent.MULTIPLAYER_JOIN_AWESOME_ROOM_FAIL, joinAwesomeRoomFailHandler);

Callbacks for start game

This is dispatched when the room creator decides to press the start button in the wrapper.

MULTIPLAYER_START_GAME_RESULT

This callback event is sent from the wrapper when a game has been started. Starting a game is handled by the wrapper when all players are in the game room and ready to play. Start your game logic after this event has been dispatched. 

addEventListener(GameEvent.MULTIPLAYER_START_GAME_RESULT, startGameResultHandler);

MULTIPLAYER_START_GAME_FAIL

This callback event is sent from the wrapper when the game could not be started. This can be used to show a error screen that the game could not be started at this time. 

addEventListener(GameEvent.MULTIPLAYER_START_GAME_FAIL, startGameFailHandler);

Callbacks for MULTIPLAYER_END_GAME

MULTIPLAYER_END_GAME_RESULT

This callback is sent when the game was successfully ended. 

addEventListener(GameEvent.MULTIPLAYER_END_GAME_RESULT, endGameResultHandler);

MULTIPLAYER_END_GAME_FAIL

This callback is sent when the game could not be ended. See the data property for more information. 

addEventListener(GameEvent.MULTIPLAYER_END_GAME_FAIL, endGameFailHandler);

Get information about a player from the SmartFox User variables

Gatcha has information about players stored inside the User object variables. You can access these variables through the User.getVariable function. These are the properties you can access when the game is loaded inside the wrapper:

  • gatcha_nickname:String The nickname of the player.
  • gatcha_id:String The id of the player which has to be used to update rankings!
  • gatcha_isLeader:Boolean If the current user is the leader of the room or not.
  • gatcha_profile_url:String Url to the player's profile page.
  • gatcha_avatar_url:String Url to the player's avatar.
  • gatcha_language:String 2 letter code of the player's language.

You can also access these variables through the SmartFoxUserVars class constants inside the Gatcha game library.

Be sure to check out the global GameEvents for the wrapper such as pause, achievements in the singleplayer documentation.

Retrieved from "http://wiki.gatcha.com/index.php/Multiplayer_game_in_AS3_with_Smartfox"
Personal tools