Magic Scrolls of Code

State Machines By Example: A Useful FSM

2012-02-13T12:26:00.001+01:00

Introduction

A finite state machine is a highly useful tool for programmers in general and for video game programmers in particular. If you’re not familiar with the notion, think about the Finite State Machine (FSM) as a GameBoy, and the States as different cartridges or games.

The GameBoy can only have one game running at any time (or no game at all, in which case it’s not very useful). Obviously, all cartridges share some characteristics (shape, connection pins, etc.…) that allow the GameBoy to interact with any game without knowing or caring what it actually does, just plug it in and it works.

There is one last, important, characteristic that defines this system. Each “game” or state has the rules to decide when to change to another different game (this kind of fucks up the metaphor, but I could not find any better).

So, code-wise, this would be a system as follows:

The FSM has one state active, which it updates every cycle. At any moment, the FSM can be told to change to a different state. All states inherit from the State class, and have a common interface so the FSM doesn’t need to know what they do internally, just call the appropriate functions.

FSM

A classic FSM pseudo-code has a structure as follows:

Code Snippet
 class FSM
{
    // Current state the FSM uses
    State* currentState;
 
    // Calls the Update function of 
    // the currentState
    Update();
 
    // Calls exit of the currentState
    // sets newState as currentState
    // call enter of currentState
    ChangeState(State * newState);
};
 

State

And a base state pseudo-code has the following structure:

Code Snippet
 class State
{
    // Pointer to the parent FSM
    FSM* fsmReference;
 
    // Called when the state is initialized
    // by the FSM
    public virtual void Enter();
 
    // Called when the state is ended by the
    // FSM
    public virtual void Exit();
 
    // Called every update cycle by the FSM
    protected virtual void Update();
}
 

Actual states are not instantiated, only derived states (in our example ShootEnemy, Defend, etc. )

Making it Useful

This basic FSM has several problems or shortcomings that limit it’s use, so let’s have a look at some of them.

Changing State at the Proper Time

Problem

The main flaw the basic FSM pattern has is the fact that at any moment, the current state can request the FSM to change to a different state. When this happens, the following steps take place:

CurrentState->Exit();
CurrentState = NewState;
CurrentState->Enter() // This is the new state

If the fsmReference->ChangeState() call was in the middle of the the Update function, this can leave the state in an undefined state, and propagate errors later on.

Solution

We shall make a request mechanism in the FSM, instead of changing the state, we will request the FSM to change to a state, and the FSM after the state update will change to a different state. For this we replace the ChangeState function for a RequestoReplaceState, and a DoStateReplacement.

Check this pseudo-code for a clearer idea:

Code Snippet
 class FSM // With delay state change
{
private:
    // Current state the FSM uses
    State* currentState;
 
    // Temporal pointer to the new state
    State* newState;
 
    // Flag indicating wheter to change state
    bool requestedStateChange;
 
    // Calls the Update function of 
    // the currentState
    void Update();
 
    // If a requested state pending, 
    // change to new state
    void DoStateReplacement();
 
    // Calls exit of the currentState
    // sets newState as currentState
    // call enter of currentState
    void RequestReplaceState(State * newState);
};
 
void FSM::Update() 
{
    if(requestedStateChange)
    {
        DoStateReplacement();
    }
    else if(this.currentState != null)
    {
        currentState->Update();
    }
}
 
void FSM::RequestReplaceState(SinState newState)
{
    nextState = newState;
    requestedStateChange = true;
}
 
void FSM::DoStateReplacement()
{
    if(nextState == null)
    { return; }
    
    requestedStateChange = false;
 
    if(currentState != null)
    { currentState->Exit();    }
    
    currentState = this.nextState;
    nextState = null;
    
    currentState->Enter();
}
 

Push & Pop

Problem

Now we have a FSM that won’t inadvertently introduce subtle ninja bugs when we’re not looking, and can replace the current state for another. But we want to add to the FSM the ability of when we change to a state, to push the current state back into memory, to be popped later on. This might be useful for example in this scenario:

Guard.state = patrolling –> Hears sound
- Guard.state = goSeeDisturbance , PushBack( patrolling )
- Guard –> Doesn’t find anything in sound source. Pop ( goSeeDisturbance )
Guard.state = patrolling

Instead of destroying the patrolling state and then having to create it again, we just push it back, store it, and once the temporal state (goSeeDisturbance) is over, we resume patrolling.

Solution

To properly do this we need to add a pause functionality to our states. Notice a very important detail that is that the Pause / Update / Resume functions, overloaded in the base classes, are no longer called by the FSM but instead we have Manager functions (ManagerUpdate, ManagerPause, ManagerResume) that are called by the FMS, while derived classes (from State) just override the same version without the “Manager” part. This allows us to add some extra functionality to all Update / Pause / Resume calls of all derived classes. With this, we can implement pause / resume, by letting the user specify what is going to happen in his state when it pauses / resumes, while doing the maintenance work (setting flags and safety checks) in the manager version. Check the code for a clearer idea:

Code Snippet
 class State
{
    // Pointer to the parent FSM
    FSM* fsmReference;
 
    // Indicates whether the state is paused
    bool isPaused;
 
    // Overriden in base clases to put pause
    // logic
    protected virtual void Pause();
 
    // Overriden in base clases to put 
    // resume logic
    protected virtual void Resume();
 
    // Called when the state is initialized
    // by the FSM
    public virtual void Enter();
 
    // Called when the state is ended by the
    // FSM
    public virtual void Exit();
 
    // NOT CALLED BY FSM ANYMORE
    protected virtual void Update();
 
    // Called by the FSM every update 
    // cycle
    public void ManagerUpdate();
    
    // CAlled by FSM on pause
    public void ManagerPause();
 
    // Called by FSM on resume
    public void ManagerResume();    
}
 
 
void State::ManagerUpdate()
{
    if(!this.isPaused) 
    { this.Update(); }
}
    
void State::ManagerPause()
{
    this.isPaused = true;
    this.Pause();
}
    
void State::ManagerResume()
{
    this.isPaused = false;
    this.Resume();
}
 

And add a push & pop mechanism to the FSM, very similar to the replace mechanism, but we store the pushed state in a variable, to restore it later. This is only an example, so it’s not very useful. For it to be useful we would need a list of pushed states, because that would allow us to push and pop as much as we wanted.

Code Snippet
 class FSM
{
    // Current state the FSM uses
    State* currentState;
 
    // Calls the Update function of 
    // the currentState
    Update();
 
    // Calls exit of the currentState
    // sets newState as currentState
    // call enter of currentState
    ChangeState(State * newState);
 
    
    // Stores a pushed state. 
    // Make this->a list to store a pile of states.
    private State pushedState = null;
    
    
    // Indicates whether a new state push 
    // has been requested.
    private bool requestedStatePush
    
    
    // Indicates whether a new state pop has 
    // been requested.
    private bool requestedStatePop;
 
    void DoStatePop();
 
    void RequestStatePop();
 
    void DoStatePush();
 
    void RequestPushState(State newState);
};
 
void FSM::Update() 
{
    if(this->requestedStateChange)
    {
        this->DoStateReplacement();
    }
    else if(this->requestedStatePush)
    {
        this->DoStatePush();
    }
    else if(this->requestedStatePop)
    {
        this->DoStatePop();
    }
    else if(this->currentState != null)
    {
        this->currentState.ManagerUpdate();
    }
}
 
void FSM::RequestPushState(State newState)
{
    this->nextState = newState;
    this->requestedStatePush = true;
}
 
void FSM::DoStatePush()
{
    if(this->nextState == null)
    {
        Log.Write("ERROR! Attempting state push in null state");
        return;
    }
 
    if(this->currentState == null)
    {
        Log.Write("ERROR! Attempting state push back null state");
        return;
    }
    
    this->requestedStatePush = false;
    this->pushedState = this->currentState;
    
    this->pushedState.ManagerPause();
    
    this->currentState = this->nextState;
    this->nextState = null;
    
    this->currentState.SetWasPushed(true);
    this->currentState.Enter();
}
 
void FSM::RequestStatePop()
{
    this->requestedStatePop = true;
}
 
void FSM::DoStatePop()
{
    if(this->pushedState == null)
    {
        Log.Write("ERROR! Attempting state pop null state");
        return;
    }
    
    if(this->currentState != null)
    {
        this->currentState.Exit();
    }
    
    this->requestedStatePop = false;
    this->currentState = this->pushedState;
    this->pushedState = null;
    
    assert this->currentState != null;
    this->currentState.ManagerResume();
}
 

Timed Update

Last improvement we can add is a timed update, by simply passing a “update time” to each state constructor and making the State::ManagerUpdate keep track of it:

Code Snippet
 public void ManagerUpdate()
{
    if(!this->isPaused) 
    { 
        if(this->updatePeriod == 0 || 
                CurrentTime() - this->lastUpdateTime >= 
                this->updatePeriod)
        {
            this->Update();
            this->lastUpdateTime = CurrentTime();
        }
    }
}
 

The Code

It’s not “by example” if it doesn’t have an example, so here is a complete example in Java.

Finite State Machine

Code Snippet
 /**
 * State machine behavior to provided 
 * different decision states.
 * 
 * Supports push/pop and replace 
 * mechanisms. (Stack of only 1 stored state.)
 * 
 * Supports safe-state switch via request.
 * @author Ying
 *
 */
public class FSM
{    
    /**
     * Reference to current state.
     */
    private SinState currentState = null;
    
    /**
     * Reference to next state requested.
     */
    private SinState nextState = null;
    
    /**
     * Indicates whether a new 
     * state replace has been requested.
     */
    private boolean requestedStateChange = false;
    
    /**
     * Stores a pushed state. 
     * Make this a list to store a pile of states.
     */
    private SinState pushedState = null;
    
    /**
     * Indicates whether a new state push 
     * has been requested.
     */
    private boolean requestedStatePush = false;
    
    /**
     * Indicates whether a new state pop has 
     * been requested.
     */
    private boolean requestedStatePop = false;
 
    /**
     * Initializes a new instance of the StateMachine 
     * class.
     */
    public FSM() {}
 
    /**
     * Update the FSM, and the current state if any.
     */
    @Override
    public void action() 
    {
        if(this.requestedStateChange)
        {
            this.DoStateReplacement();
        }
        else if(this.requestedStatePush)
        {
            this.DoStatePush();
        }
        else if(this.requestedStatePop)
        {
            this.DoStatePop();
        }
        else if(this.currentState != null)
        {
            this.currentState.ManagerUpdate();
        }
    }
    
    /**
     * Request to change the current state to a new one. 
     * Request will be stored till FSM update.
     * @param newState New state to change to.
     */
    public void RequestReplaceState(SinState newState)
    {
        this.nextState = newState;
        this.requestedStateChange = true;
    }
 
    /**
     * Do the actual state replace.
     */
    private void DoStateReplacement()
    {
        String prev = "Null";
        String next = "Null";
        if(this.nextState == null)
        {
            Log.Write("ERROR! Attempting state replacement to null state");
            return;
        }
        
        next = this.nextState.name;
        this.requestedStateChange = false;
        if(this.currentState != null)
        {
            this.currentState.Exit();
            prev = this.currentState.name;
        }
        
        this.currentState = this.nextState;
        this.nextState = null;
        
        assert this.currentState != null;
        this.currentState.SetWasPushed(false);
        this.currentState.Enter();
        Log.Write("STATE CHANGE: " + prev + " --> " + next);
    }
    
    /**
     * Request to push the current state to 
     * storage and run another one.
     * @param newState New state to run.
     */
    public void RequestPushState(SinState newState)
    {
        this.nextState = newState;
        this.requestedStatePush = true;
    }
    
    /**
     * Do the actual state push.
     */
    private void DoStatePush()
    {
        String prev = "Null";
        String next = "Null";
        if(this.nextState == null)
        {
            Log.Write("ERROR! Attempting state push in null state");
            return;
        }
        
        next = this.nextState.name;
        
        if(this.currentState == null)
        {
            Log.Write("ERROR! Attempting state push back null state");
            return;
        }
        
        prev = this.currentState.name;
        this.requestedStatePush = false;
        this.pushedState = this.currentState;
        
        this.pushedState.ManagerPause();
        
        this.currentState = this.nextState;
        this.nextState = null;
        
        assert this.currentState != null;
        this.currentState.SetWasPushed(true);
        this.currentState.Enter();
        Log.Write("STATE PUSH: " + prev + " --> " 
                + next + " [Pushed state: "+ 
                this.pushedState.name +"]");
    }
    
    /**
     * Request pop of current state and 
     * restoring of the pushed one.
     */
    public void RequestStatePop()
    {
        this.requestedStatePop = true;
    }
    
    /**
     * Does the actual pop.
     */
    private void DoStatePop()
    {
        String prev = "Null";
        String next = "Null";
        if(this.pushedState == null)
        {
            Log.Write("ERROR! Attempting state pop null state");
            return;
        }
        
        next = this.pushedState.name;
        
        if(this.currentState != null)
        {
            this.currentState.Exit();
            prev = this.currentState.name;
        }
        
        this.requestedStatePop = false;
        this.currentState = this.pushedState;
        this.pushedState = null;
        
        assert this.currentState != null;
        this.currentState.ManagerResume();
        Log.Write("STATE POP: " + prev + " --> " + next);
    }
}
 

State

Code Snippet
 /**
 * Base class for states.
 * Supports state pause.
 * @author Ying
 *
 */
public abstract class SinState 
{
    /**
     * Whether the state is paused.
     */
    protected boolean isPaused;
    
    /**
     * Update period of the state.
     */
    protected int updatePeriod;
    
    /**
     * Last update period.
     */
    private long lastUpdateTime;
    
    /**
     * Reference to the FSM
     */
    protected StateMachine FSM;
    
    /**
     * State name.
     */
    public String name;
    
    /**
     * Whether the state was pushed.
     */
    private boolean wasPushed;
    
    /**
     * Initializes an instance of the SinState class.
     * @param updatePeriod The time (in ms) between 
     *  each update. Set 0 for going as fast as possible.
     */
    public SinState(int updatePeriod, StateMachine FSM, String name) 
    {
        this.isPaused = false;
        this.updatePeriod = updatePeriod;
        this.lastUpdateTime = System.currentTimeMillis();
        this.FSM = FSM;
        this.name = name;
    }
    
    // Override functions
    public abstract void Enter();
    public abstract void Exit();
    protected abstract void Update();
    protected abstract void Pause();
    protected abstract void Resume();
 
    // Manager functions
    public void ManagerUpdate()
    {
        if(!this.isPaused) 
        { 
            if(this.updatePeriod == 0 || 
                    System.currentTimeMillis() - this.lastUpdateTime >= 
                    this.updatePeriod)
            {
                this.Update();
                this.lastUpdateTime = System.currentTimeMillis();
            }
        }
    }
    
    public void ManagerPause()
    {
        this.isPaused = true;
        this.Pause();
    }
    
    public void ManagerResume()
    {
        this.isPaused = false;
        this.Resume();
        this.lastUpdateTime = System.currentTimeMillis();
    }
    
    public void SetWasPushed(boolean pushed) 
    { this.wasPushed = pushed; }
    
    public boolean WasPushed() 
    { return this.wasPushed; }
}
 

Conclusion

Finite states machines are a very useful construct for controlling the flow of a game, how your game scene updates in different situations, how your character acts… It’s not a holly grail, all purpose solution, but it works surprisingly well for many scenarios.

Enjoy.

More advanced concepts of getting cocos2dx working on Android from Windows 7

2012-02-04T21:49:00.001+01:00

NOTE: This tutorial was done with cocos2d-1.0.1-x-0.9.1 and cocos2d-1.0.1-x-0.11.0, and so may not be 100% accurate for either version, or newer [Had to change version in the middle of development], but will serve as a general guideline for anyone using similar versions.

First Part: Quick and dirty guide to getting cocos2dx working on Android from Windows 7

Introduction

Working from the files we obtained in the first part, in this tutorial we shall cover:

Moving android-generated folder away from the cocos2d-x folder.
Add an extra library ( Chipmunk ).
Not having to use the Classes & Resources folders.

It’s important to use the proper editing tool for the files generated by the “create-android-project.bat”, because regular windows editors add extra symbols like “\r” that will confuse your Cygwin. I recommend Notepad++. A great editor that has the invaluable property of showing hidden symbols by doing: View -> Show symbol -> Show all characters.

Moving The Folder

I generated a new project FOLLOWING THE STEPS IN THE PART ONE OF THE TUTORIAL, let’s call it FVZ, using the following specs:

Package: com.companyname.fvz
Name: FVZ_2_3
Target ID: 13 (Android 2.3.3)

And copied it from the cocos2d-x folder where it’s generated by default, to the folder where my Visual Studio solution held all my code of the project I was working on. To make this work, I had to modify:

android/build_native.sh

GAME_ROOT=/cygdrive/d/All/Proyects/FVZ/Android/FVZ_2_3
( Set the path to where we have copied the project folder, and add the /cygdrive/ in front so Cygwin can use the path ).

android/jni/Android.mk

