Basic PPS Tutorial

This is a basic tutorial for new PPS students to get familiar with our framework and build environment. The process is described for tardis here. If you use another system first go to the [download] page and make sure you have all dependencies installed.

Preparations

We check out the source and media repository and build for the first time

1. Create your orxonox directory (if not already existing):

   mkdir ~/orxonox
   cd ~/orxonox
   

2. Now check out the latest revision of the media repository (you will probably be asked for a username and password once):

   svn co https://svn.orxonox.net/data/Media
   

3. Now get the latest revision of the trunk:

   svn co https://svn.orxonox.net/orxonox/branches/orxonox_tutorial
   

4. Prepare to build:

   mkdir trunk/build
   cd trunk/build
   cmake ..
   

5. Now build for the first time (may take some time, further builds will be faster):

   make -j4  #-j4 means to create 4 parallel compile processes
   

6. Additionally you can use KDevelop3? as IDE to develop (if you don't want to use the console )

Start the game for the first time

7. Enter to the appropriate folder and start the game. You will see a menu popping up, just press the Standalone button.

   cd ~/orxonox/trunk
   ./run
   

Now we extend the Ship As you might have recognized some features of the Ship were missing:

• No special effects
• You can't fire in continuous mode

TutorialShip Class

We have derived a new type of SpaceShip for you: TutorialShip. The back end doesn't have to bother you (you will notice that some functions don't seem to be doing anything at all).

Loading the right type of ship

At the moment, you are loading an object of the SpaceShip class. We would like to change this. Fortunately this can be done in an XML file where we load the level.

1. Go to your media repository (orxonox/Media) and open tutorial.oxw in the level folder with a text editor like vim, nano, etc.
2. Find the second paragraph (about 5th line) and change SpaceShip to TutorialShip
3. Save the file. You can keep it open, we need it again later.

CMake files adjustments

Next thing will be to change the code accordingly, since the game will probably crash now when started.
We organise our source files via CMake as you have already found out. You now have to tell CMake to also compile the TutorialShip:

1. Open orxonox/trunk/src/orxonox/CMakeLists.txt
2. You will see a large list of source files (*.cc). You can add "oxonox/TutorialShip.cc" anywhere you like, but it is preferred to organise the file a little bit. So look for SpaceShip.cc and add things there.
3. Save and close.

Coding: RegisterObject() and SetConfigValue()

The interesting part: Modifying the C++ code. Open orxonox/trunk/src/orxonox/objects/TutorialShip.cc. As you have already heard from Fabian, the Core Framework is like a language extension to C++. But it cannot be fully automatic. That means you have to add a few lines accordingly:

1. Find the constructor (TutorialShip::TutorialShip()) and add RegisterObject(TutorialShip); as the first statement. This is used for the class hierarchy and for the ObjectLists. Whenever you derive from OrxonoxClass or any derivative, this call is necessary.
2. Next will be creating a configurable value in our class. This enables us to configure the TutorialShip from outside (Shell or orxonox.ini). Go to the setConfigValues() and configure the member variable reloadTime_ with a default value of 0.125. Remember the syntax:

   SetConfigValue(''variable name'', ''default value'').description(''description text'');
   

Coding: ConsoleCommand

3. The console command: It enables you to call a static function in the shell. Currently, our TutorialShip cannot fire any projectiles because there is no ConsoleCommand for "fire". This code is static, so we have to go to the beginning of the source code, just after namespace orxonox {. Now add a ConsoleCommand for the static function fire() of the TutorialShip:

   SetConsoleCommand(''class name'', ''function name'', true).keybindMode(KeybindMode::''mode'');
   

   keybindMode specifies how the console command should be treated when used on a key. OnHold means the command gets fired continuously, OnRelease and OnPress only once.
   

First run test and the Shell

We haven't done everything yet, but a little function test would be nice. Compile Orxonox and run it just according to instructions above. If it doesn't compile at all, try to understand the error message and if that doesn't help, ask an assistant.
You should now see exactly what you saw last time. The ship still won't fire anything. To change that we can assign that static fire() function to a key or button. To do that, open the console with the key just above "tab". To bind a console command to a key, type keybind fire (keybind is a command itself actually), hit enter and then hit the key or button you would like to assign the command to (preferably the left mouse button…). Close the console and try to fire a projectile (mouse would also work with an open console).

orxonox.ini and the "config" command

Now exit the game by hitting Esc or typing "exit" into the console. In order to change the reload time of the ship's weapon open src/bin/orxonox.ini and look for the section called [TutorialShip]. There you should see the entry reloadTime_. Set it to 1.0, save the file and start orxonox again (you don't need to compile anything now). Laggy weapon, right? To change it back open then console and enter "config T". Hit tab then and you will see a list of classes starting with "T" having config values (only TutorialShip for now). Hit tab again and the shell completes your text. Hit tab two times more and it will even complete the (only) configurable value reloadTime_. You can see the old value being 1.0 above. You need to add a value to the command in order to change the ConfigValue. Complete instruction now:

config TutorialShip reloadTime_ 0.1

You should now be able to fire quicker. It doesn't yet go faster than the framerate though.

Declare XML loading

This part is about how you can load class parameters with XML. Unlike ConfigValues, XML parameters are per object instead of per class. That means you can load multiple objects of the same class with different settings. We are now going to add one XML parameter for the TutorialShip class.
Find the XMLPort() function in the source file. You can see that there is comment but no statement after it. That's where you can insert the macro which specifies a parameter. Keep in mind that when loading with XMLPort, you need to have an access and a store function (not just a variable). These have already been created for the specialEffects parameter which tells the underlaying SpaceShip whether to visualise the special effects. The syntax for XML parameters is:

XMLPortParam(classname, parameter name as string, setSpecialEffects, hasSpecialEffects, xmlelement, mode);

(You only need to adjust the first two macro parameters)

Configuring the XML parameter

Where to modify that XML stuff now? Of course in an XML file. It is the same that you have already opened previously when switching from SpaceShip to TutorialShip. Look at the XML attributes: The first ones sound cryptic and are on one line. Ignore them and add a new line afterwards. Here you can configure your self declared XML parameter:

<TutorialShip
    # Some unimportant parameters. Better don't mess with them ;)
    camera="true" position="0,0,0".......
    # Your own. Set it to "false" to disable showing special effects.
    name-of-your-parameter="true"
/>

Logging messages

Stay in the XMLPort() function and add a statement at the end to display a log message with output level 3:

COUT(3) << "My name is Bond. James Bond." << std::endl;

Your job is to make the message sound meaningful for this particular XMLPort() function.

Final run

Compile and run again. You should now see the TutorialShip having thrusters, a trail and blinking lights.