Wizard Fu's Cocos2dx Platformer Game Engine v1.0.1


See the file LICENSE for the license governing this code.

The Game object. It derives from cocos2d::Application and responds to messages like applicationDidFinishLaunching. Static methods provide singleton-like access to the game state, localized strings, current player index and save games. It also run scripts by filename or string.

#pragma once
#include "Headers.h"

class Game : public Application
		virtual ~Game();

Implement cocos2d::Application‘s methods

		virtual bool applicationDidFinishLaunching();
		virtual void applicationDidEnterBackground();
		virtual void applicationWillEnterForeground();

Localized strings

Localized strings are loaded from the Strings.plist (XML format) asset file. The player’s language code is used as a key to access the appropriate strings.

The custom property list file Strings.plist is used instead of platform-specific methods like using Xcode’s Localizable.strings in order to keep the game platform-independent.

Get a localized string.

		static string getLocalizedString(const string& key);

Player index

Each player can be refered to by index. In single-player mode, there is one player and a player index of 0 is used. In multiplayer mode, there can be more than one player and the current local player index may be not necessarily be 0.

Get / set the local player’s index (0 if single player).

		static int getMyPlayerIndex();
		static void setMyPlayerIndex(int);

Clear all player indices.

		static void clearPlayerIndices();

Get / set a player’s index given player id.

		static int getPlayerIndex(const string& playerId);
		static void setPlayerIndex(const string& playerId, int playerIndex);

Save games

Game state is saved using key-value pairs. The cocos2d::UserDefault class is used to save the pairs to the preferences. On Mac and iOS, UserDefault uses NSUserDefaults.

Each save game is referred to by a save game index. When setting a save game key-value pair, the save game index is prepended to each key. For example, setting key currentLevel with save game index 0 will actually save the key save0.currentLevel.

You can edit save game data by hand as needed. On Mac OS X this data is cached so you’ll need to use the defaults command to edit. (Trying to edit a save game file by hand will not work unless one kills the cfprefsd process).

Read preferences using your game’s bundle identifier like this:

defaults read com.mycompany.mygame

Write a preference like this:

defaults write com.mycompany.mygame save0.currentLevel "0-4"

On other platforms, the save game data is usually stored to UserDefault.xml in the user’s documents folder.

Set the save game index. Usually this is done from the game’s main menu.

		static void setSaveGameIndex(int);

Get / set a save game key value. Values are stored entirely as strings. Use Kit::stringWithFormat or a stringstream to convert integer, floating point and other data to a string. Use parseInt, parseFloat, parseVector and other functions from Kit.h to parse strings into the desired data types.

		static string getSaveGameKeyVal(const string& key);
		static void setSaveGameKeyVal(const string& key, const string& val);

Areas and levels

The game world is organized into areas. Areas subdivide into levels. The asset file World.plist describes the game’s areas and levels. The Level class uses World.plist to build the game’s overall world, areas and generate or load a TMX tiled map level.

Get / set / reset the current area and level.

		static void getCurrentLevel(int& areaNum, int& levelNum);
		static void setCurrentLevel(int areaNum, int levelNum);
		static void resetCurrentLevel();

Get / set previous area and level.

		static void getPreviousArea(int& area, int& level);
		static void setPreviousArea(int area, int level);

Random seed

The random seed is used to seed the random number generator before the areas and levels are generated. Using a deterministic random number generator, this means that given a certain random seed, let’s say 123, the current area and level will be generated the same on any device, as long as integers are used instead of floating points.

The random seed also affects the generation of dynamic textures. Given a seed, the textures should look the same.

Get / set the random seed

		static unsigned getRandomSeed();
		static void setRandomSeed(unsigned);


Javascript can be used and it has nearly 100% of the same cocos2dx API access as the C++ code does. The script is precompiled and performs well because it uses C++ objects behind the scenes. It is even possible to write a cocos2dx game entirely in javascript.

Access to custom functions and objects can be provided via javascript bindings. See the file GameScripting.cpp for a few custom-built javascript bindings. Bindings are created to provide access to the Game’s previous area and level, for example.

Lua can also be used. It is part of cocos2dx and available, but no Lua bindings have yet been implemented for this platformer game engine.

Initialize the scripting engine.

		static void initScripting();

Run a script string.

		static void runScript(const string& script);

Run a script file.

		static void runScriptFile(const string& filename);

Add a callback function to be called when a callback event is triggered.

		static void addCallback(const string& event, const callbackType& func);

Trigger a callback event.

		static void triggerCallback(const string& event);


Launch the multiplayer dashboard.

		static void showMultiplayerDashboard();

Return true if a multiplayer match is in session.

		static bool isMultiplayer();


Physics engines can work in meters. Return how many pixels are in a physics meter.

		static float getPixelsPerMeter();

Return the scale needed for the game’s fonts.

		static float getFontScale();

Dpad, position

		static const Vec2& getDpadPos();
		static const Vec2& getAbButtonPos();
		typedef Application super;
		typedef Game self;