Modify project path: addprefix $(LOCAL_PATH)/../../../../FvZv2/ to point to the root folder of the cocos2dx instaltion (where you have all the cocos2dx code, ej: cocos2dx, CocosDenshion, tests, tools…

What this does is search for all the Android.mk (makefiles) of the libraries you are going to use. (Notice the addprefix & addsufix functions, to generate the full paths).

# Try to use LOCALPATH, otherwise you’ll have to play a bit with the path till you get it to Cygwin’s liking.

android/jni/helloworld

LOCAL_SRC_FILES: Add RELATIVE path to each code file (cpp / h) in your Visual Studio project folder. The start of my list is, for example:

LOCAL_SRC_FILES := main.cpp \
../../../../../FvZv2/FvZ/Classes/AppDelegate.cpp \
../../../../../FvZv2/FvZ/Classes/AppDelegate.h \
../../../../../FvZv2/FvZ/Classes/HelloWorldScene.cpp …

LOCAL_C_INCLLUDES: Change Classes path to the folder where you keep all your code, and set the paths for the different cocos folders so they point to the required folders.
LOCAL_LDLIBS: Point the $(LOCAL_PATH)/../../libs/$(TARGET_ARCH_ABI)) to the proper location (TARGET_ARCH_ABI is usually armeabi).

andoid/build_native.sh

Change GAME_ROOT so it points to the root of your game folder, in my case:
GAME_ROOT=/cygdrive/d/All/Proyects/FVZ/Android/FVZ_2_1

With all that your project should compile with no problems using Cygwin. As a special note, I made a java script to parse my Classes folder, to generate my LOCAL_SRC_FILES paths, as there where hundreds of files, in nested folders and so on. Sharing it here:

Code Snippet
 import java.io.File;
 
 
public class ListFiles 
{
    static String initialPath = "D:\\All\\Proyects\\FvZ\\FvZv2\\FvZ\\Classes";
 
    public static void main(String[] args) 
    {
        FileTreePrint("");
    }
    
    private static void FileTreePrint(String path)
    {
        String files;
        File folder = new File(initialPath + path);
        File[] listOfFiles = folder.listFiles(); 
 
        for (int i = 0; i < listOfFiles.length; i++) 
        {
            if (listOfFiles[i].isFile()) 
            {
                files = listOfFiles[i].getName();
                System.out.println("../../../../../FvZv2/FvZ/Classes"+ path.replace("\\", "/") + "/" +files+ " \\");
            }
        }
        
        for (int i = 0; i < listOfFiles.length; i++) 
        {
            if (listOfFiles[i].isDirectory()) 
            {
                FileTreePrint(path + "\\" +listOfFiles[i].getName());
            }
        }
    }
}
 

Adding Chipmunk to the Compilation

We need to modify some files, but it’s a straightforward process if we take another library (CocosDenshion) as a guideline.

android/jni/Android.mk

Add “chipmunk \” in the line under CocosDenshion/android.

android/jni/Application.mk

My APP_MODULES looks like:
APP_MODULES := cocos2d cocosdenshion chipmunk game

android/jni/helloworld

LOCAL_C_INCLLUDES: Add the path to the chipmunk folder that holds all the files, in my case:
$(LOCAL_PATH)/../../../../../FvZv2/chipmunk/include/chipmunk \
In LOCAL_LDLIBS add –lchipmunk

Lastly, there is one extra modification to be done, that took me quite a while. In the main java file of the .java files generated for your project (in my case FVZ_2_3.java) we need to search for where it does System.loadLibrary(), and add:

System.loadLibrary("chipmunk");

Automating the Process

The first thing you will notice with this system is that it’s SLOW. We have have to use the command line every time we want to compile, not to mention that this method copies all the resources of the game from the Resources folder to the assets one each time, which can be very time consuming.

So let’s optimize it a bit.

Making the resource load faster

Grab your build_native.sh and clean out all the logic for cleaning the resource folder, leaving it like this:

Code Snippet
 # set params
ANDROID_NDK_ROOT=/cygdrive/c/eclipse/android/android-ndk-r6b
GAME_ROOT=/cygdrive/d/All/Proyects/FVZ/Android/FVZ_2_1
GAME_ANDROID_ROOT=$GAME_ROOT/android
 
# build
$ANDROID_NDK_ROOT/ndk-build -C $GAME_ANDROID_ROOT $*
 

What is going to happen now is that you’re going to have to remember to manually copy each modified asset from your MVS project to the assets folder of the java project. A small price to pay for compiling in 10 seconds instead of 1 minute.

So go ahead and copy all your resources to the assets folder. Once you’re done…

One Click Process

I created a batch file to be called with a simple double click, that calls cygwin and gets the whole compilation process done. After double clicking on it you just need to refresh the java project in eclipse (F5) and hit “run” to have the game showing in your android. Here is the magical .bat:

Code Snippet
 C:\cygwin\bin\bash.exe -l '/cygdrive/d/All/Proyects/FvZ/Android/FVZ_2_1/android/build_native.sh' 
pause
 

Created this Compile.bat thanks to http://forums.techguy.org/windows-xp/424616-calling-unix-scripts-dos-script.html and http://old.nabble.com/Cygwin---batch-file-td15088393.html .

Conclusion

Now you should be able to put your folder wherever you damn well please, add other libraries to it and compile by:

Compiling in MVS by hitting F5 (to check it works)
Compiling in native code by double clicking Compile.bat
Running the game in android by hitting F5 in eclipse, and then “run”.

Tell me if it worked for you!

Quick and dirty guide to getting cocos2dx working on Android from Windows 7

2011-09-30T17:54:00.002+02:00

Second Part: More advanced concepts of getting cocos2dx working on Android from Windows 7

This guide builds on the official guide for setting up Cocos2d-x on the Android Phone with additional explanations in the sections where the original one is outdated, incomplete or ambiguous, so hopefully no one else has to make the same mistakes I did.

First a general overview of what has to happen to see your precious game on the android phone. You create a Visual Studio project from a cocos2dx template and set it up to work with cocos2dx. Once you've got your game running and ready to test on the phone, you use a .bat file provided in the cocos2dx download to create a default android project from the "HelloWorld" project it comes with. In this new folder it creates in the android root, you override the existing classes and resources with the ones from your project, and you make sure they are in the makefile. Then you use Cygwin to compile everything into native code, and finally you create a new android project in eclipse, import the code you compiled and hopefully have it work in the phone.

It's a non-trivial process, but not that hard either, and the people at Cocos2dx have made quite an effort to get this working as it is. So, step by step.

Step by Step

Step 1: Get all the android material

Download android sdk, install it and test it in eclipse. This is a well-documented process in the android sdk website.
If you have an Android phone to test on, set it up for development and try a test application in it.
Download the android ndk and extract it to a folder with no spaces in the path.

Step 2: Get all the cocos2dx material

Download the latest version of cocos2d-x and set it up for win32 development as stated here. Download Cygwin and make sure you mark the "Devel" branch as "Install" when you download it.

Step 3: Get the create-android-project.bat working

From the original tutorial:

To adapt to my environment, I change the settings in create-android-project.bat.
set _CYGBIN=C:\cygwin\bin
The path of cygwin bin
set _ANDROIDTOOLS=D:\anroid\android-sdk-windows\tools
The path of android sdk tools
set _NDKROOT=D:\anroid\android-ndk-r5b
The root of ndk

Step 4: Creating the project

Now we create our Cocos2d-win Application form the MVS templates. If this template is not available, go back and check you did step 2 correctly. You can create this project wherever you want. For the sake of brevity, let’s assume you are creating a Pong game, and aptly name your project “Pong”. While following the cocos2dx creation template unmark every cocos2d library except Simple Audio Engine in Cocos Denshion.

Next up we need to add 3 things to make the Pong project reach the cocos2dx files it needs. Include the source files, link the library files, and copy the dll files. To make this process easier create an environment variable with the root of your cocos2dx installation. I call mine COCOS2DX and it’s defined as C:\eclipse\android\cocos2d-1.0.1-x-0.9.1\cocos2d-1.0.1-x-0.9.1.

NOTE: If you modify this variable, or any other, and want to use it from visual studio, you need to restart visual studio.

Step 4.1: Include the source files

Inside Visual Studio, with your Pong project open, right click on the project and select Properties. At the top make sure you select “Configuration: All Configurations”, otherwise you’ll have to repeat the whole process for the each configuration you’ve got (usually just debug and release).
Go to C/C++ / General /Additional Include Directories, there your template should have 9 includes already. Something like this:

.;
.\win32;
.\Classes;
..\cocos2dx;
..\cocos2dx\include;
..\cocos2dx\platform;
..\cocos2dx\platform\third_party\win32\OGLES;
..\CocosDenshion\Include;
%(AdditionalIncludeDirectories)

