Singleplayer game in AS2

From GatchaWiki

Jump to: navigation, search

Contents

Getting started

What you need to create Actionscript 2.0 games for Gatcha:

  • Actionscript 2.0 knowledge.
  • Adobe Flash CS3 or Flash CS4.
  • The Gatcha AS 2.0 swc library which can be downloaded here.

This article covers:

  • Setting up your project for Gatcha game development in Actionscript 2.0.
  • All API calls to-from the wrapper.
  • Basic game security against hackers.

How it works

Gatcha games for Actionscript 2.0 are loaded inside a flash player 10 wrapper that manages the calls to the Gatcha API for you. Communication with this wrapper works through LocalConnection. Calls are made from the game.swf to the wrapper.swf through a custom Gatcha class which is provided in the library. Listeners can also be added to listen for callbacks that are sent by the wrapper.swf. The swc library containing this class can be downloaded here.

Downloads

Including the class library inside Flash CS3

You cannot link an swc to a project in Flash CS3, but there is a component bundle available which you can install and has the same result.

File:AddGatchaComponentCS3Folder.jpg

Extract the contents of the zip to C:\Program Files (x86)\Adobe\Adobe Flash CS3\<installation language>\Configuration\Components on Windows (64bit) or /Applications/Adobe Flash CS3/Configuration/Components on Mac OS X. A folder Gatcha will be created at that location. This folder contains the GatchaAS2Library.swc file. After a restart of the Flash IDE, you will find a Gatcha folder in your components view with the required component. Drag this component on your stage and it will automatically be added to the library.

File:AddGatchaComponentCS3.jpg

Available classes

Upon installation, the following classes are available: 

    com.gatcha.api.GameEvent (Class)

This is a class containing static variables of the calls that can be made to the wrapper. Use the static variables to avoid making typos. 

    com.gatcha.api.GatchaAS2Connector (Singleton)

This is the class that will be used to communicate with the wrapper swf through LocalConnection. 

    com.gatcha.api.Translations (Singleton)

This class can be used to easely access copy translations for your game (if available) 

    com.gatcha.memory.SafeAS2Memory (Singleton)

This Class must be used to store all your sensitive data (scores,lives,levels,bonus values,configurations...). This is a countermeasure against memory hacking.

Initializing the GatchaAS2Connector class

Before you start sending calls to the wrapper, the GatchaAS2Connector needs to be connected. It also needs to know on which object the callback functions need to be applied. Call the initialize function of the GatchaAS2Connector and pass the object that will listen for callbacks. Example: Execute the line below in the class that holds the callback functions 

GatchaAS2Connector.instance.initialize(this);

Callbacks from the wrapper to the game

Before you start sending calls to the wrapper, you should setup callback functions that will listen for the response of the wrapper.swf. The callbacks will return extra data or errors when needed. As such, the wrapper.swf will call functions in the object that you specified in the initialize function, so make sure those functions are public!

SINGLEPLAYER_START_GAME 

public function onSingleplayerStartGame(success:Boolean, data:Object):Void {}

This function is fired if the API confimed the game has been started. check the success parameter if the call was valid or an error occured. See the data object for the requested data or more info if an error occured.

SINGLEPLAYER_END_GAME 

public function onSingleplayerEndGame(success:Boolean, data:Object):Void {}

This function is fired if the API confimed the game has ended. check the success parameter if the call was valid or an error occured. See the data object for the requested data or more info if an error occured.

SINGLEPLAYER_UPDATE_HIGHSCORE 

public function onSingleplayerUpdateHighscore(success:Boolean, data:Object):Void {}

This function is fired if the API confirmed the score was saved. check the success parameter if the call was valid or an error occured. See the data object for the requested data or more info if an error occured.

WRAPPER_PAUSE 

public function onWrapperPause(paused:Boolean, data:Object):Void {}

This function is fired when the wrapper shows or hides the pause screen. Check the paused parameter to see if the wrapper is showing the pause screen or not.

ACHIEVEMENT_REACHED 

public function onAchievementReached(success:Boolean, data:Object):Void {}

