= How to create Orxonox Levels =
[[TracNav(TracNav/TOC_CC_Tut)]]

== Create the basic file ==
 1. Go to the folder __../data/levels__. The level files ending with .oxw are simple XML files and can be opened with any editor. Each level file stored in this folder can be selected later in Orxonox.
 2. Copy „empty_level.oxw“ and paste it again in the folder.
 3. Rename the copy. Try to use a name that sounds good. Avoid whitespace – use „_“ or CamelCase instead.
 4. Open your level with your favourite editor.

== About XML ==
XML is a description language that looks similar to HTML. We use tags to describe objects:
{{{
#!xml
<templates>                               <!-- Opening tag 1 -->
    <Template link=lodtemplate_default /> <!-- Opening and closing tag 2 at once -->
</templates>                              <!-- Closing tag 1 -->
}}}
							
A tag can contain several attributes. An attribute is the place where a value is set.
{{{
#!xml
<Light type=directional position="0,0,0" direction="0.253, 0.593, -0.765" diffuse="1.0, 0.9, 0.9, 1.0" specular="1.0, 0.9, 0.9, 1.0" />
<!-- Quite a lot attributes. -->
}}}
The syntax is attribute=“vaule(s)“. If only one value is set, the quotation marks are not necessary.

Tip: XML files do not have to be compiled. If you changed a level file (and didn't forget to save it), you simply have to reload the level to view the changes. In Linux you can switch between the game and the editor by pressing [alt] + [tab]. If you insert only a little error and try to load a level the game will „stuck“. By pressing [alt] + [tab] you can leave the game and view the error message on the terminal.

== First steps ==
 1. Define the level's name in the menu. The "description" will be displayed, when a player hovers his mouse over your level's "name". This should be the first tag in the XML file.
{{{
#!xml
<LevelInfo
 name = "Teambase Match"
 description = "Fight for the bases."
 tags = ""
/>
}}}
 2. Decide wether you create a level for a gametype or a single player mission. A gametype is set in the <level> tag.
{{{
#!xml
<Level
 name         = "Presentation"
 description  = "A simple testlevel"
 gametype     = TeamBaseMatch
>
}}}
 3. Set the levels backgroud. The level's background is called skybox and is an image of what you can seen on the horizon. You can add an new skybox by changing the corresponding parameter:
{{{
#!xml
<Scene
    ambientlight = "0.5, 0.5, 0.5" 
    skybox       = "Orxonox/Starbox" 
>
}}}
Possible values for skybox are:
|| "Orxonox/Starbox" || "Orxonox/skypanoramagen1" || "Orxonox/skypanoramagen2" || "Orxonox/skyBoxMoreNebula" ||

== Basics ==
 * Worldentity: Point in space with orientation ( ~point with a vector attached to it).
  * Static Entity: Worldentity with a fixed position and fixed orientation.
  * Movable Entity: Worldentity that can rotate or move constantly.
  * Controllable Entity: Completely freely movable point. Usually steered by a controller.
 * Model: Each visible 3d-Object. A model consists of a mesh (the form) and a material (the surface colouring).
 * Collisionshape: A Collisionshape is the physical representation of a model. Currently collisionshapes only have the form of a sphere, cube/ashlar, cone or plain. For StaticEntities the collisionType is „static“. Movable Entities have the collisionType "dynamic". At the moment static collisionshapes do not provide a shield against bullets. The collision of projectiles is only detected by dynamic collisionshapes.

== Worldentity + Model + Collisionshape = adding objects to the level ==
{{{
#!xml
<StaticEntity position="0,-10000,0" direction="0,-1,0" collisionType=static mass=100000 friction=0.01 >
    <attached> 
        <Model position="0,0,0" mesh="cube.mesh" scale3D="10000,10000,1000" /> 
    </attached> 
    <collisionShapes> 
        <BoxCollisionShape position="0,0,0" halfExtents="10000,10000,1000" /> 
    </collisionShapes> 
</StaticEntity>
}}}
The StaticEntity defines the model's place and orientation (and some other values). The Model (a cube) is attached to the StaticEntity. With the proper sized collisionshape attached to the StaticEntity you have a "solid" cube. Without a collisionshape, the cube wouldn't be solid and your spaceship could just fly through it. This exampe is quite useful, since you usually can't see a collisionshape's size. If you combine a invisible collisionshape with a fitting model you can see where a collisionshape is for testing purposes.

== MovalbeEntity - Let's get the world moving==
Worldentities can be attached to other worldentities. If you want a model to move in circles, you can create a MovableEntity that rotates and a StaticEntity attached to it. The model that should be rotating is attached to the StaticEntity.
{{{
#!xml
<?lua
    dofile("includes/CuboidSpaceStation.lua")
  ?>
<!-- ----------------Rotating SpaceStation--------------- -->
<MovableEntity position="1,1,1" rotationrate="-4.5" rotationaxis="0,0,1">
    <attached>
        <StaticEntity position="-2500,0,0" yaw=90 pitch=90>
            <attached>
                <?lua
                  createSpaceStationPar(0,2,1,2,1,4,1,50)
                ?>
            </attached>
        </StaticEntity>
    </attached>
</MovableEntity>
}}}
Note that in this example there Model is created by a lua script that is called in a lua tag. Lua is a scripting language that is a very powerful tool for level design.

== Spawpoints ==
A Spawnpoint is the entrance point for controllable entities (spaceships). Without a spawnpoint no level can work!
{{{
#!xml
<SpawnPoint team=0 position="-200,0,0" lookat="0,0,0" spawnclass=SpaceShip pawndesign=spaceshipassff />
}}}
You can define which kind of spacecraft a player/ bots can use. Additionally the corresponding template has to be included:
|| '''pawndesign''' || '''include()''' || '''additional information'''||
||spaceshipassff||"templates/spaceship_assff.oxt"||default spaceship - equiped with rockets||
||spaceshippirate||"templates/spaceship_pirate.oxt"|| ||
||spaceshipswallow||"templates/spaceship_swallow.oxt"||fast||
||spaceshipHtwo||"templates/spaceship_H2.oxt"|| ||
||spaceshipghost||"templates/spaceship_ghost.oxt"||stealth aircraft ||
||spaceshipHXY||"templates/spaceship_HXY.oxt"||'''diffenrent steering''': you have to press the right mouse button to steer!||
||spaceshipHXYSL||"templates/spaceship_HXY_SL.oxt"||normal steering, really fast||
||spaceshipTransporterSL||"templates/spaceship_Transporter_SL.oxt"||slow transporter||
||spaceshipTransporter||"templates/spaceship_Transporter.oxt"||slow transporter, equal to SL version||
If the level is designed for several teams you have to use team spawn points.
{{{
#!xml
<TeamSpawnPoint team=0 position="1000,0,0" lookat="0,0,0" spawnclass=SpaceShip pawndesign=spaceshipassff/>
}}}

== [http://www.orxonox.net/doxygen/classorxonox_1_1_pickup_spawner.html Pickups]  ==
Pickups give a player a tomporary bonus, if he is able to flight through the pickup. Bonuses are invisibility, health, boost,  shield, a drone, ...
 1. Include the pickups.
{{{
#!xml
<?lua 
    include("includes/pickups.oxi") 
 ?>
}}}
 2. Add a PickupSpawner. An invisible device that puts pickups in the level.
{{{
#!xml
<PickupSpawner position="-160,65,10" triggerDistance="10" respawnTime="5" maxSpawnedItems="10">
    <pickup> 
        <InvisiblePickup template=mediuminvisiblepickup /> 
    </pickup> 
</PickupSpawner>
}}}
 * triggerDistance: Distance to collect the pickup. The larger the triggerDistance, the easier it is to get the pickup.
 * respawnTime: After respawntime seconds a new pickup will appear, if the pickup had been collected.
 * maxSpawnedItems: After maxSpawnedItems no further pickup will appear.