= 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 [wiki:download#Source download] page and make sure you have all dependencies installed.

== Preparations ==
'''We check out the source and data 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 data repository (you will probably be asked for a username and password once):
{{{
svn co https://svn.orxonox.net/game/data/trunk data_extern
}}}
 3. Now get the latest revision of the tutorial:
{{{
svn co https://svn.orxonox.net/game/code/branches/tutorial tutorial
}}}
 4. Prepare to build:
{{{
mkdir tutorial/build
cd tutorial/build
cmake-2.8.3 ..
}}}
 5. Now build for the first time (may take some time, further builds will be faster):
{{{
make -j3  #-j3 means to create 3 parallel compile processes
}}}
 6. Additionally you can use [wiki: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 ''Quickstart'' button.
{{{
cd ~/orxonox/tutorial/build
./run
}}}

== Before you start coding ==
Before you start coding there's one [wiki:howto/XMLPort page] which is extremely useful for the following tasks. You might want to have a look at it.

== The task ==
Our goal  is to create a drone in Orxonox that, that does some kind of autonomous flying.
In Orxonox we try our best to separate different kinds of functionality. You will see, that this is also the case here.
In the case of the drone, we want to create, we separate the drone itself (called AutonomousDrone) from the entity that controls  the drone (called the AutonomousDroneController) and the thing that gives shape and texture to our drone (basically that is the model). Or put more crudely, the AutonomousDrone is the physical entity, the AutonomousDroneController is its intelligence and the model is it's visual representation. This is done for several reasons, the most important being, that with this kind of separation we can have multiple  controllers for just one drone, we could also have one controller for multiple types of flying objects. And the behavior of our drone is independent of how it looks like. That makes your code more generic and leads to cleaner code, less dependencies and also less code in general.

== The AutonomousDrone ==
At first we need to create the drone itself. The drone provides the functionality of physically having a place in the game world (because it's a WorldEntity) and being able to move in it.

{{{
#!html
<p style="text-align: left; color: red">Note: Do not just copy & paste! Most commands / codelines need to be edited. But that doesn't mean you shouldn't copy & paste, but you should stink about whether what you paste should be modified and how.</p> 
}}}
Otherwise you'll get tons of compiler errors. ;)
We created for you the skeleton of an autonomous drone. You can find the code in the files ''src/orxonox/worldentities/AutonomousDrone.{cc|h}'' and ''src/orxonox/controllers/AutonomousDroneController.{cc|h}'' in the trunk folder that you checked out from our repository.

 1. Open the file ''AutonomousDrone.cc'' and have a look at the code (the file can be found in ''src/orxonox/worldentities/'').
 2. In order to be able to create an AutonomousDrone object from the XML file just by using the class name, you need to add a call of ''CreateFactory(Classname)'' somewhere inside the ''.cc'' (global, inside the namespace). This is best done just above the constructor.
{{{
CreateFactory(ClassX);
}}}
Note: You have to replace ''ClassX'' with the appropriate class.
 3. Make sure that each drone object gets registered to the core by adding a call of ''RegisterObject(Classname)'' inside the constructor.
{{{
RegisterObject(ClassX);
}}}
 4. Now go to the function called ''XMLPort''. ''XMLPort'' allows you to specify how your class can be instantiated (i.e. how an object can be created) purely through XML. This is important when we want to create levels, which in Orxonox are specified in XML files.
Add the calls for the two variables ''auxiliaryThrust_'' and ''rotationThrust_''. As you can see, the XMLPort function for the variable ''primaryThurst_'' has already been specified. Now add the calls for the other two variables accordingly, you can compare your function calls to the call for ''primaryThrust_'' to get a feel for, whether what you have been doing could be correct or not.
{{{
XMLPortParam(Classname, "xml-attribute-name (i.e. variablename)", setFunction, getFunction, xmlelement, mode)
}}}
 Note: You need to add set- and get-functions for ''auxiliaryThrust_'' and ''rotationThrust_'' inside the ''AutonomousDrone.h'' file (have a look at {get/set}PrimaryThrust).
 5. Now you need to add the AutonomousDrone to the build system. Open the file ''src/orxonox/worldentities/CMakeLists.txt'' and add ''AutonomousDrone.cc'' to the ORXONOX_SRC_FILES. This makes ''cmake'' consider the ''AutonomousDrone.cc'' file for further builds.

That's it for the AutonomousDrone class.

If you have been having '''problems''', consider the following suggestions, that might help you resolve them.
 * Is the classname that you specified for ''CreateFactory(Classname)'' and ''RegisterObject(Classname)'' correct? If it is either ''Classname'', ''ClassX'' or ''ClassXY'', then it is incorrect, try to think about what it should be. If you can't find the solution ask one of the assistants.
 * Have you created 2 set-functions and 2 get-functions for the two variables ''auxiliaryThrust_'' and ''rotationThrust_''?

== The AutonomousDroneController ==
Now you will finish the AutonomousDroneController which gets called each tick and steers the drone using the functionality of movement in the game world that the drone provides. 

 1. Open the file ''AutonomousDroneController.cc'' and look at it (''src/orxonox/controllers/'').
 2. Have a look at the constructor and make sure nothing is missing (think of the core).
 3. now look at the tick function. it gets called each time before a new frame is drawn. you can put in some steering code here. if you want you can use some functions provided by Math.h:
{{{
rnd() // return a random value between 0 and 1
sin() // should be clear (also cos)
// many other functions (have a look at src/util/Math.h for details)
}}}
 4. repeat step 5 (CMakeLists) of the AutonomousDrone for the AutonomousDroneController.

== The XML Part ==
As a last step we will include the drone in our level and add the visual part of the drone, the model. (and some other stuff, too)

Now that you finished the classes you can recompile the project. Afterwards open the level file:
 1. Open ''tutorial/data/levels/tutorial.oxw''.
 2. We want to add a drone to the level now, so put in an entry for it (below the comment that tells you to do so). Look at this example:
{{{
<ClassX variable1="2" string1="blabla" coord1="1,0,0">
</ClassX>
}}}
 3. Now add the appropriate entries for the variables you defined in AutonomousDrone/4. (Have a look at ''data/levels/templates/spaceship_assff.oxt'' for example values)
 4. As we want our drone to be visible we have to attach a model to it. Add the following code between the above 2 lines:
{{{
  <attached>
    <Model scale="10" mesh="drone.mesh"/>
  </attached>
}}}
 this adds a model with the mesh drone.mesh and the defined textures at the position of our drone object.

 5. Because the physics engine needs a collision shape to work with, we will add the following entry (before </ClassX>):
{{{
  <collisionShapes>
    <BoxCollisionShape position="0,0,0" halfExtents="10, 10, 10" />
  </collisionShapes>
}}}
 this will tell the physics engine what dimensions our drone has (in this case its just a cube).
 6. Now we define the mass and two damping parameters of our drone. Append definitions for the following variables as attributes to your drone. (as in 3.)
{{{
mass = 50
linearDamping = 0.9
angularDamping = 0.7
}}}
 Note: The Drone definition should now look like this: 
 {{{
 <AutonomousDrone primaryThrust="<...>" <...> mass=50 linearDamping=0.9 angularDamping=0.7>
 }}}

== Have a look at your AutonomousDrone ==
 - Now recompile the code, start the game again and have a look at how your drone behaves.
 - Don't worry if it does not react to your steering commands as expected. Try to modify some things.
 - If you want to do some more things you can try to let the drone fly in circles or helixes.
 - Play around a little bit with the linear/angular-Damping parameters.

== Commit your code to the repository ==
We may want to use your steering function later on, so commit it now:
 1. Make sure you have a recent version of the branch:
{{{
~/orxonox/tutorial$ svn up
}}}
 2. In order to avoid conflicts copy your file (''AutonomousDroneController.cc''):
{{{
~/orxonox/tutorial$ svn cp src/orxonox/objects/controllers/AutonomousDroneController.cc src/orxonox/objects/controllers/AutonomousDroneController_myUserName.cc
}}}
 3. Make sure you don't commit any changes of the original file, so revert your local changes on it:
{{{
~/orxonox/tutorial$ svn revert src/orxonox/objects/controllers/AutonomousDroneController.cc
}}}
 4. Now commit:
{{{
~/orxonox/tutorial$ svn ci -m "This is my version of the AutonomousDrone steering function" src/orxonox/controllers/AutonomousDroneController_myUserName.cc
}}}