This function is fired if the API confirmed achievement was reached. check the success parameter if the call was valid or an error occured. See the data object for the requested data or more info if an error occured.

GET_ACHIEVEMENTS 

public function onGetAchievements(success:Boolean, data:Array):Void {}

This GameEvent is fired when the list of achievements was loaded. check the success parameter if the call was valid or an error occured. See the data Array for the requested data or more info if an error occured.

PUT_PERSISTENT_STORAGE 

public function onPutPersistentStorage(success:Boolean, data:Object):Void {}

This GameEvent is fired when the PUT_PERSISTENT_STORAGE call returns from api. check the success parameter if the call was valid or an error occured. See the data object for the requested data or more info if an error occured.

GET_PERSISTENT_STORAGE 

public function onGetPersistentStorage(success:Boolean, data:Object):Void {}

This GameEvent is fired when the GET_PERSISTENT_STORAGE call returns from api. check the success parameter if the call was valid or an error occured. See the data object for the requested data or more info if an error occured.

DELETE_PERSISTENT_STORAGE 

public function onDeletePersistentStorage(success:Boolean, data:Object):Void {}

This GameEvent is fired when the DELETE_PERSISTENT_STORAGE call returns from api. check the success parameter if the call was valid or an error occured. See the data object for the requested data or more info if an error occured.

Sending events to the wrapper through the GatchaAS2Connector class

The calls that can be sent to the wrapper are defined in the GameEvent class as constants. Each call is defined below:

SINGLEPLAYER_START_GAME 

GatchaAS2Connector.instance.dispatch(GameEvent.SINGLEPLAYER_START_GAME);

This call starts a singleplayer game session and must be dispatched before starting the gameplay. If this call is not executed, scores cannot be saved. This will most likely be dispatched after a click on a "Start game" button inside the game's main menu screen. Listen for the callback before starting game logic!

SINGLEPLAYER_END_GAME 

GatchaAS2Connector.instance.dispatch(GameEvent.SINGLEPLAYER_END_GAME);

This call will end the current game session. All dispatched calls after this will return errors. A new startGame must be dispatched to start playing again. This call will most likely be dispatched when the game is over. You can also create a "play again" button that will call the startGame event again to start another game.

SINGLEPLAYER_UPDATE_HIGHSCORE 

GatchaAS2Connector.instance.dispatch(GameEvent.SINGLEPLAYER_UPDATE_HIGHSCORE, scoreToSend);

This call updates the score of a player for this particular game and this particular game session. A score of 0 is ignored and will not be sent by the wrapper swf. You will get a fail callback stating that scores of 0 are invalid. You can pass an integer as a score to save, or if you are using our supplied SafeAS2Memory Class, you can pass the String which contains the location of the score. Remember to dispatch the update score call before the end game call!

WRAPPER_LOG_THIS 

GatchaAS2Connector.instance.dispatch(GameEvent.WRAPPER_LOG_THIS);

This will cause the String that is send with this event to be appended to the log for this particular game session.Everytime a player plays a game, a log is generated, this is a anti-cheating measure. Logs can then later be viewed and show information about how the player played that particular game. It is important to only send vital information about the gameplay in a short format to be logged.

WRAPPER_PAUSE 

GatchaAS2Connector.instance.dispatch(GameEvent.WRAPPER_PAUSE);

This will make the wrapper.swf overlay a Pause screen, which has buttons for unpausing. This screen overlays the entire game, so there is no need to create an unpause screen for your game since it will not be visible. Make sure to pause your game logic when you receive the WRAPPER_PAUSED GameEvent.

ACHIEVEMENT_REACHED 

GatchaAS2Connector.instance.dispatch(GameEvent.ACHIEVEMENT_REACHED);

