Tutorial: Creating your first application

Introduction

This tutorial will cover the very first steps for creating a new FIFE application. Please note if you are trying to follow along with this tutorial you will first need to copy the file <fife>/demos/rpg/settings-dist.xml into the same directory as your .py files.

Get started

If you're a bit curious you surely have already consulted the run.py file present in each current FIFE demos. Not yet? So let's do it together :

from fife import fife
print "Using the FIFE python module found here: ", os.path.dirname(fife.__file__)
 
from fife.extensions.fife_settings import Setting
from scripts.rpg import RPGBaseApplication
 
TDS = Setting(app_name="rpg", settings_file="./settings.xml")
 
def main():                                                                                                                                                                        
        app = RPGBaseApplication(TDS)                                                                                                                                              
        app.run()                                                                                                                                                                  
 
if __name__ == '__main__':                                                                                                                                                         
        if TDS.get("FIFE", "ProfilingOn"):                                                                                                                                         
                import hotshot, hotshot.stats                                                                                                                                      
                print "Starting profiler"
                prof = hotshot.Profile("fife.prof")
                prof.runcall(main)
                prof.close()
                print "analysing profiling results"
                stats = hotshot.stats.load("fife.prof")
                stats.strip_dirs()
                stats.sort_stats('time', 'calls')
                stats.print_stats(20)
        else:
                if TDS.get("FIFE", "UsePsyco"):
                        # Import Psyco if available
                        try:
                                import psyco
                                psyco.full()
                                print "Psyco acceleration in use"
                        except ImportError:
                                print "Psyco acceleration not used"
                else:
                        print "Psyco acceleration not used"
                main()

Don't be afraid by all this code and let's get focused on what is really important in the context of this tutorial.

First interesting line :

TDS = Setting(app_name="rpg", settings_file="./settings.xml")

This line create a new Setting instance by providing the application name (in this case "rpg") and the settings file. This instance will be use to create our main application.

We create a new application by creating a RPGBaseApplication instance :

app = RPGBaseApplication(TDS) #we pass the Setting instance to our application

And to run it :

app.run()

In the next section we will see how the RPGBaseApplication class works.

The application class

RPGBaseApplication is the name of our main application (we are writing a RPG) so let's see how it looks like :

class RPGApplication(ApplicationBase):
        """
        The main application.  It inherits fife.extensions.ApplicationBase.
 
        Implements ApplicationBase._pump().
        """
        def __init__(self, TDS):
                super(RPGApplication,self).__init__(TDS)
                self._settings = TDS
 
                self._gamecontroller = GameController(self, self.engine, self._settings)
 
        def createListener(self):
                """
                @note: This function had to be overloaded otherwise the default
                listener would have been created.
                """
                self._listener = ApplicationListener(self.engine, self._gamecontroller)
                return self._listener
 
        def requestQuit(self):
                """
                Sends the quit command to the application's listener.  We could set
                self.quitRequested to true also but this is a good example on how
                to build and dispatch a fife.Command.
                """
                cmd = fife.Command()
                cmd.setSource(None)
                cmd.setCommandType(fife.CMD_QUIT_GAME)
                self.engine.getEventManager().dispatchCommand(cmd)
 
        def _pump(self):
                if self._listener.quit:
                        self._gamecontroller.endGame()
                        self.quit()
                else:
                        self._gamecontroller.pump()
 
 
        def _getLogManager(self):
                return self._log

So as you can see, to create a FIFE application, we have to create a class which inherits from the ApplicationBase one (located in fife.extensions.basicapplication module).

The __init__ method

In this method we do two things :

• Keep trace of our Setting instance :

self._settings = TDS

• Create the game controller :

self._gamecontroller = GameController(self, self.engine, self._settings)

Don't yet worry about the game controller creation. Just admit for the moment that this will be the class that handles the game process and it is not the point of this tutorial to explain how to write a kind of game controller

The createListener method

This method will create a custom listener for our application. A listener can be seen as a method which attempts to get an event (from keyboard, mouse etc...) and handle it. For example, if you want to make your application shut down after the ESCAPE key is pressed, it will be handled by a listener. Writing a listener will be covered by another tutorial.

requestQuit method

Read the comments, this method is an example of using FIFE command. We will not take care of this method since it's not provided by ApplicationBase.

_pump method

This is maybe the most important method of your FIFE application. It's called every frame when the application is running (application.run()).

def _pump(self):
    if self._listener.quit:
        self._gamecontroller.endGame()
        self.quit()
 
    else:
        self._gamecontroller.pump()

If you omit how the game controller really works, this method is really easy to understand. Every frame we check if the quit attribute of our listener is 'True'. If it's the case, the user has requested the application to shut down, so we end the game process :

self._gamecontroller.endGame()

and quit the application with quit() method provided by ApplicationBase :

self.quit()

In the other case, the application have keep running so we update the game process :

self._gamecontroller.pump()

Now you should have a FIFE application up and running.

To summarize

Steps

If the basics of application concepts in FIFE was not already clear enough to you, it should be the case after reading this. We will summarize the key steps to build your own FIFE application.

• Write your application class that inherits from the AplicationBase class provided by FIFE engine and override all the methods you need
• In your main file (run.py for example), create your Setting instance
• Use this Setting instance to create an instance of your application and use the run() method to run it :

TDS = Setting(...)
 
app = YourApplication(TDS) #create your application instance
app.run() #and run it, all your game start here

Application diagram

Just to show the position of your application in a FIFE based game :