The first 3 you can leave as-is, because they reference the project locally (including what’s in the project folder and in the win32 and classes folders. As you need these files, all is good. The next 5 however, all the ones that start with “..\cocos2dx”, assume you’re in the root cocos2dx folder. So we just correct this using our COCOS2DX environment variable.

.;
.\win32;
.\Classes;
$(COCOS2DX)\cocos2dx;
$(COCOS2DX)\cocos2dx\include;
$(COCOS2DX)\cocos2dx\platform;
$(COCOS2DX)\cocos2dx\platform\third_party\win32\OGLES;
$(COCOS2DX)\CocosDenshion\Include;
%(AdditionalIncludeDirectories)

To be honest, I don’t quite know what the AdditionalIncludeDirectories are, so I just leave it there.
With this however, your project knows where the cocos2dx files it needs are.

Step 4.2 : Adding the libraries

You need the .lib files that where created by compiling the cocos2d-win32.vc2010.sln, all the way back at step 2. We are going to store them locally for clarity, though you could just modify the linker path using our COCOS2DX variable.

In the Pong folder, next to the Classes and Resource folders, we create a Libs folder, and inside put two subfolders, Debug and Release.
Next we copy all the .lib files from our COCOS2DX/Debug.win32 and COCOS2DX/Release.win32 folders to the Debug and Release folders respectively.

Inside Visual Studio, with your Pong project open, right click on the project and select Properties. At the top make sure you select “Configuration: All Configurations”, otherwise you’ll have to repeat the whole process for the each configuration you’ve got (usually just debug and release).
Go to Linker / General / Additional Library Directories and you should find something like:

$(OutDir);
%(AdditionalLibraryDirectories)

We need to add the library path, so we make it:

$(OutDir);
$(SolutionDir)\Pong\Libs\$(Configuration);
%(AdditionalLibraryDirectories)

As long as you only have Debug and Release configurations this should work fine. Visual will go to Pong/Libs/Debug or Pong/Libs/Release and get the .lib files from there when needed. If you add more configurations, make sure to add the appropriate folder to Libs. If your project is not named Pong, modify the path accordingly.
Right now it should let you compile the project without errors but not run it. We’re missing the dlls.

Step 4.3: Adding dlls

First build your application both in release and in debug. This should create in your visual studio project debug and release folders with an executable called Pong.exe, and maybe a few other things.

Go back to the COCOS2DX/Debug.win32 and COCOS2DX/Release.win32 folders and fish out all the .dll files copying them to the Debug and Release folders in your Pong project folder respectively.
There. You should be able to build and run, seeing your project on a small window.

Step 5: Use the .bat to create an android project

This is pretty well covered in the original tutorial. Click the create-android-project.bat and fill out the package path (org.cocos2dx.Pong in our case) and the name (Pong) and finally the version to compile to (a list of versions should appear in screen).

NOTE: This step is irrelevant of your visual studio project, you don’t need to copy your Pong visual studio project to the cocos2dx root or anything. The .bat creates a folder all by itself.

Step 6: Fill in the meat

This is the step that really had me stumped until I asked in the forums. The .bat creates a new project based on the HelloWorld example in the root directory, so if you just run the bat and continue to the next step, in the end you’ll have the HelloWorld project in your phone instead of the Pong game.

Once you have the Pong folder created by the .bat in the root cocos2dx folder, you need to copy the content of your Classes folder in your visual studio Pong project to the cocos2dx Pong Classes folder, substituting the contents, and do the same with the Resources folder.

Now the files are in the appropriate place, but we still need to tell tel the makefile to take them into consideration when compiling, so we go to COCOS2DX\Pong\android\jni\helloworld\Android.mk and modify the makefile. You’ll notice that near the top of the file there is a LOCAL_SRC_FILES that already includes the path of the main.cpp and the 2 HelloWorld project files. Leave the main but override the rest so it has the paths of the files you added.

In my case:
LOCAL_SRC_FILES := main.cpp \
../../../Classes/AppDelegate.cpp \
../../../Classes/Elements/Ball.cpp \
../../../Classes/Elements/Stick.cpp \
../../../Classes/Scenes/PlayScene.cpp \
../../../Classes/Scenes/TitleScreen.cpp

Step 6: Run Cygwin to compile

Just like the original tutorial explains

Step 7: Create a project in eclipse and import the Pong project

Just like the original tutorial explains.

Second Part: More advanced concepts of getting cocos2dx working on Android from Windows 7

Baddies 4–Saving

2011-08-27T22:36:00.001+02:00

Introduction

Objective

The objective of the saving system is, given a node, any node, serialize it completely and automatically without having to go through the mistake prone method of each time we add a member, having to remember to update the load and save functions.

To this aim, we will use the IntermediateSerializer class, with a few auxiliary classes to handle logical exceptions in our design and in the IntermediateSerializer class.

Considered options

There are several options when saving the game in XNA, the 3 more common ones are serializing using the XmlSerializer class, serializing using the IntermediateSerializer class, and finally, saving with a BinaryWriter class.

The reasons why I won’t use the XmlSerializer are explained in the conclusion in this post, so I won’t expand on it. The BinaryWriter, on the other hand, requires knowing the data you are going to read beforehand, as it’s in binary format and you need to select “chunks” of specific lengths to be interpreted as variables. This does not work well with the initial objective of the saving being automatic or not having to make custom save / load functions for each class. This leaves us with the IntermediateSerializer.

Serialization

Serializing with the IntermediateSerializer

The use of the IntermediateSerializer is best documented in these 2 articles by Shawn Hargraves: Teaching a man to fish, and Everything you ever wanted to know about IntermediateSerializer.

On the positive side, it’s simple (doesn’t require the multithreading gymnastics for the container that the XmlSerializer needs), and highly customizable (adding private members, excluding public members, setting members as references, dealing with collections, etc…). On the negative side, it only works on windows, but that’s an acceptable inconvenient, and it needs the full .Net Framework 4.0 instead of the client version (explanation).

Working with the Node

For our specific situation, we want to serialize a subtree of nodes, this nodes being any class that might derive from node. For example, we might have a situation like this:

This diagram represents that there is a root node “Scene” with two added child nodes “Camera” and “Map” (ignore the UML notation, it was the only editor at hand). We want to serialize Scene without caring about what hangs from it and have everything serialized to XML.

The first attempt at serializing this launched an error of cyclic reference, as each Node has a pointer to it’s parent. To solve this we declared the parent member of a node as a ContentSerializerAttribute.SharedResource so instead of storing the parent, it just stored a reference to this. This serialized, but upon closer investigation of the XML code it became apparent that this generated “shadow” parents, as we had both the original parent that called the serialization, and the one each child was referencing, resulting in something like this:

That’s because the children of each node are not references themselves, if they were we’d just have a very slim XML tree with just references, no content, and then the references at the bottom. Something like this:

Code Snippet
 <?xml version="1.0" encoding="utf-8"?>
<XnaContent xmlns:Utils="Baddies.Utils" 
            xmlns:Scenes="Baddies.Scenes" 
            xmlns:Nodes="Baddies.Nodes">
  
  <!-- Root of the tree-->
  <Asset Type="Utils:NodeSerializer">
    <root>#Resource1</root>
  </Asset>
 
  <!-- References-->
  <Resources>
 
    <!-- Scene node-->
    <Resource ID="#Resource1" Type="Scenes:Scene">
      <Name>Node</Name>
      <ParentRelativePos>false</ParentRelativePos>
      <Children Type="Utils:SharedResourceDictionary[int,Nodes:Node]">
        <Item>
          <Key>0</Key>
          <Value>#Resource2</Value>
        </Item>
        <Item>
          <Key>1</Key>
          <Value>#Resource3</Value>
        </Item>
      </Children>
      <Visible>true</Visible>
      <Position>-0 -0 -0</Position>
      <Parent />
    </Resource>
 
    <!-- Camera node -->
    <Resource ID="#Resource2" Type="Baddies.Camera">
      <Name>Cam</Name>
      <ParentRelativePos>false</ParentRelativePos>
      <Children Type="Utils:SharedResourceDictionary[int,Nodes:Node]" />
      <Visible>true</Visible>
      <Position>0 0 0</Position>
      <Parent>#Resource1</Parent>
      <W>673</W>
      <H>442</H>
      <DisplayBorder>true</DisplayBorder>
    </Resource>
 
    <!-- Map node -->
    <Resource ID="#Resource3" Type="Baddies.Map.MapGrid">
      <Name>Map</Name>
      <ParentRelativePos>true</ParentRelativePos>
      <Children Type="Utils:SharedResourceDictionary[int,Nodes:Node]" />
      <Visible>true</Visible>
      <Position>0 0 0</Position>
      <Parent>#Resource1</Parent>
      <DisplayTerrain>true</DisplayTerrain>
      <DisplayGrid>true</DisplayGrid>
      <DisplayCollisionMap>false</DisplayCollisionMap>
      <MapWidth>16</MapWidth>
      <MapHeight>16</MapHeight>
      <TileSize>16</TileSize>
      <Tiles>
        <!-- Map tiles excuded for brevity -->
      </Tiles>
      <tileSetTex>
        <Name>TileMap/tileset1</Name>
        <contentRef>#Resource3</contentRef>
      </tileSetTex>
    </Resource>
    
  </Resources>
</XnaContent>
 

To achieve that structure we need to set the children of the Node as references as well. The children of each node are kept in a dictionary, so to solve this “dictionary of shared resources” dilemma, I wrote a class to handle it, explained in this article. This is one of the few exceptions to the “not writing custom code for saving different data” but only because the IntermediateSerializer doesn’t support these type of dictionaries out of the box.

Another exception is that even if we mark everything as references, the first node to be serialized is not considered a reference because it’s the starting point of the serializer. To solve this I made a wrapper class to serialize that only contains the root node, as a reference.

Code Snippet
 /// <summary>
/// Auxiliary class that takes care of 
/// the serialization of a Node tree.
/// <remarks>
/// Works by having a reference to the 
/// node and serializing itself, so the root
/// node is also regarded as a reference.
/// </remarks>
/// </summary>
public class NodeSerializer
{
    /// <summary>
    /// Root node to serialize.
    /// </summary>
    [ContentSerializerAttribute(SharedResource = true)]
    private Node root;
 
    /// <summary>
    /// Serializes a node to XML.
    /// </summary>
    /// <param name="node">Node to 
    /// serialize.</param>
    /// <param name="name">Name of the 
    /// file to serialize to.</param>
    public void Serialize(Node node, string name)
    {
        this.root = node;
 
        XmlWriterSettings settings = 
            new XmlWriterSettings();
        settings.Indent = true;
 
        using (XmlWriter writer = 
            XmlWriter.Create(name, settings))
        {
            IntermediateSerializer.
                Serialize(writer, this, null);
        }
    }
 
    /// <summary>
    /// Deserializes the XML file provided 
    /// and returns the created node.
    /// </summary>
    /// <param name="name">Name of the xml file.</param>
    /// <returns>Node serialized in that file.</returns>
    public Node Deserialize(string name)
    {
        Node node = null;
        XmlReaderSettings settings = 
            new XmlReaderSettings();
 
        using (XmlReader reader = 
            XmlReader.Create(name, settings))
        {
            NodeSerializer serial = 
                IntermediateSerializer.
                Deserialize<NodeSerializer>(reader, null);
            node = serial.root;
        }
 
        return node;
    }
}
 

The last exception comes with the Texture2D class. I wanted that the serializing of a tree included the actual textures used, as not to have to do a “second” step when loading. This has 2 problems. First, the texture is binary data, so kind of difficult to serialize in xml. Second, the texture has a reference to the ContentManager that loaded it, so it creates a circular dependency that there is no way to solve, short of dumping the use of the ContentManager all together.

To work around these 2 issues I created a Texture2D proxy class, as shown here:

Code Snippet
 public class Texture2DProxy
{
    /// <summary>
    /// Reference to the the parent class 
    /// that holds a ContentManager to load 
    /// this texture.
    /// </summary>
    [ContentSerializerAttribute(SharedResource = true)]
    private IContentHolder contentRef;
 
    /// <summary>
    /// Texture we wrap.
    /// </summary>
    private Texture2D texture;
 
    /// <summary>
    /// Name of the texture in the 
    /// ContentManager.
    /// </summary>
    private string name;
 
    /// <summary>
    /// Initializes a new instance of 
    /// the Texture2DProxy class.
    /// </summary>
    /// <param name="contentRef">
    /// Content manager that will be 
    /// used for loading.</param>
    public Texture2DProxy(IContentHolder contentRef)
    {
        this.contentRef = contentRef;
        this.name = string.Empty;
        this.texture = null;
    }
 
    /// <summary>
    /// Initializes a new instance of 
    /// the Texture2DProxy class.
    /// </summary>
    public Texture2DProxy()
    {
        this.contentRef = null;
        this.name = string.Empty;
        this.texture = null;
    }
 
    /// <summary>
    /// Gets or sets the name of the texture.
    /// </summary>
    /// <value>Name of the texture.</value>
    public string Name
    {
        set { this.name = value; }
        get { return this.name; }
    }
 
    /// <summary>
    /// Gets or sets the texture of the proxy.
    /// <remarks>
    /// The Get method has lazy 
    /// initialization of the texture, 
    /// in the sense that if we have the 
    /// texture name and not the texture, 
    /// it loads it when we request the 
    /// texture. This is useful for when 
    /// we load a texture via serialization.
    /// </remarks>
    /// </summary>
    /// <value>Texture that we wrap.</value>
    [ContentSerializerIgnore]
    public Texture2D Texture
    {
        get 
        {
            if (this.texture == null && 
                this.name != string.Empty)
            {
                ContentManager man = 
                    this.contentRef.GetContent();
 
                this.texture = 
                    this.contentRef.GetContent().
                    Load<Texture2D>(this.name);
                
            }
 
            return this.texture; 
        }
 
        set 
        {
            this.texture = value; 
        }
    }
 
    /// <summary>
    /// Loads the selected texture.
    /// </summary>
    /// <param name="name">
    /// Name of the texture to 
    /// load.</param>
    public void Load(string name)
    {
        this.name = name;
 
        this.texture = 
            this.contentRef.GetContent().
            Load<Texture2D>(name);
    }
}
 

What is serialized in the texture is the actual name of the texture, so afterwards we can load the name, and load the actual texture by request in the “get” field. This makes for a simple method of loading the textures from xml, the only problem is a project can have many ContentManagers running, and we have no way of knowing which one is the one the texture is associated to. To get around this we create a IContentHolder interface.

Code Snippet
 /// <summary>
/// Class that has a content manager.
/// </summary>
public interface IContentHolder
{
    /// <summary>
    /// Returns the ContentManager 
    /// associated to this class.
    /// </summary>
    /// <returns>A ContentManager object.</returns>
    ContentManager GetContent();
}
 

The parent class that owns the texture implements this interface, and is required to pass itself to the texture as a reference upon creation. That way the steps when deserializing are as follows:

When the serializer creates the parent class, the parent class creates the Texture2DProxy object and assigns itself as the ContentHolder.
The deserializer fills the serialized data of the Texture2DProxy (the name of the texture),
At some point, the game requests the texture for the first time, in the “get” field we see it’s not loaded yet, so we create it using the ContentManager of our parent, and we’re ready to go.

Dictionary of shared resources for serializing in XNA

2011-08-24T11:17:00.001+02:00

Introduction

This is a class built on the articles of Shawn Hargreaves for using the IntermediateSerializer class to serialize collections of shared resources. In his article he only does the List<T> collection, but I had the need to serialize a Dictionary<T,K> instead, and maybe someone else will need it at some point, so here it is.

Background

The class is to be used with the IntermediateSerializer. It’s a class for serializing data to XML in XNA, and though it only works on the windows platform, it’s easier to use and has a lot more flexibility than the XmlSerializer. Introduction to the IntermediateSerializer can be found here, and a more extensive explanation can be found here. Following that, you might want to check out how to write your own ContentTypeSerializer, and specifically, how to do it for a collection of shared resources.

Code

As you have seen in the example about collections of shared resources, Shawn only deals with the List class, leaving us to work through the rest. Well, here is a Dictionary class with the values as shared resources.

Dictionary evolves to… SharedResourceDictionary!

The shared resource dictionary is nothing more than an empty wrapper:

Code Snippet
 class SharedResourceDictionary<K, T> : 
    Dictionary<K, T>
{    }
 

SharedResourceDictionarySerializer

This is where the serializing gets done. As a side note, you don’t need to do anything special to get the SharedResourceDictionary to use the SharedResourceDictionarySerializer, just by having both classes in your project it’s fine.

Code Snippet
 [ContentTypeSerializer]
class SharedResourceDictionarySerializer<T, K> : 
    ContentTypeSerializer
        <SharedResourceDictionary<T, K>>
{
    static ContentSerializerAttribute itemFormat = 
        new ContentSerializerAttribute()
    {
        ElementName = "Item"
    };
 
    static ContentSerializerAttribute keyFormat = 
        new ContentSerializerAttribute()
    {
        ElementName = "Key"
    };
 
    static ContentSerializerAttribute valueFormat = 
        new ContentSerializerAttribute()
    {
        ElementName = "Value"
    };
 
 
 
    protected override void Serialize(
        IntermediateWriter output,
        SharedResourceDictionary<T, K> value,
        ContentSerializerAttribute format)
    {
            foreach (KeyValuePair<T, K> item in value)
        {
            output.Xml.WriteStartElement(
                itemFormat.ElementName);
 
            output.WriteObject(
                item.Key, 
                keyFormat);
 
            output.WriteSharedResource(
                item.Value, 
                valueFormat);
 
            output.Xml.WriteEndElement();
        }
    }
 
 
    protected override SharedResourceDictionary<T, K> 
        Deserialize(
        IntermediateReader input,
        ContentSerializerAttribute format,
        SharedResourceDictionary<T, K> existingInstance)
    {
        if (existingInstance == null)
        {
            existingInstance = 
                new SharedResourceDictionary<T, K>();
        }
 
        while (input.MoveToElement(itemFormat.ElementName))
        {
            T key;
 
            input.Xml.ReadToDescendant(
                keyFormat.ElementName);
 
            key = input.ReadObject<T>(keyFormat);
 
            input.Xml.ReadToNextSibling(
                valueFormat.ElementName);
 
            input.ReadSharedResource<K>(
                valueFormat, 
                (K value) =>
            {
                existingInstance.Add(key, value);
            });
            input.Xml.ReadEndElement();
        }
 
        return existingInstance;
    }
}
 

Sorry about the “strung out” format of the code, otherwise the blog settings compact it into an unreadable mess.

Calling the serializer

To use this code, we have a dictionary we want to serialize:

Code Snippet
 SharedResourceDictionary<int, string> dictTest = 
    new SharedResourceDictionary<int, string>();
 

To serialize it to Xml we do this:

Code Snippet
 XmlWriterSettings settings = new XmlWriterSettings();
settings.Indent = true;
 
using (XmlWriter writer = 
    XmlWriter.Create("out.xml", settings))
{
    IntermediateSerializer.Serialize(
        writer, 
        dictTest, 
        null);
}
 

To deserialize from Xml we do this:

Code Snippet
 XmlReaderSettings settings = new XmlReaderSettings();
using (XmlReader reader = 
    XmlReader.Create("out.xml", settings))
{
    this.dictTest = IntermediateSerializer.
        Deserialize<SharedResourceDictionary<int,string>>
        (reader, null);
}
 

Notes

Special thanks to r2d2rigo for helping me hunt down some bugs in the code.

XNA Serialization to XML tutorial

2011-08-19T19:30:00.002+02:00

Introduction

What is serialization?

Serialization is a semi-automatic process where XNA gets a class ~~that has been marked as [Serializable] and~~ stores/loads it from xml. An awesome idea in theory but with a few shortcomings.

Why these tutorials?

While trying to add serialization to one of my games, I’ve come to notice that there is a very real lack of documentation on XML serialization if you want to do anything more complex than serializing a struct with a few value members inside. When you get to serializing derived classes, dictionaries, trees,… and in general the normal stuff any game needs, there are a lot of hidden pitfalls to be aware of.
It’s a big list of things to go work, but I’m going to share my experiments with serialization and hopefully it will help someone else.

Windows only

This tutorial is aimed only at the windows platform, simply because it’s the only one I’ve got. I promise that if anyone likes them enough to send me a WP7 or an Xbox, I’ll make sure they are compatible. :D

Note*: Check the comments to see the small change to make it work in WP7 and XBox

Serialization example

A look at MSDN serialization

This tutorial is based on the simplest of all options, the default MSDN tutorial for serializing xml, to be found at MSDN: Serialization. The version provided in the download of that article is aimed for the Xbox, which makes it kind of confusing on the windows platform as it uses classes that are not needed, such as the Guide class. If you are working on the Xbox and have doubts, have a look in the book: "XNA Game Studio 4.0 Programming".

My main objection to the example at MSDN: Serialization is that it does NOT tell you where it gets the "device" object, and if you download the code to find out, it uses the "Guide" to get the device in a rather confusing way.

Searching around on how to make it work I found another 3 ways to get the storage device here MSDN : Get StorageDevice. Note that even though they are ALMOST the same as in the MSDN: Serialization example code, the function call varies, not much, but enough to drive one crazy. God bless IntelliSense. If you’ve got more interest, there is a theoretical explanation on how to get a storage device at MSDN : User Storage.

Steps

For both saving and loading the steps are almost the same. Notice most of the work goes into getting the actual file we are going to save to. The function calls to achieve this vary slightly from platform to platform, but we’re going to stick with windows, as the code download at the MSDN: Serialization tutorial has a Xbox version.

User requests to Save / Load
Get the StorageDevice.

Request StorageDevice
Receive StorageDevice

Get a StorageContainer from the device.

Request StorageContainer
Receive StorageContainer

Get the Stream of the file we want to use from the container.
Serialize / Deserialize.
Cleanup.

Code

With that out of the way, let’s head over to the code!
We will be using a very simple data class to serialize in this first tutorial.

Code Snippet
 /// <summary>
/// Data class with some basic data 
/// for testing.
/// </summary>
[Serializable]
public class Data1
{
    public int age;
 
    public string name = "Chuel";
 
    /// <summary>
    /// Initializes a new instance of 
    /// the Data1 class. 
    /// Required default constructor for 
    /// serialization.
    /// </summary>
    public Data1()
    {
        this.age = 0;
    }
 
    /// <summary>
    /// Initializes a new instance of 
    /// the Data1 class. 
    /// </summary>
    /// <param name="age">Age of the chuel.</param>
    public Data1(int age) 
    {
        this.age = age;
    }
 
    public void Draw(SpriteBatch spriteBatch, SpriteFont font)
    {
        string text = "Name: " + this.name + 
            " Age: " + this.age;
 
        spriteBatch.DrawString(
            font, text, 
            new Vector2(10, 10), 
            Color.White);
    }
}
 

~~First thing to notice here is that you need to mark with the [Serializable] attribute the class you want to serialize~~ (Not necessary for serializing to XML, check r2d2rigo's comment), there are more options to explore with related attributes and you can find it here. Second, that it’s a public class, as the object you serialize must be public. Third, only public properties or fields will be serialized (age and name).

And here is how we load / save the data.

Code Snippet
 /// <summary>
/// This is a game component that 
/// implements IUpdateable.
/// It serializes data in a simple way, 
/// no preprocesing or special content.
/// No blocking when doing the async. calls.
/// </summary>
public class Mode2 : 
    Microsoft.Xna.Framework.DrawableGameComponent
{
    public Data1 data1;
    private SpriteBatch spriteBatch;
 
    // Keyboard polling helpers
    private KeyboardState currentState;
    private KeyboardState previousState;
 
    // Action to do
    private enum State { 
        Innactive, RequestDevice, 
        GetDevice, GetContainer, 
        SaveLoad };
    private State state;
    private enum Action { None, Save, Load };
    private Action action;
 
    // Needed variables
    IAsyncResult result = null;
    StorageDevice device = null;
    StorageContainer container = null;
 
    public Mode2(Game game)
        : base(game)
    {
        state = State.Innactive;
        action = Action.None;
    }
 
    public override void Initialize()
    {
        base.Initialize();
        this.spriteBatch = 
            new SpriteBatch(Game.GraphicsDevice);
        this.data1 = new Data1();
    }
 
 
    public override void Update(GameTime gameTime)
    {
        // Key checking
        previousState = currentState;
        currentState = Keyboard.GetState();
 
        // STEP 1: User requests save / load
        // When we press the "s" key
        if (currentState.IsKeyUp(Keys.S) &&
            previousState.IsKeyDown(Keys.S))
        {
            // Request to save
            if (state == State.Innactive && 
                action == Action.None)
            {
                this.state = State.RequestDevice;
                this.action = Action.Save;                    
            }
        }
 
        // When we press the "l" key
        if (currentState.IsKeyUp(Keys.L) &&
            previousState.IsKeyDown(Keys.L))
        {
            // Request to save
            if (state == State.Innactive && 
                action == Action.None)
            {
                this.state = State.RequestDevice;
                this.action = Action.Load; 
            }
        }
 
        // Do the actual save or load
        if (this.action == Action.Save && 
            this.state != State.Innactive)
        {
            this.Save();
        }
        if (this.action == Action.Load && 
            this.state != State.Innactive)
        {
            this.Load();
        }
 
        // Make the age change so we can see 
        // stuff change with the save / load
        if (Mouse.GetState().LeftButton == 
            ButtonState.Pressed)
        {
            this.data1.age += 1;
        }
 
        base.Update(gameTime);
    }
 
    /// <summary>
    /// Function where we do all the saving
    /// </summary>
    private void Save()
    {
        switch (this.state)
        {
        case State.RequestDevice:
        {
            // STEP 2.a: Request the device
            result = 
                StorageDevice.BeginShowSelector(
                PlayerIndex.One, 
                null, 
                null);
            this.state = State.GetDevice;
        }
        break;
        case State.GetDevice:
        {
            // If the device is ready
            if (result.IsCompleted)
            {
                // STEP 2.b: Recieve the device
                device = 
                StorageDevice.EndShowSelector(result);                            
 
                // STEP 3.a: Request the container
                result.AsyncWaitHandle.Close();
                result = null;
                result = device.BeginOpenContainer(
                    "StorageDemo", 
                    null, 
                    null);
                this.state = State.GetContainer;
            }
        }
        break;
        case State.GetContainer:
        {
            // If the container is ready
            if (result.IsCompleted)
            {
                // STEP 3.b: Recieve the container
                container = device.EndOpenContainer(result);
                result.AsyncWaitHandle.Close();
                this.state = State.SaveLoad;
            }
        }
        break;
        case State.SaveLoad:
        {
            string filename = "savegame.sav";
 
            // Check to see whether 
            // the file exists.
            if (container.FileExists(filename))
            {
                // Delete it so that we 
                // can create one fresh.
                container.DeleteFile(filename);
            }
 
            // Create the file.
            Stream stream = 
                container.CreateFile(filename);
 
            // Convert the object to XML data 
            // and put it in the stream.
            XmlSerializer serializer = 
                new XmlSerializer(typeof(Data1));
 
            serializer.Serialize(stream, data1);
 
            // Close the file.
            stream.Close();
 
            // Dispose the container, to 
            // commit changes.
            container.Dispose();
            state = State.Innactive;
            action = Action.None;
        }
        break;
        }
    }
 
    /// <summary>
    /// Function where we do all the loading
    /// </summary>
    private void Load()
    {
        switch (this.state)
        {
        case State.RequestDevice:
        {
            // STEP 2.a: Request the device
            result = 
                StorageDevice.BeginShowSelector(
                PlayerIndex.One, 
                null, 
                null);
            this.state = State.GetDevice;
        }
        break;
        case State.GetDevice:
        {
            // If the device is ready
            if (result.IsCompleted)
            {
                // STEP 2.b: Recieve the device
                device = 
                StorageDevice.EndShowSelector(result);
 
                // STEP 3.a: Request the container
                result.AsyncWaitHandle.Close();
                result = null;
                result = 
                    device.BeginOpenContainer(
                    "StorageDemo", 
                    null, 
                    null);
                this.state = State.GetContainer;
            }
        }
        break;
        case State.GetContainer:
        {
            // If the container is ready
            if (result.IsCompleted)
            {
                // STEP 3.b: Recieve the container
                container = 
                    device.EndOpenContainer(result);
                result.AsyncWaitHandle.Close();
                this.state = State.SaveLoad;
            }
        }
        break;
        case State.SaveLoad:
        {
            string filename = "savegame.sav";
 
            // Check to see whether the save exists.
            if (!container.FileExists(filename))
            {
                // If not, dispose of the 
                // container and return.
                container.Dispose();
                return;
            }
 
            // Create the file.
            Stream stream = 
                container.OpenFile(
                filename, 
                FileMode.Open);
 
            // Convert the object to XML 
            // data and put it in the stream.
            XmlSerializer serializer = 
                new XmlSerializer(typeof(Data1));
 
            data1 = 
                (Data1)serializer.Deserialize(stream);
 
            // Close the file.
            stream.Close();
 
            // Dispose the container, to commit changes.
            container.Dispose();
            state = State.Innactive;
            action = Action.None;
        }
        break;
        }
    }        
 
    public override void Draw(GameTime gameTime)
    {
        base.Draw(gameTime);
 
        this.spriteBatch.Begin();
        this.data1.Draw(
            this.spriteBatch, 
            Game.Content.Load<SpriteFont>("Font"));
        this.spriteBatch.End();
    }
}
 

We need to get 2 objects with asynchronous calls, the device and the container. This means we need to be careful not to block the game while we wait for the calls to return, and that’s why the code looks like a magical rainbow of cases, because the Update() function might be called lots of times while we wait and we don’t want strange stuff to happen.

We create a data object with just a name and an age, when we press the left button of the mouse the age increments, press “s” to save and “l” to load the last saved data.

Following the comments in the code should give a pretty clear idea of what is going on, but we’ll go over it none the less, I’ll ignore the support code not directly related with serialization, but if there are any doubts just ask in the comments. There is some redundant code but I haven’t shortened to make it as simple as possible to follow the logic.

Both save and load work very similar. First thing we need to do is get a storage device. This requires using an asynchronous call, so we request it (2.a) by calling BeginShowSelector and when it’s ready result.IsCompleted will return true. Notice that in windows we pass PlayerIndex.One as the parameter.

We then receive the device (2.b) and request the container from the device (3.a) with BeginContainer, where we pass the name of the “container” to use, in this case, the folder StorageDemo.

We finally we receive the container (3.b) and we’re ready to go! No more magical asynchronous stuff.

The last part is where the actual serializing takes place. For saving we get ourselves a file to write on (4) and a serializer for the type of data we want to serialize (Data1 in this case), and then just serialize it into the file (5) and tidy up (6). For loading we check the file exists (4) and then open it and deserialize into our data object (5) and clean up (6).

The generated XML looks like this:

Code Snippet
 <?xml version="1.0"?>
<Data1 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  <age>43</age>
  <name>Chuel</name>
</Data1>
 

A last note on how the system is set up. The Mode2 class is a DrawableGameComponent so that the XNA framework takes care of everything (updating and drawing and so on), and in our game class we only need to add one line. Has nothing to do with serializing.

Code Snippet
 public Game1()
        {
            graphics = new GraphicsDeviceManager(this);
            Content.RootDirectory = "Content";
 
            this.Components.Add(new Mode2(this));
        }
 

Notes

Data that XNA serializes

XNA doesn’t serialize everything that there is in the class, but the documentation is not too specific on what’s game besides “public properties and fields”. So I went ahead a did a little testing. Here are the results of testing, plus what I found searching around the net.

Serializes public properties, not private or protected.
Serializes public fields with both get and set, not partially implemented fields.
Arrays of values or of objects work fine.
Lists<> of values or of objects work fine. Tough not generic List<T>
Cannot serialize ArrayList.
Cannot serialize an enumeration of unsigned long with any value larger than 9,223,372,036,854,775,807.
Typical XNA classes like Rectangle or Vector work just fine with the serialization.
On serializing references, I found this bit from the MSDN forum:

“It will serialize references, but always as a copy. Basically what this means is that each time the serializer hits an object that has a reference to another serializable object exposed as a public property or field, it will write out the all of the public properties/fields of the object that reference points to. This is a problem if you have the same object referenced multiple times by something you're serializing. For instance...say you had two MeleeAttack's referencing the same PhysicsObject. After deserialization, you'd end up with your MeleeAttack's having references to different PhysicsObject's with identical properties. I used to get around this by giving certain types of objects a unique integer ID, and then having the objects serialize the ID rather than the reference. Then after deserialization I'd have another initialization step where I'd use the ID to look up the corresponding object and grab a reference.”
From textures it only saves the name.

Leads for more complex serialization magic

For elements that we read from Xml that are not in the object, we can use the XmlAnyElementAttribute and XmlAnyAttributeAttribute attributes. Useful for compatibility with older versions of our code. Check it here.

To ignore a field we can use the XmlIgnoreAttribute. Check it here.

You can override the serialization of any set of objects by creating one of the appropriate attributes and adding it to an instance of the XmlAttributes class. More complex stuff that can be used to serialize things that come from dlls, or to control how to serialize your own data. Check it here.

You can use the IXmlSerializable interface to provide custom formatting for Xml serialization and deserialization. Check it here.

4 Quick rules

To end, 4 quick reference rules to keep in mind for serializing:

~~Note #1: You need to mark the class you want to serialize with the [Serializable] attribute.~~
Note #2: Serialized classes must have a default constructor.
Note #3: Serialization only converts the public properties and fields
Note #3: The actual object you serialize must be public.

Conclusion

The serialization mechanism is awesome as in it’s automatic for the classes marked, but it’s lack of handling references correctly makes it useless for saving a big “chunk” of game data (like a whole level) as it doesn’t avoid the work of having to set up a ID system to take care of the references. It is best suited for things as saving the player preferences, or the control settings or similar.

XNA Notes–Day 6

2011-08-16T10:34:00.001+02:00

There is an onscreen keyboard that can be shown with Guide.BeginShowKeyboardInputwhich is an asyncronous object and you need to wait till the isCompleted parameter returns true. On Windows and XBox you need to add the GamerServicesComponent to the list of components the game has.

The Xbox can have a chat pad keyboard attached to the controller.

2 modes for audio: Fire and Forget (just call play on the audio and that's it, it plays until it finishes) and using SoundEffectInstance which lets you pause, resume, and things like that.

There is a Miscrosft Cross-Platform Audio Creations Tool to manage all audio, add effects and so on.

You can read microfone data from xna.

XNA Notes–Day 5

2011-08-15T11:43:00.001+02:00

In short, the Importer reads from text into objects, and the Processor loads stuff (like the actual textures from the texture name) using other Processors (like the default processor for a texture) and applies effects.

Content Processor

To create a custom content processor you add a new Content Pipeline Extension Library and add a reference to it from your project.

Create a new class in this project and derive it from ContentProcessor, setting the template variable to whatever type of file we want to load and what type of file we're going to generate.

public MyContentProcessor : ContentProcessor<InputType, OutputType> {}

Then we override the Process function (that looks something like this)

public OutputType Process(InputType input, ContentProcessorContext context)

Finally, in the Content project, select the element to process and change the processor to the new one you made.

You can add properties to the content processor you create, and they appear on the visual studio properties when you select the asset in the content project.

Content Importer

To load new formats (game level).
You crterate a Content Pipeline Extension Project and create a class that derives from ContentImporter<ToImport.Extension> and override the Import function.

Content Writer

You inherit from the ContetTypeWriter<ClassToWrite> class,
and in that class you override the Write function and write out all the data you need to.

XNA Notes–Day 4

2011-08-13T19:07:00.001+02:00

Effects

The effects are what makes the 3D world of xna roll.

Basic effect is the default one and keeps track of stuff like lighting (ambient, directional, specular, emissive), texturing, colors and fog. It also has interfaces to be derived from by the user (one for matrix positioning, one for light and one for fog).
Alpha test effect is used for performance by rejecting pixels based off their alpha level.
Enviroment map effect is used for maping the enviroment into an object (think mirror).
Skinned Effect is ussed for animation of models, it relies heavily on a proper content processor.

States of the graphics device

A state can be passed to the Begin method of the spritebatch when selecting to draw something.

Blend state controls how colors blend together, can be used in various ways, among others to get the negative of the image, to control the alpha operations and play with the depth stencil.

Render targets

There is a RenderTarget2D class that allows you to render to it instead of the device, which you can use it by calling GraphicsDevice.SetRenderTarget(rt), and in HiDef mode you can have up to 4 different render targets going.

Baddies 3–Editor

2011-08-11T18:30:00.001+02:00

Showing the game in a PictureBox

The first hurdle when making the game editor with windows forms was getting it to render XNA in a form. For this I used a picture box and followed the tutorial at http://royalexander.wordpress.com/2008/10/09/xna-30-and-winforms-the-easy-way/ The only change I had to do was to make sure the back buffer size of the xna game was the same as the size of the picture box, otherwise weird stretching ensued.

Coupling game and form

There is a high coupling between both game and form in the editor, as this is the fastest and cleanest method of working the interaction between both of them. None of the two classes are intended for any reuse or generic use, so it’s the best decision. For this, we just store a reference to each other during the initialization of the program so they are linked, and provide methods to access whatever is needed.

Creating a map

Creating a new map is an essential part of the editor. I created a new form that took care of receiving all the necessary information and then launched an event with this data.
This event was caught by the main editor form and then passed on to the game class, where we just create a MapGrid node and add it to the root.

Loading a TileSet

To load a new tile set we create a dialog that uses the windows interface to load the required image file with the tileset. If the image is found, we create one TilePictureBox out of each bit of the image that is of tileSize x tileSize size and set it in the appropriate form container, so when the user clicks on one he can use it to draw.
Making a specific class instead of just using a normal picturebox was necessary to make the tiles react to the OnClick event.

Baddies 2.8–Map

2011-08-10T16:55:00.001+02:00

The map is just a list of lists, holding all the tiles in a matrix. The only thing it has special is the fact that it holds the tileset image, with all the images of the tiles, as well as other extra graphics used for other drawing modes (for example the grid). When the map wants to draw the tiles (be it as the actual tiles, or the grid, or the collision) it passes the corresponding graphic to the tiles in their draw function.

The map tiles are not nodes because of the need to access them easily with a 2D coordinate system, and the special operations that we need to do with them. It’s one of the cases where efficiency is more important than following the tree structure.

Baddies 2.7–GUI Input Management

2011-08-10T16:36:00.001+02:00

The game engine needs to accept input from several devices, mainly Xbox, Windows and WP7. For each of them a different input controller must be used.
The input device is an independent class, it has no power to actually do anything or change anything. Instead what happens is it interprets the input of the user using various means (selection boxes, touches, radial menus, etc.) depending on the device. Once it knows what the action is (select units in rectangle, interact with clicked position, etc.) it sends a message with all the relevant data, to be caught and acted upon by whoever is responsible.

Having a system like this prevents having lots of cases for the different controllers distributed all through the code, and also avoids duplication of work.

The basic idea is that the primary input of the user gets transformed into some kind of command with data that then the engine then interprets homogenously, without knowing who sends the message. Adding new input devices is therefore trivial, as the engine just receives messages of commands to execute.

As for the GUI elements themselves, they hang from the input device they are designed for (no sense having a selection box in the Xbox for example), and the input device object is always on the top of any other nodes so it gets the input / drawn first. The input device has a GUINode that is active at the moment. That’s the one which attempts to answer to the user event (say a keypress), if it consumes the event, that’s it. If not, we send a message to the system, to see if any other node wants anything to do with that event.

Having the GUINodes independent of the InputDevice class makes it so if we want a standard GUI element (say a minimap), we just add the MiniMapGUINode to the InputDeviceNode, and we know it’s going to be on top, whereas if we want something more local (for example a speech bubble) we add it to the player node, and it’s going to be in the proper Z height, at the same as the player.

XNA Notes–Day 3

2011-08-10T13:16:00.001+02:00

If you want to set a rectangle section of the screen to draw to, set the GrpahicsDevice.ScissorRectangle to a rectange and set the ScissorTestEnable property of the GraphicsDevice.RasterizerState to true.

GraphicsAdapter is used to deal with all the graphic output devices a pc might have (XBox and WP7 only have one), and their characteristics.

GraphicsDevice has a back buffer and uses double buffering. the Present method does the flip, and there are several flip modes

.PresentInterval.One (Flips when the display is in vertical retrace phase)
PresentInterval.Two (Flips every other vertical retrace)
PresentInterval.Immediate (Flips as soon as possible, can cause tearing but good for measuring performance)

GraphicsDevice.SupportedOrientations lets you determine the positions you let the game work in WP7.

Baddies 2.6–Event Manager

2011-08-09T18:44:00.001+02:00

In a tree architecture, getting the nodes to communicate without making a huge mess of links between nodes requires special attention. That’s where the EventManager comes in.

It provides a one or two way communication system among nodes in the system. The nodes don’t even need to know that the other node exists. It works on one to one and one to many modes with no difference.

The EventManager is a singleton, there is only one and shared by the whole system. Anyone can register a new event, with a specific name. Once an event has been added to the EventManager, anyone can register an EventHandler to it, and anyone can trigger it. When someone triggers an Event, everyone who registered an EventHandler gets notified. As this system is built on the delegate system of XNA, it incorporates sending extra information along with triggering an Event, mainly arguments and who triggered it.

This works fine for general purpose messages (like print subtree, that orders the root node to print it’s subtree) or for messages that require a reply (someone asking for a content manager, just send an argument object with a content manager memberto fill, and check it in the sender class.)

The main issue with this system is security, as messages are not guaranteed to be answered, but the Debug.Assert function covers almost all the dead ends in this case.

Baddies 2.5–FSM and Scene

2011-08-09T18:03:00.001+02:00

A FSMNode (finite state machine node), is a node with the special property that it has one active node, and that is the only one which gets updated and drawn. The FSMNode also has special methods to change the active node. A FSM is a pattern I find myself using a lot when I program games, so a generic Node-like FSM is a great deal.

Closely linked with the FSMNode is the Scene node. This is so because in any given game you have different scenes and only one of them active at any given time, so the FSMNode is the perfect place to hang SceneNodes. The one peculiar thing the SceneNodes have is a ContentManager, so the loaded content is local to each scene and when we swap scenes we don’t have to worry about what we load/unload. The common assets can be loaded in the Game ContentManager.

Seeing as the ContentManager class already caches and takes care of assets for us, there is no immediate need to make a resource manager and manage all assets globally. Again, we sacrifice a small amount of performance for simplicity of use.

That’s it for the specifics of those two classes.

Baddies 2.4–Camera

2011-08-08T19:34:00.001+02:00

First off, to define what we mean by camera. My camera in this project is just a position in 2D space, a width and a height. It does not take care of rendering itself, and is independent of screen size.

The camera is a delicate element, there are a lot of ways to implement it and a lot of variation in those ways. In this particular architecture is complicated because once we set up a camera, which by definition is a node, every node in the selected subtree needs to deal with it, and we want to avoid cluttering the draw function with a camera parameter that might even not be needed.

Methods I discarded

Using a singleton, easy to access from any sub node, very little security on who controls it, the game can only have one “view”, and it doesn’t fit in the spirit of the node based system. An easy patch.

Passing the camera by parameter on the draw, but this forces all draw routines to have a parameter they might not need (see GUI), creating an overloaded Draw is dangerous, as you let the user too easily forget to use the one with the camera. Another problem is even if you do it like this, you must position the camera somewhere, and it doesn’t make much sense to do so with a node, so we would have to add a special element to one of our nodes, which is the whole thing I was trying to avoid by using generic nodes.

Setting the camera as a static member of a main class, like the scene, and let anyone access it like that. That’s a more “local” version than the singleton, but it suffers from most of the same problems and a few more, like the variable can be accessed with no Scene created (BAD), and we mark just ONE type of node as capable of using the camera, thus limiting the use of the camera element.

Final method

The solution I found best is to derive the camera like just another node, that can be added anywhere. The node it is added to effectively takes on the camera’s position (by setting the position of the parent node to it’s negated position in every update of the camera), and that node and all the subtree it spans are displaced as required by just the normal draw mechanism, which includes adding the parent’s (now camera’s) absolute position to our relative position.

The other detail is we need a proper camera that is capable of culling. For this we implement a cull method in node, which does accept a Camera object, but is only used by the camera behind scenes, and only by those “affected” by a camera, thus removing the problem mentioned with overriding the Draw method. Every node can override this cull method to suit it’s needs, and the camera calls it every update, keeping only a list of elements that are inside the camera as the ones ready to draw.

That’s basically it.

Baddies 2.3–Node Updating

2011-08-08T18:57:00.002+02:00

When dealing with a node – tree architecture, there are several functions that need to be called recursively down the tree (mainly draw and update, but there are others, such as cull, exit, etc…) AND they need to be overridden in base classes, normally by the user.

Implementing either one of these things is trivial, but doing them together and while keeping the system secure from any slips by the user is not. One possible solution is to remind the user in the documentation that when he overrides update, he must always call update on all the children of the node. But this is playing with fire, eventually someone is going to forget, and put a sneaky bug in the system.

The easiest solution I’ve come up with is putting 2 functions of each: Update and NodeUpdate, Draw and NodeDraw… where the single word function is an abstract function for the user to override, and the double word function is the one actually called in the tree update, which calls to the simple function, does some extra necessary stuff and updates the children.

This method is transparent to the user, who just needs to override the function as expected, and doesn’t let him fuck up anything important. Similar solutions might be made with delegates or callbacks.

XNA Notes–Day 2

2011-08-08T12:44:00.002+02:00

Random notes

Program.cs is a stub that launches the game, it's not even used in WP7

GraphicsDeviceManager implements IGraphicsDeviceService and IGraphicsDeviceManager, and adds itself to the "Services" property of the game object.

You can create your own services and get them directly from the game object. For example a spritebatch for public access with: Services.AddService(typeof(SpriteBatch), spriteBatch); and you can access it from anywhere you can access the game with SpriteBatch spriteBatch = Game.Services.GetService( typeof(SpriteBatch)) as SpriteBatch;

GraphicsDeviceManager (GDM)

Instantiating a GraphicsDeviceManager makes it create a GraphicsDevice as a property of game and of GDM. It also creates the GraphicsProfile property and the IsFullScreen property (that behaves differently depending on the platform).

The GDM also has preferences. The runtime attempts to use them and if it cant it falls back on the closest it can.

PreferedMultisampling (to blend pixels together and remove jagged edges, defaults to fault because of the overhead)
PreferedBackbufferHeight /Width (size of the window on non-fullscreen, resolution on fullscreen and ignored in XBox and WP7)
PreferBackBufferFormat / ScencilFormat (how many bits used for the deph and stencil buffers)
SupportedOrientations (for WP7)
SynchronizeWithVerticalRetrace (prevents tearing by pausing until ready to draw).

There are also events you can hook to, most interesting the PreparingDeviceSettings, lets you override any of the settings before the device is created.

Two interesting methods

ApplyChanges (flushes the changes)
ToggleFullscrenn (changes to and from full screen)

Game class

There are 2 methods to overload BeginDraw and EndDraw which are not visible on default. Overloading EndDraw requires you to call base.EndDraw.

Two other interesting methods to override, BeginRun and EndRun, called just before begins/ after finishes to run.

Events you can hook to:

OnActivated (Game is activated at the beginign and any time it regains focus)
OnDeactivated (Ditto)
OnExiting (Just once when the game is exiting)

Methods in Game

Exit (Causes the game to start shutting down)
ResetElapsedTime (Does exactly that)
Run (As expected in W and XBox, but throws an exception in WP7 as it's a blocking method)
SupressDraw (Stops calling draw until the next time Update is called)
Tick (Advances one frame, calls Update and Draw)

Propierties in Game

InactiveSleepTime (Tells the system how long to sleep when not the active process, default 20 milliseconds)
IsActive (Tells you if you're the active process)
LaunchParameters (Gests the comand line parameters of in WP7 information oabout the parameters required for launch)

Game time

Game has two parameters to handle time IsFixedTimeStep and TargetElapsedTime, and the update method gets passed a GameTime object with the current time. Interesting detail is the IsRunningSlowly property in the GameTime object, which can be used in FixedTimeStep mode.
For measuring the performance of the game, variable time step should be used.

Components

Encapsulated game objects of 3 types, GameComponent, DrawableGameComponent and GamerServicesComponent.
Focusing on the first 2, they have the same structure more or less than Game.
You can add components in the Game class initialize method, and they get handled by the Game, with no supervision.

Baddies 2.2–Node Positioning

2011-08-06T19:06:00.001+02:00

Each node in the game tree has two possible options when drawing, either relative to the parent node, or with absolute coordinates respect to the screen. This is done as some things like the GUI need to be relative to the screen, regardless of where they are hooked up in the game tree, and for most of the compound objects (like a player with a sword and a shadow) it makes it a lot easier if you just put the sword and shadow relative to the player and forget about it (when the player moves, the sword and shadow will as well.)

But this apparently simple system raises some questions. First and foremost, do we keep 2 sets of coordinates? We keep the absolute coordinates and (needed for drawing from everyone) and the relative ones? Or we recalculate one of them?
And if we recalculate one of them, do we do it on demand? Or every cycle?
And finally, how do we keep this coordinates “safe” so there are no hidden bugs when the user modifies one set and not the other?

The answer I came with is to keep just the relative coordinates as position, and a variable parentRelativePos, which indicates whether the coordinates are relative to the parent post or not. No double set of coordinates because data replication is a sure way for innocent bugs to creep invisible into the system, and still attack months later in the development. So by elimination we end up with just one set of data.

As for recalculating them, it will be apparent by now that for the vast majority of nodes, it is only needed to recalculate the absolute position it when drawing (for those relative to the parent position), and not at all for the rest (the not relative to the parent position nodes can just draw with their normal position variable, as it’s absolute coordinates).

So, the problem boils down to recalculating when drawing, or when the position changes. Doing it when the position changes is viable ONLY if we keep the position variable private, and all changes to it go through an accessor method that updates the position and the “drawPosition”, but that is still a possible nest of bugs (maybe we need to open the level of security of position to protected, or have some unacceptable access times in derived classes from node, and this is again giving a user full access to fuck up). So we recalculate the drawPosition every draw cycle, by adding the parent drawPosition to our own position. Just 3 additions per cycle of extra cost, not so bad when the alternative is ninja bugs all over the code.

In conclusion, one variable that is position, the Boolean parentRelativePos indicates whether it is a relative or absolute position, and the drawPosition is updated every draw cycle from our position and our parents drawPosition.

XNA Notes–Day 1

2011-08-06T18:33:00.001+02:00

I’ve been programming on and off in XNA for a few years now, but I never really tried to learn XNA, just picked it up on the go, googling whatever was needed at the time. But now I’m working on a more dedicated project, and not knowing my tools in depth can only lead to suboptimal solutions. Therefore, I have decided to pick up the XNA Game Studio 4.0 Programming book, by Tom Miller and Dean Johnson, and start studying it from the beginning.

This series of XNA notes are just that, notes from studying, with curious / useful facts from the book, as I have a horrible memory and writing things down is the only way to remember them. Besides, someone else might find something useful here, who knows?

So, without further ado, today’s notes:

Random notes

Game Studio 4.0 is broken up in two different profiles, Reach which encompasses features for all platforms and HiDef, which includes extra features that exist only in W and Xbox.

The origin of coordinates is the top left.

font.MeassureString(string) tells you the width and height of the string in that font.

SpriteBatch

Tinting in spritebatch.draw multiplies the original color of the image by the color of the tint.

Using a Vector2 instead of a rectangle means we don't do any stretching to the image when we render it on screen, we draw it with the original size.

Different overloads

In the appropriate draw overloads, the source rectangle lets you decide which part of the original image you're going to draw. Useful for frame animations.
In the appropriate draw overloads you can rotate the image using an angle in radians and an origin for the rotation. You can also scale the image.
You have some crappy SpriteEffect options, which are to flip horizontaly, to flip vertically or none.
There is a Z ordering for the drawing between 1.0 (top) and 0.0 (bottom) that only matter if you play arround with the sorting modes.

Sprite Sorting

Using spritebatch.begin we can specify the draw mode, among others SpriteSortMode…

Texture (sort by texture, do all of the same texture at the same time as not to have to change, default),
FrontToBack / BackToFront (taking into account the depth specified for each draw call),
Deferred (Drawn in the order it is used in the draw calls),
Immediate (different from all others bacause hardware render calls are not batched, but instead we have one hardware call per draw call).

Sprite Blending

Using spritebatch.begin we can also specify the blend state, among others BlendState.

AlphaBlend (default blending mode, transparency works fine),
Opaque (No blending),
Aditive (adds the colors together).

Baddies 2.1–Nodes and Tree Architecture

2011-08-05T17:59:00.001+02:00

The game engine follows a tree based architecture, that is, all elements are nodes, and any node might be added as a child to someone else. Every node might have at most one parent. Specific cases and conditions can be dealt with from each individual node.
There are three main reasons I’ve opted for this architecture, to the point of redoing several months of work.

Low coupling

Ideally, in any computer science project there is low coupling and high cohesion. This means, in an OOP environment, that the best situation would be one where no class needs to know about any other to function. This is a goal worth pursuing, even though it is not always reasonable to stick to this guideline, as you need to sacrifice other factors (speed, mainly) to achieve it, and that is simply not an option in a game project.
But, low coupling is good, as I’ve found out in countless projects, and most games can be designed as to minimize coupling and be all the better for it. And a tree based architecture is awesome for this because since any node can be added to any other node, you can never assume a node will have a particular parent on whose internal workings it relies, therefore you must always write modular code.
This, of course, takes a toll on efficiency and forces us to use several communication mechanisms we shall see later.

Avoiding repetition

In almost all game projects I’ve done, I find the objects follow a hierarchical structure, and from each parent object I usually have to call the “Enter, Update, Draw, Exit” functions of all of its children, for which I have to create individual variables, and so on. There is a lot of duplicated effort for each object you add to a class.
A tree architecture solves all this by putting all items as nodes, so they can be stored and treated in a generic way. No more remembering to modify half the class when I add a new variable or remove it.
The down side is that accessing elements in a class from the outside is slower as a search of some sort, or even a direct access to the index of the element requires extra work, and therefore time.

Empirical experience

I worked with the Cocos libraries in a couple of projects and found it to be a delightful system, working fine in the limited environment that is a smartphone.

Conclusion

All in all, it’s a good system for games that don’t try to squeeze the processor dry, and like a clean easy to maintain system.

Baddies 1.3–Project distribution

2011-08-04T10:21:00.002+02:00

Reflecting the new architecture explained in the previous article (Baddies 1.2 – Architecture), the whole project was divided in 4 MVS projects, though within a single solution.

Microsoft Visual Studio is a superb tool for this kind of things and as long as you don’t put recursive references of a project within a project, it gets the job done very easily.

The project structure ends up looking like this:

Core
Game
Editor
Content

The Content project holds the content files (graphics, audio, and so on) used by any of the other 3 projects, as the amount of non-shared assets in the whole solution is relatively small compared to the total amount of assets.
The references between all the projects are the logical ones, with the game and editor using the core and content.

This setup of projects is interesting to remember as it’s common to a lot of game projects (tough instead of the editor there might be another secondary tool for the game).

Baddies 1.2 - Architecture

2011-08-03T17:53:00.002+02:00

The initial project was to make a single complete game, and the architecture reflects this. It’s a tree based system where almost every element of the game is a node, and any node can be attached to another. The architecture is inspired on the one implemented very successfully by the Cocos2D libraries.
Here is a class diagram in a simplified UML notation, with each class linked to where it was going to be used later on, instead of normal UML composition, as any node can be linked to any node as need arises.

After the start of the project, it became apparent however that an editor was needed for the game. The editor shared many of the classes of the original game, thus the need for a library of common classes that both projects (game and editor) needed to access. This evolved into 3 separate architectures, as follows.

Core architecture

The core architecture has all the classes of the core engine and their dependency to the Node class. Classes in green are XNA classes.

Game architecture

The game architecture has the relationship of the core classes among each other to create the actual game. All the white classes are from the core library, while blue classes are specific to the actual game.

Editor architecture

The editor architecture is mainly one editor form and one game editor closely coupled via a picture box form. Inside the game editor we build the actual game to be shown, and in the editor form we create the GUI via windows forms.

Baddies – 1.1 Introduction

2011-07-17T19:57:00.016+02:00

This is the first of a series of articles documenting the creation of the Baddies project.

The Baddies project is a game idea I have been musing for quite a long time, and as I have found that an initial all-encompassing game architecture to be well beyond my means, I shall attempt to do it in an incremental fashion (tough following an initial architecture diagram), documenting each design decision whilst coding. What better way to do this than by blogging about it?

The Baddies game is a tactic based game, with heavy focus on the minions the player can control and some base building. The story of the game also plays a very important role in the final version.

It’s a game aimed for Xbox, windows and Windows Phone 7. For simplicity I shall focus first on the windows version and leave the other 2 for later on. I build on the XNA framework for the code of the game. I work on Microsoft Visual Studio 2010 as my IDE, and with subversion as my backup version storage.

I will use this post as an index for the rest of articles in this series. The articles will only focus on the code side of this project tough. Any story or graphics news will have to wait till almost completion of the game.

Behavior Trees by Example. AI in an Android game.

2010-12-14T20:41:00.002+01:00

Introduction

I'm going to cover the implementation of a very useful technique for AI programmers called Behavior Trees (BT for now on). I've been using this technique for the AI in the Android game I'm working on, and found a few quirks in the architecture that made me have to struggle somewhat. Just thought I'd share what I've learnt during the process.

As this is for an Android game, the code is in Java. Even so, it is easily ported to C++, and there are almost no Android specific libraries or function calls to worry about.

What are Behavior Trees?

The internet is crawling with places to find a good theory on what behavior trees are, and how to implement them, for example:

AIGameDev : Overview; Approaches; Video tutorial part 1, part 2.
Wikipedia (Not recommended for videogame development, but interesting)
Etc...

Overview

This article assumes you know what a BT is. If not have a look at the mentioned articles. I’m going to work with a system with the following architecture.

It may look complex at a glance, but once we’ve gone over each part you will see like it’s quite understandable, elegant and flexible. At a glance you can see 3 “groups” of classes. The Tasks (yellow), the TaskControllers (blue) and the Decorators (green). We shall consider each of these in turn, and then how they all fit together.

Architecture

General

The general idea for the system is that you have a set of modular tasks (MoveTo, FindClosestEnemy, FindFleeDirection, WaitTillArrivedAtDestination…) and you use them to form a BT. The base Task class provides a interface for all these tasks, the leaf tasks are the ones just mentioned, and the parent tasks are the interior nodes that decide which task to execute next.

The tasks have only the logic they need to actually do what is required of them, all the decision logic of whether a task has started or not, if it needs to update, if it has finished with success, etc. is grouped in the TaskController class, and added by composition. This is done for two reasons, one is for elegance when creating new tasks, the other for security when creating new decorators.

The decorators are tasks that “decorate” another class by wrapping over it and giving it additional logic. In our case we use them to give a update speed to a certain task, or to reset it once is done, or similar things. You can read about the Decorator pattern here.

Finally, the Blackboard class is a class owned by the parent AI that every task has a reference to. It works as a knowledge database for all the leaf tasks, and it’s where we keep the data that is generated on one task and needs to be used by another.

Tasks

Task

All tasks follow the same interface:

Code Snippet
 /**
 * Base abstract class for all the tasks in 
 * the behavior tree.
 * 
 * @author Ying
 *
 */
 
public abstract class Task 
{    
    /**
     * Reference to the Blackboard data
     */
    protected Blackboard bb;
    
    /**
     * Creates a new instance of the Task class
     * @param blackboard Reference to the 
     *    AI Blackboard data
     */
    public Task(Blackboard blackboard)
    {
        this.bb = blackboard;
    }
    
    /**
     * Override to do a pre-conditions check to 
     * see if the task can be updated.
     * @return True if it can, false if it can't
     */
    public abstract boolean CheckConditions();
    
    /**
     * Override to add startup logic to the task
     */
    public abstract void Start();
    
    /**
     * Override to add ending logic to the task
     */
    public abstract void End();
    
    /**
     * Override to specify the logic the task 
     * must update each cycle
     */
    public abstract void DoAction();
    
    /**
     * Override to specify the controller the 
     * task has
     * @return The specific task controller.
     */
    public abstract TaskController GetControl();
}
 

As in any BT node, a CheckConditions and a DoAction functions, to check if the node can be updated, and to actually update the node, respectively. The Start and End functions are called just before starting to update the node, and just after finishing the logic of the node.

To be a true interface, the Blackboard member should not be in the class, but for simplicity and ease of use, it’s the perfect place for it. So fuck interfaces then.

Leaf Task

Base LeafTask class

Code Snippet
 /**
 * Leaf task (or node) in the behavior tree.
 *  
 * Specifies a TaskControler, by composition, 
 * to take care of all the control logic, 
 * without burdening the Task class with 
 * complications.
 * 
 * @author Ying
 *
 */
public abstract class LeafTask extends Task 
{
    /**
     * Task controler to keep track of the 
     * Task state.
     */
    protected TaskController control;
 
    /**
     * Creates a new instance of the 
     * LeafTask class
     * @param blackboard Reference to the 
     *  AI Blackboard data
     */
    public LeafTask(Blackboard blackboard) 
    {
        super(blackboard);
        CreateController();
    }
    
    /**
     * Creates the controller for the class
     */
    private void CreateController()
    {
        this.control = new TaskController(this);
    }
    
    /**
     * Gets the controller reference.
     */
    @Override
    public TaskController GetControl()
    {
        return this.control;
    }
}
 

The leaf task has a TaskController for the support logic of the class, and implements the GetControl method. It has no more extra logic or methods.

The child classes of the LeafTask class are the ones with the real logic of the system, and each time we want a new behavior we are going to have to create a few. They are building blocks, modular, and they can be combined in different ways to generate different effects. Take for example simplistic Chase and a Flee strategies, they could work like this:

Chase

GetClosestEnemy
SetClosestEnemyPositionAsDestination
MoveToDestination
WaitUntilPositionNearDestination

Flee

CalculateFleeDestination
MoveToDestination
WaitUntilPositionNearDestination

The italics mark the reused leaf nodes in two different sequences of behaviors. That shows how modular leaf nodes can be recycled and used to conform many different behaviors.

Leaf tasks often calculate data needed by other leaf tasks. Instead of making a complex linking of the whole tree of tasks, we just use a common “data dump” for all of them, a Blackboard object shared by all the tasks, that simply has member data used by the different tasks.

Some examples of Leaf Nodes follow.

LeafTask Examples

GetClosestEnemyTask

Code Snippet
 /**
 * Finds the closest enemy and stores 
 * it in the Blackboard.
 * @author Ying
 *
 */
public class GetClosestEnemyTask extends LeafTask 
{
    /**
     * Creates a new instance of the 
     * GetClosestEnemyTask task
     * @param blackboard Reference to the 
     *  AI Blackboard data
     */
    public GetClosestEnemyTask(Blackboard bb)
    {
        super(bb);
    }
 
    /**
     * Checks for preconditions
     */
    @Override
    public boolean CheckConditions() 
    {        
        return Blackboard.players.size() > 1 && 
        bb.player.GetCursor().GetPosition() != null;
    }
 
    /**
     * Finds the closest enemy and stores 
     * it in the Blackboard
     */
    @Override
    public void DoAction() 
    {
        Enemy closestEnemy = null;
        // Finds the closest enemy
        // Omited for clarity
 
        // Store it in the blackboard
        bb.closestEnemy = closestEnemy;
        GetControll().FinishWithSuccess();
    }
 
    /**
     * Ends the task
     */
    @Override
    public void End() 
    {
        LogTask("Ending");
    }
 
    /**
     * Starts the task
     */
    @Override
    public void Start() 
    {
        LogTask("Starting");
    }
}
 

MoveTo

Code Snippet
 /**
 * This task requests the player to 
 * move to a given destination.
 * It takes the destination from 
 * the Blackboard.
 * @author Ying
 *
 */
public class MoveToDestinationTask extends LeafTask 
{
    /**
     * Creates a new instance of the 
     * MoveToDestinationTask class
     * @param blackboard Reference of the 
     *  AI Blackboard data
     */
    public MoveToDestinationTask(Blackboard bb)
    {
        super(bb);
    }
 
    /**
     * Sanity check of needed data for the 
     * operations
     */
    @Override
    public boolean CheckConditions() 
    {
        LogTask("Checking conditions");
        return bb.moveDirection != null;
    }
 
    /**
     * Requests the cursor to move
     */
    @Override
    public void DoAction() 
    {
        LogTask("Doing action");
        bb.player.Move(bb.moveDirection);
        control.FinishWithSuccess();
    }
 
    /**
     * Ends the task
     */
    @Override
    public void End() 
    {
        LogTask("Ending");
    }
 
    /**
     * Starts the task
     */
    @Override
    public void Start() 
    {
        LogTask("Starting");
    }
}
 

Parent Task

Parent task require a bit more explanation than leaf tasks, but don’t worry, we’ll work through it step by step. The base class is similar to the LeafTask class:

Code Snippet
 /**
 * Inner node of the behavior tree, a 
 * flow director node that selects the
 * child to be executed next.
 * (Sounds macabre, hu?)
 * 
 * Sets a specific kind of TaskController for 
 * these kinds of tasks.
 * 
 * @author Ying
 *
 */
public abstract class ParentTask extends Task 
{
/**
    * TaskControler for the parent task
    */
ParentTaskController control;
    
public ParentTask(Blackboard bb)
{
    super(bb);
    CreateController();
}
    
/**
    * Creates the TaskController.
    */
private void CreateController()
{
    this.control = 
        new ParentTaskController(this);
}
    
/**
    * Gets the control reference
    */
@Override
public TaskController GetControl() 
{
    return control;
}
 
/**
    * Checks for the appropiate pre-state 
    * of the data
    */
@Override
public boolean CheckConditions() 
{
    LogTask("Checking conditions");
    return control.subtasks.size() > 0;
}
    
/**
    * Abstract to be overridden in child 
    * classes. Called when a child finishes 
    * with success.
    */
public abstract void ChildSucceeded();
    
/**
    * Abstract to be overridden in child 
    * classes. Called when a child finishes 
    * with failure.
    */
public abstract void ChildFailed();
 
/**
    * Checks whether the child has started, 
    * finished or needs updating, and takes 
    * the needed measures in each case
    * 
    * "curTask" is the current selected task,
    * a member of our ParentTaskController
    */
@Override
public void DoAction() 
{
    LogTask("Doing action");
    if(control.Finished())
    {
        // If this parent task is finished
        // return without doing naught.
        return;
    }
    if(control.curTask == null)
    {
        // If there is a null child task 
        // selected we've done something wrong
        return;
    }
        
    // If we do have a curTask...
    if( !control.curTask.
        GetControl().Started())
    {
        // ... and it's not started yet, start it.
        control.curTask.
            GetControl().SafeStart();
    }        
    else if(control.curTask.
        GetControl().Finished())
    {
        // ... and it's finished, end it properly.
        control.curTask.
            GetControl().SafeEnd();
            
        if(control.curTask.
            GetControl().Succeeded())
        {
            this.ChildSucceeded();
        }
        if(control.curTask.
            GetControl().Failed())
        {
            this.ChildFailed();
        }
    }
    else
    {        
        // ... and it's ready, update it.        
        control.curTask.DoAction();
    }    
}
 
/**
    * Ends the task
    */
@Override
public void End() 
{
    LogTask("Ending");
}
 
/**
    * Starts the task, and points the 
    * current task to the first one 
    * of the available child tasks.
    */
@Override
public void Start() 
{
    LogTask("Starting");
    control.curTask = 
        control.subtasks.firstElement();
    if(control.curTask == null)
    {
        Log.e("Current task has a null action");
    }
}
}
 

The ParentTask class has a ParentTaskController, identical to the TaskController for the LeafNode (handles state logic, if it’s ready, finished, ect…) but adds responsibility for the child tasks (a subtasks vector) and the current selected task (curTask).

It also implements the Start and End functions, very similar to the LeafTask. But the big change comes in the DoAction function. Here it updates the child of the parent task acordingly. All Parent tasks have the same process, that can be explained conceptually more or less like this:

Safety checks to see if we have all the data, and it’s not null
If the current child task is not started, start it
Else, if the current child task is finished, finalize it propperly and check if it finished with success or failure. Here is where the different ParentTask differ, on what happens if the child fails or succeeds. (ChildSuceeded and ChildFailed virtual functions)
Else, the child must be updated, so we call it’s DoAction.

The abstract ChildSuceeded and ChildFailed functions are for the classes derived from ParentTask to specify how they behave when a child ends their execution. We have two distinct cases for this, Sequence and Selector classes.

Sequence

In a sequence of tasks, if a child ends it’s execution with a failure, we bail and the Sequence ParentTask ends with failure. This makes sense, as sequences are used for example for the Chase explained earlier:

GetClosestEnemy
SetClosestEnemyPositionAsDestination
MoveToDestination
WaitUntilPositionNearDestination

If task 2 fails, we don’t want the ParentTask to continue on to MoveToDestination, as the Destination Vec2 is possibly corrupted, and will result in undefined behavior.

On the other hand if a child finishes with success, we continue onto the next task.

Some code to illustrate this:

Code Snippet
 /**
 * This ParentTask executes each of it's children 
 * in turn until he has finished all of them.
 * 
 * It always starts by the first child, 
 * updating each one.
 * If any child finishes with failure, the 
 * Sequence fails, and we finish with failure.
 * When a child finishes with success, we 
 * select the next child as the update victim.
 * If we have finished updating the last child, 
 * the Sequence returns with success.
 * 
 * @author Ying
 *
 */
public class Sequence extends ParentTask 
{
    /**
     * Creates a new instance of the 
     * Sequence class
     * @param blackboard Reference to 
     * the AI Blackboard data
     */
    public Sequence(Blackboard bb)
    {
        super(bb);
    }
    
    /**
     * A child finished with failure.
     * We failed to update the whole sequence. 
     * Bail with failure.
     */
    @Override
    public void ChildFailed() 
    {
        control.FinishWithFailure();
    }
 
    /**
     * A child has finished with success
     * Select the next one to update. If 
     * it's the last, we have finished with 
     * success.
     */
    @Override
    public void ChildSucceeded() 
    {
        int curPos = 
            control.subtasks.
            indexOf(control.curTask);
        if( curPos == 
            (control.subtasks.size() - 1))
        {
            control.FinishWithSuccess();
        }
        else
        {
            control.curTask = 
                control.subtasks.
                elementAt(curPos+1);
            if(!control.curTask.CheckConditions())
            {
                control.FinishWithFailure();
            }
        }
    }
}
 

Selector

The selector chooses one it’s children to update, and if that fails it chooses another until there are no more left. This means that if the current chosen child ends with failure, we choose another. If we can’t choose another, we end with failure. On the other hand, if our child returns with success, we can happily finish with success as well, as we only need one of the children to succeed.

In retrospect, the Sequencer is like a AND gate, and the Selector as a OR gate, only applied to tasks instead of circuits…

Some code then.

Code Snippet
 /**
 * This parent task selects one of it's 
 * children to update.
 * 
 * To select a child, it starts from the 
 * beginning of it's children vector
 * and goes one by one until it finds one 
 * that passes the CheckCondition test.
 * It then updates that child until its 
 * finished.
 * If the child finishes with failure, 
 * it continues down the list looking another
 * candidate to update, and if it doesn't 
 * find it, it finishes with failure. 
 * If the child finishes with success, the 
 * Selector considers it's task done and 
 * bails with success. 
 * 
 * @author Ying
 *
 */
public class Selector extends ParentTask 
{
    /**
     * Creates a new instance of 
     * the Selector class
     * @param blackboard Reference to 
     *  the AI Blackboard data
     */
    public Selector(Blackboard bb)
    {
        super(bb);        
    }    
    
    /**
     * Chooses the new task to update.
     * @return The new task, or null 
     *  if none was found
     */
    public Task ChooseNewTask()
    {
        Task task = null;
        boolean found = false;
        int curPos = 
            control.subtasks.
            indexOf(control.curTask);
        
        while(!found)
        {
            if(curPos == 
                (control.subtasks.size() - 1))
            {
                found = true;
                task = null;
                break;
            }
            
            curPos++;
            
            task = control.subtasks.
                elementAt(curPos);
            if(task.CheckConditions())
            {
                found = true;
            }
        }
        
        return task;
    }
 
    /**
     * In case of child finishing with 
     * failure we find a new one to update,
     * or fail if none is to be found
     */
    @Override
    public void ChildFailed() 
    {
        control.curTask = ChooseNewTask();
        if(control.curTask == null)
        {
            control.FinishWithFailure();
        }        
    }
 
    /**
     * In case of child finishing with 
     * sucess, our job here is done, finish 
     * with sucess
     * as well
     */
    @Override
    public void ChildSucceeded() 
    {
        control.FinishWithSuccess();        
    }
}
 

Task Controller

Introduction

The task controller, as mentioned earlier, tracks the state of the Task it is added to. It keeps a reference to the task and acts as a wrapper for said class when dealing with all the “Is it finished? Is it ready to update?” kind of questions.

This code is separated from the actual task for two reasons.

Reason One: Elegance of Design.

Once we separate the state control from the task class, we can create new subtasks paying no mind to the whole mechanism going on in the background to keep our task in harmony with it’s parent and children tasks. In the Task classes we just focus on specifying the specific logic for the task at hand.

Reason Two: Safety in the Decorators

If we take the utility/state logic out of the Task class, we can make all the methods abstract, and when we create the Decorator classes, the compiler checks to see if we have overridden all the abstract functions (if we forget to wrap any of the Task functions in the Decorator, we could introduce subtle but dangerous bugs). If we have the utility functions in the Task class we may or may not remember to make a wrapper for them, and if we have to change the interface of the Task class at some point, we could be in for a hell of pain.

Code

All said, some code on how the task controller works:

TaskController

Has the done and success flags, and all the utilities related with them.

Code Snippet
 /**
 * Class added by composition to any task, 
 * to keep track of the Task state
 * and logic flow. 
 * 
 * This state-control class is separated 
 * from the Task class so the Decorators
 * have a chance at compile-time security.
 * @author Ying
 *
 */
public class TaskController 
{
    /**
     * Indicates whether the task is finished 
     * or not
     */
    private boolean done;
    
    /**
     * If finished, it indicates if it has 
     * finished with success or not
     */
    private boolean sucess;
    
    /**
     * Indicates if the task has started 
     * or not
     */
    private boolean started;
    
    /**
     * Reference to the task we monitor
     */
    private Task task;
    
    /**
     * Creates a new instance of the 
     * TaskController class
     * @param task Task to controll.
     */
    public TaskController(Task task)
    {
        SetTask(task);
        Initialize();
    }
    
    /**
     * Initializes the class data
     */
    private void Initialize()
    {
        this.done = false;
        this.sucess = true;
        this.started = false;
    }
    
    /**
     * Sets the task reference
     * @param task Task to monitor
     */
    public void SetTask(Task task)
    {
        this.task = task;
    }
    
    /**
     * Starts the monitored class
     */
    public void SafeStart()
    {
        this.started = true;
        task.Start();
    }
    
    /**
     * Ends the monitored task
     */
    public void SafeEnd()
    {
        this.done = false;
        this.started = false;
        task.End();
    }
    
    /**
     * Ends the monitored class, with success
     */
    protected void FinishWithSuccess()
    {
        this.sucess = true;
        this.done = true;
        task.LogTask("Finished with success");
    }
 
    /**
     * Ends the monitored class, with failure
     */
    protected void FinishWithFailure()
    {
        this.sucess = false;
        this.done = true;
        task.LogTask("Finished with failure");
    }
    
    /**
     * Indicates whether the task 
     * finished successfully
     * @return True if it did, false if it didn't
     */
    public boolean Succeeded() 
    {
        return this.sucess;
    }
    
    /**
     * Indicates whether the task 
     * finished with failure
     * @return True if it did, false if it didn't
     */
    public boolean Failed()
    {
        return !this.sucess;
    }
    
    /**
     * Indicates whether the task finished
     * @return True if it did, false if it didn't
     */
    public boolean Finished() 
    {
        return this.done;
    }
    
    /**
     * Indicates whether the class 
     * has started or not
     * @return True if it has, false if it hasn't
     */
    public boolean Started()
    {
        return this.started;
    }
    
    /**
     * Marks the class as just started.
     */
    public void Reset()
    {
        this.done = false;
    }
}
 

ParentTaskController

We add the subtasks vector, and curTask task to the previous responsibilities of the taskController.

Code Snippet
 /**
 * This class extends the TaskController 
 * class to add support for 
 * child tasks and their logic. 
 * 
 * Used together with ParentTask.
 * 
 * @author Ying
 *
 */
public class ParentTaskController extends TaskController 
{
    /**
     * Vector of child Task
     */
    public Vector<Task> subtasks;
    
    /**
     * Current updating task
     */
    public Task curTask;
 
    /**
     * Creates a new instance of the 
     * ParentTaskController class
     * @param task
     */
    public ParentTaskController(Task task) 
    {
        super(task);
        
        this.subtasks = new Vector<Task>();
        this.curTask = null;
    }
    
    /**
     * Adds a new subtask to the end 
     * of the subtask list.
     * @param task Task to add
     */
    public void Add(Task task)
    {
        subtasks.add(task);
    }
    
    /**
     * Resets the task as if it had 
     * just started.
     */
    public void Reset()
    {
        super.Reset();
        this.curTask = 
            subtasks.firstElement();
    }
}
 

Decorator

The Decorators are used in the BT to add special functionality to any given task. They act as wrappers of the class, calling the class methods and adding the extra functionality where they deem it necessary.

Abstract Decorator Class

A Decorator, as explained in the Decorator Pattern has a reference to the class it “decorates” (in our case private Task task), and also inherits from said class.

Normally, the Decorator adds extra logic in the DoAction method of the task, which is why the base Decorator class presented only overrides the rest of the methods of Task, for simplicity. None the less, if any Decorator subclass needs to override any other method, it can do so with no problem.

Here is the code

Code Snippet
 /**
 * Base class for the specific decorators.
 * Decorates all the task methods except 
 * for the DoAction, for commodity. 
 * 
 * (Tough any method can be decorated in 
 * the base classes with no problem, 
 * they are decorated by default so the 
 * programmer does not forget)
 * 
 * @author Ying
 *
 */
public abstract class TaskDecorator extends Task 
{
    /**
     * Reference to the task to decorate
     */
    Task task;
 
    /**
     * Creates a new instance of the 
     * Decorator class
     * @param blackboard Reference to 
     * the AI Blackboard data
     * @param task Task to decorate
     */
    public TaskDecorator(Blackboard bb, Task task) 
    {
        super(bb);
        InitTask(task);
    }
    
    /**
     * Initializes the task reference
     * @param task Task to decorate
     */
    private void InitTask(Task task)
    {
        this.task = task;
        this.task.GetControl().SetTask(this);
    }
 
    /**
     * Decorate the CheckConditions
     */
    @Override
    public boolean CheckConditions() 
    {
        return this.task.CheckConditions();
    }
 
    /**
     * Decorate the end
     */
    @Override
    public void End() 
    {
        this.task.End();
    }
 
    /**
     * Decorate the request for the 
     * Controll reference
     */
    @Override
    public TaskController GetControl() 
    {
        return this.task.GetControl();
    }
 
    /**
     * Decorate the start
     */
    @Override
    public void Start() 
    {
        this.task.Start();
 
    }
}
 

Examples

Here are some specific examples of Decorators.

ResetDecorator

Simply checks to see if the task it decorates has finished. If it has, it resets the task to “ready to execute again”.

Code Snippet
 /**
 * Decorator that resets to "Started" the task 
 * it is applied to, each time said task finishes.
 * 
 * @author Ying
 *
 */
public class ResetDecorator extends TaskDecorator 
{    
    /**
     * Creates a new instance of the 
     * ResetDecorator class
     * @param blackboard Reference to 
     *  the AI Blackboard data
     * @param task Task to decorate
     */
    public ResetDecorator(Blackboard bb, 
        Task task) 
    {
        super(bb, task);
    }
 
    /**
     * Does the decorated task's action, 
     * and if it's done, resets it.
     */
    @Override
    public void DoAction() 
    {
        this.task.DoAction();
        if(this.task.GetControl().Finished())
        {
            this.task.GetControl().Reset();
        }
 
    }
}
 

RegulatorDecorator

Updates the task it decorates at a specific speed. This case of Decorator also overrides the Start method.

Code Snippet
 /**
 * Decorator that adds a update speed 
 * limit to the task it is applied to
 * @author Ying
 *
 */
public class RegulatorDecorator extends TaskDecorator 
{
    /**
     * Regulator to keep track of time
     */
    private Regulator regulator;
    
    /**
     * Update time in seconds per frame
     */
    private float updateTime;
        
    /**
     * Creates a new instance of the 
     * RegulatorDecorator class
     * @param blackboard Reference to the 
     *  AI Blackboard data
     * @param task Task to decorate
     * @param updateTime Time between each 
     *  frame update
     */
    public RegulatorDecorator(Blackboard bb, 
        Task task, float updateTime) 
    {
        super(bb, task);
        this.updateTime = updateTime;
    }
 
    /**
     * Starts the task and the regulator
     */
    @Override 
    public void Start()
    {
        task.Start();
        this.regulator = 
            new Regulator(1.0f/updateTime);
    }
    
    /**
     * Updates the decorated task only if the 
     * required time since the last update has 
     * elapsed.
     */
    @Override
    public void DoAction() 
    {
        if(this.regulator.IsReady())
        {
            task.DoAction();
        }
    }
}
 

Example

Usage Example

With all the code mentioned earlier, it’s a little easy to get lost, so here is a reminder of how this is supposed to work. We are going to create a simple BT with just two basic behaviors, Chase and Flee. (This is taken straight from the game code).

Code Snippet
 /**
* Creates the behavior tree and populates 
* the node hierarchy
*/
private void CreateBehaviourTree()
{
    // Create a root node for the tree, that
    // resets itself and updates at 10 fps
    this.planner = new Selector(
        blackboard, 
        "Planner");
    this.planner = new ResetDecorator(
        blackboard, 
        this.planner, "Planner");
    this.planner = new RegulatorDecorator(
        blackboard, 
        this.planner, "Planner", 0.1f);
        
    // Create chase sequence
    Task chase = new Sequence(
        blackboard, 
        "Chase sequence");
    ((ParentTaskController)chase.GetControl()).
        Add(new GetClosestEnemyCursorTask(
        blackboard, 
        "GetClosestEnemyCursor"));
    ((ParentTaskController)chase.GetControl()).
        Add(new SetEnemyCursorAsDestinationTask(
        blackboard, 
        "SetEnemyCursorAsDestination"));
    ((ParentTaskController)chase.GetControl()).
        Add(new MoveToDestinationTask(
        blackboard, 
        "MoveToDestination"));
    ((ParentTaskController)chase.GetControl()).
        Add(new WaitTillNearDestinationTask(
        blackboard, 
        "WaitTillNearDestination"));
        
    // Create the flee sequence
    // It's a normal selector but with extra logic
    // to see if we want to flee or not
    Task flee = new Sequence(blackboard, 
        "Flee sequence");
    flee = new FleeDecorator(blackboard, flee, 
        "Flee sequence");
    ((ParentTaskController)flee.GetControl()).
        Add(new CalculateFleeDestinationTask(
        blackboard, 
        "CalculateFleeDestination"));
    ((ParentTaskController)flee.GetControl()).
        Add(new MoveToDestinationTask(
        blackboard, 
        "MoveToDestination"));
    ((ParentTaskController)flee.GetControl()).
        Add(new WaitTillNearDestinationTask(
        blackboard, 
        "WaitTillNearDestination"));
        
    ((ParentTaskController)this.planner.
        GetControl()).Add(flee);
    ((ParentTaskController)this.planner.
        GetControl()).Add(chase);        
}
 

Diagram

The previous code generates the Behavior Tree shown in this diagram.

Conclusion

Behavior trees are a incredibly interesting tool for game AI. They can be applied to many different types of AI and their modularity makes them a blessing when it comes to extending or modifying an existing AI.

I just hope that with this huge post I have provided the necessary tools for someone who is looking for a nice AI technique for his AI to start working and hopefully avoid the pitfalls I had to survive whilst doing this system.

Happy coding.

PS: The full code for my game Behavior Tree can be found here.

3D Picking in Android

2010-10-08T23:30:00.002+02:00

Introduction

In this short tutorial I’m presenting something that’s made me loose weeks of work. How to implement picking with a perspective camera in the Android platform using OPENGL 1.0.

The process of picking basically involves the user clicking a point in their device screen, we take that point and apply the inverse transforms that opengl applies to it’s 3D scene, and so get a point in the world coordinate system (wcs) that is where the player wanted to click. For the sake of simplicity, we will work on a simple 2D map, instead of having to cast a ray to intersect multiple objects.

Usually, in opengl we would use the function glUnProject to un-project the point and so get the wcs equivalent point, but that function is plagued by errors on the Android platform and it’ very difficult to get the gl transformations for the projection and model matrixes.

Algorithm

So here is my solution. It might not be perfect, but it actually works.

Code Snippet
 /**
    * Calculates the transform from screen coordinate 
    * system to world coordinate system coordinates 
    * for a specific point, given a camera position.
    * 
    * @param touch Vec2 point of screen touch, the 
      actual position on physical screen (ej: 160, 240)
    * @param cam camera object with x,y,z of the 
      camera and screenWidth and screenHeight of 
      the device.
    * @return position in WCS.
    */
   public Vec2 GetWorldCoords( Vec2 touch, Camera cam)
   {  
       // Initialize auxiliary variables.
       Vec2 worldPos = new Vec2();
       
       // SCREEN height & width (ej: 320 x 480)
       float screenW = cam.GetScreenWidth();
       float screenH = cam.GetScreenHeight();
              
       // Auxiliary matrix and vectors 
       // to deal with ogl.
       float[] invertedMatrix, transformMatrix, 
           normalizedInPoint, outPoint;
       invertedMatrix = new float[16];
       transformMatrix = new float[16];
       normalizedInPoint = new float[4];
       outPoint = new float[4];
 
       // Invert y coordinate, as android uses 
       // top-left, and ogl bottom-left.
       int oglTouchY = (int) (screenH - touch.Y());
       
       /* Transform the screen point to clip 
       space in ogl (-1,1) */       
       normalizedInPoint[0] = 
        (float) ((touch.X()) * 2.0f / screenW - 1.0);
       normalizedInPoint[1] = 
        (float) ((oglTouchY) * 2.0f / screenH - 1.0);
       normalizedInPoint[2] = - 1.0f;
       normalizedInPoint[3] = 1.0f;
 
       /* Obtain the transform matrix and 
       then the inverse. */
       Print("Proj", getCurrentProjection(gl));
       Print("Model", getCurrentModelView(gl));
       Matrix.multiplyMM(
           transformMatrix, 0, 
           getCurrentProjection(gl), 0, 
           getCurrentModelView(gl), 0);
       Matrix.invertM(invertedMatrix, 0, 
           transformMatrix, 0);       
 
       /* Apply the inverse to the point 
       in clip space */
       Matrix.multiplyMV(
           outPoint, 0, 
           invertedMatrix, 0, 
           normalizedInPoint, 0);
       
       if (outPoint[3] == 0.0)
       {
           // Avoid /0 error.
           Log.e("World coords", "ERROR!");
           return worldPos;
       }
       
       // Divide by the 3rd component to find 
       // out the real position.
       worldPos.Set(
           outPoint[0] / outPoint[3], 
           outPoint[1] / outPoint[3]);
         
       return worldPos;       
   }
 

In my case, I’ve got a render, a logic and an application thread, this function is a service provided by the render thread, because it needs the gl Projection and ModelView matrixes.

What happens is the logic thread sends a touch (x,y) position, and the current camera (x,y,z, screenH, screenW), to the GetWorldCoords function, and expects the world position of that point taking into accound the camera position (x,y,z), and the view fustrum (represented by the projection and modelview matrixes).

The first lines get the data ready, create auxiliary matrixes and access camera data.

One important point is the line

int oglTouchY = (int) (screenH - touch.Y());

This inversion is needed because android screen coordinates assume a top-left coordinate system, and opengl needs a bottom left. So we change it. And with that we can start doing the picking algorithm.

Transform the point from screen coordinates (ej: 120, 330) to clip space (for a 320 x 480 android, this would be –0.25, 0.375)
Get the transformation matrix (projection * modelView), and invert it.
Multiply the clip-space point times the inverse transformation.
Divide the coordinates x,y,z (positions 0,1,2) times the w (position 3)
You’ve got the world coordinates.

Notes:

The z doesn’t appear because I don’t have need for it, but you can get it easily (outPoint[2] / outPoint[3]).

The situation I’m working on is the following. The red and blue are the frustum limits, the green is the world map, at an arbitrary point in space, and the camera is at the tip of the view frustum.

There is one very special complication when doing this picking algorithm in the android platform and that is accessing the projection and model view matrixes opengl uses. We manage with the following code.

Code Snippet
 /**
    * Record the current modelView matrix 
    * state. Has the side effect of
    * setting the current matrix state 
    * to GL_MODELVIEW
    * @param gl context
    */
   public float[] getCurrentModelView(GL10 gl) 
   {
        float[] mModelView = new float[16];
        getMatrix(gl, GL10.GL_MODELVIEW, mModelView);
        return mModelView;
   }
 
   /**
    * Record the current projection matrix 
    * state. Has the side effect of
    * setting the current matrix state 
    * to GL_PROJECTION
    * @param gl context
    */
   public float[] getCurrentProjection(GL10 gl) 
   {
       float[] mProjection = new float[16];
       getMatrix(gl, GL10.GL_PROJECTION, mProjection);
       return mProjection;
   }
 
   /**
    * Fetches a specific matrix from opengl
    * @param gl context
    * @param mode of the matrix
    * @param mat initialized float[16] array 
    * to fill with the matrix
    */
   private void getMatrix(GL10 gl, int mode, float[] mat) 
   {
       MatrixTrackingGL gl2 = (MatrixTrackingGL) gl;
       gl2.glMatrixMode(mode);
       gl2.getMatrix(mat, 0);
   }
 

The gl parameter passed to the getCurrent*(GL10 gl) functions is stored as a member variable in the class.

The MatrixTrackingGL class is part of the android samples, and can be found here. Some other classes must be included for it to work (mainly MatrixStack). The MatrixTrackingGL class acts as a wrapper for the gl context, but providing the data we need. For it to work, our custom GLSurfaceView class must have the GLWrapper call, something like this.

Code Snippet
 public DagGLSurfaceView(Context context) 
{
    super(context);       
        
    setFocusable(true);
        
    // Wrapper set so the renderer can 
    //access the gl transformation matrixes.
    setGLWrapper(
    new GLSurfaceView.GLWrapper() 
    {
        @Override
        public GL wrap(GL gl) 
        { 
            return new MatrixTrackingGL(gl); 
        }
    });  
        
    mRenderer = new DagRenderer();
    setRenderer(mRenderer);
}
 

(Where DagRender is my GLSurfaceView.Renderer, and DagGLSurfaceView is my GLSurfaceView)

Holy Hole

2010-01-30T22:05:00.001+01:00

No. This is not the build up to a perverted pun. That said, let’s get on with the game!

Holy Hole was our entry for the 2009 campus party quick-compo, a coding contest with just 3 day’s time from concept to finish. It came in 4th, not bad, but not great either.

The game play is basic, you can only let the balls that match the criteria (color, shape, …) into the hole. Clicking at them sends them flying. The more balls of the correct criteria that get in, the more points you get. There are also different power-ups available.

Let’s get technical then. The game is completely coded in C# and XNA (which we learnt the day before the competition started, just for that purpose) and a bit of XML for the high score. There was no up-front design here (no time!), I did it with 2 people which I trust and have worked a lot with so communication was just sort of telepathy.

So, some specifics, here is the class diagram generated by visual studio.

Main Systems:

Ball Manager and Balls
Scene Manager and Scenes
Combo Manager and Combos

Then the XML team:

High Score
Load/Save Data

And finally some nice graphics:

Spotlight
Particle Emitter and Simple Particle

So that’s another game done. The team this time was Maria (Chuel) Cabezuelo, Victor (CyanCrey) Villanueva and me, Jaime (Ying) Barrachina. Music credit goes to Pablo (Undi) De la Ossa.

You can find the SVN here and a direct download here.

Caged

2010-01-19T08:44:00.002+01:00

Caged is a RPG game written by me and my team* in our first year (2007) at the university. The game development was difficult as hell, and fun as hell as well. I learnt to design the architecture and lead a team, while teaching the team to code. One of the most rewarding experiences in my life.

The game is written C++, using SDL and TinyXML as only support libraries. We worked on the Dev-C++ IDE and SVN. It has 20+ game levels.

Features

A scripting engine which feeds cut-scenes and dialogues from XML
A sound engine based of SDL_mixer
AI for the bots, with path finding, decision making and message system.
Core, with entity manager, event system, clocks and timers, log system, resource manager, FSM…
Physics with collision detection and some neat force driven steering behaviors.
Graphics. SDL isn't meant to be used as a Gfx engine, so the camera, the GUI, and so on was also fun to make.
Integrated game editor, to make all the xml maps for the game.
Life-saver debug mode xD

In the end, one year and 200k lines of code later, the game was completed. It won 2nd place in two different contests, “tu tambien puedes” and “CDV 2008”.

Just wanted to share my first game with the world :) Game SVN here and direct download here.

Team*

Programming

Jaime (Ying) Barrachina
Victor (CyanCrey) Villanueva
Maria (Chuel) Cabezuelo
Catalin (K_ta) Costin
David (Coper) Garcia

Art

(You know who you are ;) )

Jusep
Alberto
Kiwi
Yuna (Script writer)

Special thanks

Javier (NeoM) Belenguer (Our life saver, really)
Wynter (Zerotri) Woods

Caged from CyanCrey on Vimeo.

Meanies

2010-01-18T15:45:00.002+01:00

What's this game about?

You control a evil mastermind that's bent on taking over the world! Or at least his city.

To accomplish that, he will find and recruit as many minions as he can, and send them or lead them on missions, for the good of mankind. And of course, himself.

Where is it set?

This game is set in a small city in our age and time. You will move all over it, it's almost completely visitable, and under it, as your base is in the sewers.

What do you control?

You control small, big headed minions, each with his unique personality and stats.

How many do you control?

At any given moment, you can control up to 8 minions, tough you will usually be controlling your avatar, the evil mastermind.

What's the main objective?

Conquer the world!

This is one of the games I’m currently developing. I’m not going to say anymore about the general game design, as it’s an idea I hope to use for personal stuff, and because this blog is about the technical side.

So, let’s get technical then. The game is written in C# and XNA. It might or might not be the definite language for the game, as right now I’m using the whole thing as a prototype. The game is for windows, I’ll worry about porting and the like when I’ve actually got something.

Hum, the architecture then.

Ignore the green boxes. Right now I’ve got, starting from Game, the branches that end at: EntityManager, MapGrid and Modes done, including the Entities (as far as collision and animations are concerned), and all that hangs from MapGrid.

A quick overview of the stuff so far, and I’ll update as I code along.

SceneManager

A state machine that changes Scenes. It has only one scene active at any given time, and Scenes are discarded, not saved, when a new one is selected.

Scene

States the game can be in. Structural purpose.

PlayScene

The main scene of the game, it provides content, NOT logic. This might be a bit hard to understand, but basically, once playing, we need a second state machine to keep track of how we play. More often than not, from one play mode we don’t change the content but instead the changes are more subtle, and while we don’t want to just cram all the possible options for every situation in the PlayScene, it doesn’t make sense to swap to a new Scene and reload all assets, logic or whatever.

For example, in the game I could have the fighting, normal and dialog modes. In all of them the same graphics are still loaded, the player still is on screen, etc… The changes here are more along the lines of player control, dialogs shown, Bot decision paths…

That’s why I introduce…

Mode

Mode is the thread of your process, so to speak. PlayScene is always in a Mode, and modes can be swapped in and out easily. Modes dictate the logic the resources of the PlayScene must follow. They hold all the logic of PlayScene, and are used as different “logic paths” for the game components to follow.

And logically, Modes don’t have any “content” themselves, apart of the needed to run their own logic. You could say they are the cartridges in your gameboy, and call the shots in all the components of PlayScene.

CityMap

It’s a collection of zones, as well as an actual map where to choose a location. Only basic functionality to support one scene is implemented right now.

Zone

It’s a place with a map, scenario items and entities, so the class has the necessary tools to handle them.

MapGrid

Holds the tiles, the scenario items and a tile-collision map generated from the load files of terrain and scenarios.

And… that’s all for now. Entity deserves his own post, and the rest isn’t really developed yet. I’m still deciding what to code next… maybe some input, or perhaps some basic path finding and random movement.

AI - Planner Approach

2009-06-24T19:11:00.015+02:00

There are may ways of coding the AI for a game, each game definitely needs it's custom made AI but that doesn't mean that there aren't certain patterns to apply for similar AI in different games.

The technique I'm about to expose is primarily focused for strategy games of a reduced scope, but works wonders in them. It's basically a Planner with 3 distinct levels to control the global AI of the game (NOT the specific units).

The beauty of the system is that it's simple, elegant and robust. Simple because each module is simple. Elegant because the interaction of the simple elements makes a complex behavior, and robust because adding or modifying the game design at any level has no impact whatsoever on the general AI architecture, only in the corresponding module.

Overview:

The technique consists of 3 levels.

First there is the data generators, that calculate all the data the planner needs. Then there is the actual planner, who calculates the probability of executing each action and calls them. Finally there are the individual actions, that produce different results based on the actual game situation.

The above diagram shows an example of the Planner strategy.

A PlayerAI class has references to external data (player and map), the blue methods are data generators, the red object is the planner, and the yellow objects are actions.

Data generators:

These are usually part of the general AI class, and game specific (you won't change throughout the game because they provide general info of the game the AI needs, regardless of the actual situation).

In the example:

They provide two datum. The % of the battle that is won (to know if the AI is wining and must press the advantage being aggressive, or is losing and must quickly rally to defend) which it calculates from the number of units, defenses and overall power of both contestants. The budget the AI can spend in that turn, cause in the beginning of the game it can spend freely to create cheap units, but later on it needs to save up to create more powerful ones.

Planners:

The planner is a object the AI has. A base Planner class exists to derive different planners from, and could look something like this:

It's the planner's job to decide what to do, and here is how it goes about it.

Creation:

For each kind of scenario we have a different planner, specified in the external game data files. When we load a PlayerAI data file, we create a specific Planner object specified in that file.

In the example:
We have a PlayerAI xml file with this structure:

So we would create for our playerAI a new Planner of type "somePlanner".

Then for each Action assigned to the Planner in the data file, we create a new Action object of type "T" and add it to the planner's action vector, with it's corresponding base percentage, which represents the probability of choosing that particular action.

In the example:
We would create a Order, CastSpell, CreateUnit, CreateBuilding and Wait actions and add them to m_vActions.

Execution:

Each time the AI updates, we update the Planner passing it the data provided by the data generators. Taking those into account, it calculates the new % of choosing each action, from their base %.

Now, knowing what the chances are of executing each action, it chooses those most probable ones and executes them.

In the example:
We would get the BattleStatus and Budget, and for each of the 5 actions, update their probability of being executed according to how much money we have and wherever we are winning the battle or not.

Actions:

All the actions are objects that take the same parameters, and provide some sort of output to the rest of the game system.

They are modular, so you can add new actions, remove actions (changing the xml file of that planner) or modify particular actions (changing the code of that particular action class) and the rest of the system never needs to know.

In the example:
The Order action tells units to attack, stop or retreat, depending on the BattleStatus. The Create Units action chooses one unit or another depending on the need for offensive or defensive units. ... Finally the Wait action puts the AI on idle, so it doesn't do anything.

Notes:

The Planners and actions are implemented by a base Planner (or Action) class and derived classes for each specific Planner (or action) and using those by polymorphism.

A Player AI class might look something like this:

Engine vs. Game

2009-06-12T23:45:00.005+02:00

When immersed in amateur game programming, there's 2 ways to go. The game of the game-making, or getting skill points on engine programming.

There's plenty of strong opinions of what's better and what's not, but the truth is they both have their strong points and appeals for the beginner programmer, this must be so, or else natural selection would have claimed one of these two ways long ago.

As for what I think...

Before going in depth on either of them, I'll do a fast forward and give the definite answer to life, the universe, and everything:

Whatever you have most fun making.

That's one of the few pros of being an amateur, you can actually code just for fun, whatever goes your way. Putting that aside, lets have a look at some real arguments:

Engine:

Pros:

You learn, not more (quantity of knowledge is in direct correlation to, basically, quantity of work, wherever making engines or games), but more basic. You go down a deeper level and fight with elemental bugs. As with everything in life, the more you work on the basics, the more skill you'll achieve in the long run.
You get a head's up on engine design and architecture, which will make using any 3rd party engine much easier, cause after figuring out the logical way to design that entity class, you won't be surprised when you find a physx::Actor and see some of the physical methods you did for your engine.
As you probably won't be writing the whole engine from the most basic level (bliting pixels to screen using hardware functionality for example, is too basic level) you'll get the hang of a lot of auxiliar libraries. Maybe opengl for gfx, tinyXML for those weapon data files you wanted, or sdlMixer for making your speakers blast some sound.

Cons:

Its boring, up to a degree. Sure, you always have the hard-core programmer's joy of implementing a new feature here, tweaking a system there, but there's always a point when not seeing results starts eroding morale. It's not too bad per-se, but it can quickly kill a project, and that is something to be avoided.
It's harder, which to some translates to boring, which takes us to the above logic.
When all is said and done, you actually have nothing to show. No game here to play and show of to family and friends, nothing visible to put on your portfolio.

Game:

Pros:

You learn to make a game, which is a obscure science that no one can teach. Something like illumination, but with a lot more networking involved.
You have a shinny new gem to add to your portfolio, and to impress chicks at bars (well, some chicks, at some bars at least).
You get your hands dirty with a full featured engine, and learn from their design and their functionality.
It's easier, and faster, make that much much faster.
You have things visible from near the start, and there is nothing for keeping morale up like seeing little everyday improvements to your project.
It gives you security, as you finish one game after another, and that in turn makes you push a bit further, take bigger challenges.

Cons:

Half the work is done already. So that's one part you won't be needing to sweat, but it's also a part you're not gonna learn how it works.

Conclusion:

The above is my personal experience, so the conclusion will be my personal advice:

Make some games, get the feel of some engines, see what works and what doesn't. Those structures and systems you build time and again (entity manager, log system, menu state machine, any of those ring a bell?) save them up and re-utilize them from game to game, that way you'll be making them generic.

When you've done that, make an engine. Learn from the bottom up, get a paper tablecloth and sketch a full blown design of the engine, and implement it with care and dedication.

That over with, get back to making games, and if the engine works fine, remember to release it to the nice folks of the interwebs, so we can learn from you!

Game - Phagocitosis

2009-06-10T19:04:00.006+02:00

Phagocitosis is a 1 week, simple, small puzzle game I created some months back.

It was developed in ActionScript with Adobe Flash CS4, using the KeyObject library as the only external help. A friend proposed the subject and I couldn't resist the challenge of coding a game and learning a new IDE and language at the same time, so here's how I went about it.

Design:

The Game Design was informal and written in miscellaneous pieces of paper, napkins, and the back of envelopes. It was mainly done by my buddy Undi. It took several months of sporadic work to get the general idea working.

Once the game design was over with, the Investigation and Technical Design phases began, in parallel. As it happens with new technologies, you can't design the technical aspect until you know how they work, and you can't know what you need to investigate until you know what you need.

The result of that phase was this Technical Design Document (TDD), (well, actually a draft, it was a quick development so it didn't need detail) specked with investigation notes, and this list of references:

Also, some interesting book titles:

Game Development With ActionScript
Essential ActionScript 3.0

Development:

The very first thing you come to realize when jumping into the Flash bandwagon is that there's ActionScript 2.0 and ActionScript 3.0 and that alone can shoot everything to hell.

I chose AS 3.0 on the grounds that, tough it might have a smaller support base, for learning purposes it's always a good idea to go for the next thing, as technologies outdate incredibly fast in this field.

After a few false starts, getting Adobe Flash working and setting up a SVN got me ready to start coding.

The game was built based on 3 things, the scenario, the player (a slimy Amoeba) and the enemy (a simple hole, if you fell in, you died).

The scenario was set up as a series of keyframes in the main timeline of Adobe Flash, with each keyframe having an associated Enter, Execute and Exit functions, creating a Finite State Machine to provide for all the screens of the scenario.

Scenes:

Menu
Scene Selection
Play
Pause
Game Over
Game Won

And you can guess what each one represents ;)

Each scene had it's own challenges, but the 2 biggest ones were:

Making buttons: 5 out of the 6 Scenes needed buttons, and those introduced me to the world of callbacks in AS, coupled with event handling and corresponding objects from the IDE to code entities.

The map: I wanted to have a easy way to create new levels and add them, and as I was using mappy to generate xml files of the levels, it stood to reason I had to have a in-game xml interpreter that also had access to the tilemaps and rendered the complete map. Now that was fun.

And everywhere, I had to take out my magical photoshop and produce crappy graphic after crappy graphic to fill my scene. I tried for a simple animation of the Amoeba and failed dramatically, after which I gave up and focused on static gfx.

The Amoeba and the Hole:

Each of these elements had to move around the map without charging trough walls. The pixel perfect collision detection was a real bugger, even tough the game only has 4 directions available.

The Amoeba was player controlled, so it needed a bit of input-handling magic, which had me fighting key input for more than a few hours.

The Hole on the other hand, was AI driven, and it uses a special pathfinding approximation algorithm based on it's relative position to the amoeba, instead of going for a full pathfinding with Dijkstra or A*. Not too surprisingly, this hack, apart from making the game run MUCH faster, made it more fun, as you could bait the hole to come out of certain areas instead of just waiting for it to chase you.

Game Play and Map-Making:

Final logic was added, specifically:

Collision between Hole and Amoeba results on player death
Collision between player and Objective results on loading next map
Map loading and changing
Game Over and Game Win
Select scene (start the game from a specific map)

Map after map was produced (special thanks to my brother there) each with different challenges, and tweaked to make them have a smooth difficulty curve (tough different players disagree on that one).

The End:

Final touches where made on the last wee hours of the morning in the last day of the development week, and a html file created for quick play without having to payload it to a server.

The game can be found at the SVN, along with all the code. Or if you prefer, a direct download.

Enjoy!

Cocos2D iPhone Research

2009-06-10T12:50:00.008+02:00

Cocos2D is one of the top choices when choosing an iPhone game development engine, THE top choice if you're looking for something free. Works great in 2D and has one of the best scene graphs I’ve seen out there.

First up, a list of interesting links to guide the efforts of the aspiring Cocos2D programmer.

For starters, here is monoclestudios. This company decided to give a little bit back to cocos2D, as a thanks for using it for one of their games writing a walk trough that explains how to get a Cocos2D project working.

Once you've got that over with, you still need some preparation before heading on the path to adding cocos2D to your basic arsenal. The class hierarchy of the documentation must be read carefully to get a general idea of the engine works. Making your synapses comprehend the connections between the different classes will give you a good foothold.

With that bit of theory as reference, you can now enjoy the wonderful article written by Will Larson, showing the idea of how to work with the basic pillars of Cocos2D. After that one, you should have enough idea of the engine to draft a basic game architecture.

What our life needs right now, apart of a nice cup of coffee, is a step-by-step, code spiced, dummy game, to show how everything actually works, and to provide some working code for us to play with. Start reading those articles from the bottom, you won't be disappointed. Of special interest, I would point out the detection of user input, physics with chipmunk and a custom made particle effect in that series of tutorials.

That's about it! With that nice collection you can get well on your way with your iPhone game coding skills.

Code hard and have fun!

Magic Scrolls of Code

State Machines By Example: A Useful FSM

Introduction

FSM

State

Making it Useful

Changing State at the Proper Time

Push & Pop

Timed Update

The Code

Finite State Machine

State

Conclusion

More advanced concepts of getting cocos2dx working on Android from Windows 7

Introduction

Moving The Folder

Adding Chipmunk to the Compilation

Automating the Process

Making the resource load faster

One Click Process

Conclusion

Quick and dirty guide to getting cocos2dx working on Android from Windows 7

Step by Step

Step 1: Get all the android material

Step 2: Get all the cocos2dx material

Step 3: Get the create-android-project.bat working

Step 4: Creating the project

Step 4.1: Include the source files

Step 4.2 : Adding the libraries

Step 4.3: Adding dlls

Step 5: Use the .bat to create an android project

Step 6: Fill in the meat

Step 6: Run Cygwin to compile

Step 7: Create a project in eclipse and import the Pong project

Baddies 4–Saving

Introduction

Objective

Considered options

Serialization

Serializing with the IntermediateSerializer

Working with the Node

Dictionary of shared resources for serializing in XNA

Introduction

Contents

Background

Code

Dictionary evolves to… SharedResourceDictionary!

SharedResourceDictionarySerializer

Calling the serializer

Notes

XNA Serialization to XML tutorial

Introduction

What is serialization?

Why these tutorials?

Windows only

Serialization example

A look at MSDN serialization

Steps

Code

Notes

Data that XNA serializes

Leads for more complex serialization magic

4 Quick rules

Conclusion

XNA Notes–Day 6

XNA Notes–Day 5

Content Processor

Content Importer

Content Writer

XNA Notes–Day 4

Effects

States of the graphics device

Render targets

Baddies 3–Editor

Showing the game in a PictureBox

Coupling game and form

Creating a map

Loading a TileSet

Baddies 2.8–Map

Baddies 2.7–GUI Input Management