This tells the wrapper an achievement has been unlocked for this game. A popup overlay will be displayed showing the icon and specified information about the unlocked achievement. Achievement calls should always be executed even if that user has already unlocked that achievement. The wrapper checks who has achieved what. Pass a data object as 2nd parameter with following properties:

  • achievement:String Required key identifier of the achievement. This should be a unique name.
  • title:String Required Required textual represantion of the achievement. This should be a short identifier for the achievement that was reached. eg. "Coin Collector"
  • description:String Required textual representation of the achievement. This explains what the player did to reach this achievement. eg. "Collected 100 gold coins."
  • category: Optional textual identifier of the category the achievement is in. Can be used for filtering when fetching achievements. eg. Campaign achievements, Time-trial achievements, Survivor achievements, etc...
  • icon: Optional URL to an icon serving as a visual representation of the achievement. When no icon is provided, the default Gatcha icon will be shown.
  • data: JSON encoded array of key-value pairs specific to this user's achievement. This data array will be used to evaluate the title and description parameters for a title and description specific to the user-achievement combination.

GET_ACHIEVEMENTS 

GatchaAS2Connector.instance.dispatch(GameEvent.GET_ACHIEVEMENTS);

This asks the wrapper for an Array of achievement objects that were unlocked for this game by the player.

PUT_PERSISTENT_STORAGE 

GatchaAS2Connector.instance.dispatch(GameEvent.PUT_PERSISTENT_STORAGE, storageData);

Saves data in the persistent storage. The GameEvent takes an object with following properties:

  • key:String Unique id to store the given data and will be used to retrieve or delete the data. This may only contain alphanumeric (A-Za-z0-9) characters, underscore(_), dot(.) or dash(-).
  • value:String The value that will be stored. You can use Base64 to encode non-string data as a String.

GET_PERSISTENT_STORAGE 

GatchaAS2Connector.instance.dispatch(GameEvent.GET_PERSISTENT_STORAGE, key);

Fetches data for a certain key from the persistent storage. The GameEvent takes a String as parameter:

  • key:String This should be one of the keys that was specified in a GET_PERSISTENT_STORAGE api call.

DELETE_PERSISTENT_STORAGE 

GatchaAS2Connector.instance.dispatch(GameEvent.DELETE_PERSISTENT_STORAGE, key);

Removes previously stored data from the persistent storage for a certain key. The GameEvent takes a String as parameter:

  • key:String This should be one of the keys that was specified in a DELETE_PERSISTENT_STORAGE api call.

Configuring translations for your game

Through the instance of the Translations singleton, you can access the translations of the messagebundle. Do note that these are only available when your game is loaded into the wrapper .Translations can be read out, but will be turn out "{Missing <translationskey>}" if not available.

A messagebundle is a xml file with following syntax (Messagebundle documentation): 

<messagebundle>
    <msg name="labelScore">Points</msg>
    <msg name="labelLife">Lifes</msg>
    <msg name="labelStart">Start the game!</msg>
</messagebundle>

Each name should be unique for that messagebundle whereas the value between the msg tags is the translations for that key.

Accessing the translations for your game

Use the Translations class in the GatchaAS2Library. Translations that cannot be loaded will always return a string "Missing <key>" with the key you specified.

Translations.instance.getString(key):String returns a translation for the specified key 

txtScore.text = Translations.instance.getString(labelScore);

Translations.instance.exists(key):Boolean returns true or false if the translation exists. You can use this to set a default language if the translation could not be loaded 

(Translations.instance.exists(labelScore) ? txtScore.text = Translations.instance.getString(labelScore) : txtScore.text = "Score";

Encrypting valuable game data against hackers

Cheating in Flash games can be very easy. We have erected several countermeasures to try and withhold some forms of hacking. One of the most common ways for players to cheat is memory hacking. To prevent this, the library provides a SafeAS2Memory class which will encrypt all the given variables in the memory, to stop easy memory readouts. As a general rule: Never store sensitive data in class variables or constants!

Saving a numeric value 

    SafeAS2Memory.instance.setValue("score", 100);

Reading a numeric value 

    SafeAS2Memory.instance.getValue("score");

Operators on numeric values

Instead of reading out values, performing operations on it and saving the value again, there are some functions available that do that for you 

    SafeAS2Memory.instance.incrementValue("score",1);
    SafeAS2Memory.instance.decrementValue("score",1);
    SafeAS2Memory.instance.multiplyValue("score",10);
    SafeAS2Memory.instance.divideValue("score",2);
Retrieved from "http://wiki.gatcha.com/index.php/Singleplayer_game_in_AS2"
Personal tools