# Scenery description in XML

## 0 About this document

This document describes version 3 of the CRRCsim scenery file format.

Disclaimer: This document is not complete yet. It may be inaccurate or wrong, too.

This document does not provide complete examples. Please take a look at the scenery files you got when downloading/installing CRRCsim. The file `simple.xml` in CRRCsim's `scenery` folder demonstrates many of the features discussed in this document.

You need to know basics about xml files: they are structured text. Whitespace and line breaks do not matter in most places. Just take a look at the examples and you will understand.

The files can be edited using a text editor. There are lots of them. Use something like Notepad++, vi, emacs, joe... Even the standard Windows notepad will do, but it is recommended to use an editor that features syntax highlighting for XML files to spot any obvious formatting errors immediately.

### 0.1 Changes

2010-01-01 | J. Reucker | First version of this document.
2010-01-09 | J. Reucker | Added details about rotation axes in model based scenery.
2010-05-16 | J. Reucker | Changed sky definition schema: Now multiple sky sections are allowed in a single XML file.

## 1 General information

Like most other XML files used in CRRCsim, a scenery description starts with the XML file header and a changelog. Whenever you edit such a file, please add a new `change` section and fill in what is needed. The example below shows a template.

    <?xml version="1.0"?>

    <crrcsimSceneryFile version="4">

      <!-- Some general information -->
      <name>My scenery</name>
      <categories>
        <category>Field</category>
      </categories>
      <description>
        <en>My first scenery file for CRRCsim.</en>
      </description>
      <changelog>
        <change>
          <date>2009-12-20</date>
          <author>Jan Reucker (slowhand_47@gmx.de)</author>
          <en>Created.</en>
        </change>
      </changelog>

Every text is written in english, so it is enclosed in `<en> </en>`. If you want to add something in italian for example, you should enclose it in `<it> </it>`. Other languages than `en` are not supported yet by CRRCsim, so at the time of writing information in other languages is solely visible for those reading or editing your scenery file directly.

## 2 Units

All numeric attribute values in a scenery file are written as plain numbers without engineering units. All length or position values are assumed to be in feet (ft).

## 3 Coordinate system

All positional values are specified using the following attributes:

Attribute | Axis (internal) | Direction
--- | --- | ---
north | x | positive north, negative south
east | y | positive east, negative west
height | -z | positive up, negative down

The attributes listed in the table above are used in all tags specifying some kind of position. In earlier versions of CRRCsim, the attributes `x`, `y` and `z` were used. This is still possible for specifying object positions in a model-based scenery (for compatibility reasons), but it's strongly discouraged and may be removed in future versions of CRRCsim without further notice.

## 4 Player positions: section `views`

This section defines possible viewpoints for the player. Currently CRRCsim will only use the first `position` that is found in the `views` section.

      <views>
        <position name="default" north="0" east="0" height="4"  />
      </views>

## 5 Starting positions: section `start`

The starting position for the model. As with the player position, you may specify more than one starting location. The topmost position will be used as default.

      <start>
        <position name="field" north="0" east="0" height="4"  />
      </start>

## 6 Default values: section `default`

Some default values. Right now, you may only specify the default wind parameters.

      <default>
        <wind velocity="3" direction="180" />
      </default>

## 7 Appearance of the sky: section `sky`

The appearance of the sky is determined by the `<sky>` tag. There are two different types of sky available: a sky dome and a sky box. A scenery file can contain an arbitrary number of sky definitions. This allows for simulating different weather conditions or time of day, or providing different texture resolutions to adapt textured skies to the available GPU power.

### 7.1 General description

The sky section should contain a brief description, which is in turn composed of a long and a short description. The short description is used in menus or list boxes, while the long description may contain some more information.

      <descr_short>
        <en>default</en>
      </descr_short>
      <descr_long>
        <en>The default sky box with 512x512 pixel textures.</en>
      </descr_long>

### 7.2 Sky dome

The sky dome produces a sky like in the first CRRCsim version. Think of it as a textured semi-sphere above your head. You can set the texture and the radius of the semi-sphere.

      <sky type="original" texture="textures/clouds.rgb" radius="10000">
        <descr_short>
          <en>original</en>
        </descr_short>
        <descr_long>
          <en>The original CRRCsim textured sky dome.</en>
        </descr_long>
      </sky>

If you omit the texture name, CRRCsim will generate an untextured but colored (from grey haze on the horizon to deep blue in the zenith) semi-sphere. This may help those people with broken OpenGL implementations that don't get the textured dome right.

      <sky type="original" />

### 7.3 Sky box

After CRRCsim version 0.9.6, a new sky rendering method was implemented: The sky box. It's nothing but a cube with the viewer/player in the middle. A texture can be projected onto each cube face. If the textures are seamless and feature the right kind of distortion for the cubical projection, this will give a very realistic impression of the sky.

      <sky type="box" size="10.0">
        <descr_short>
          <en>default</en>
        </descr_short>
        <descr_long>
          <en>The default sky box with 512x512 pixel textures.</en>
        </descr_long>
        <textures>
          <north filename="textures/skybox_n.rgb" />
          <south filename="textures/skybox_s.rgb" />
          <west  filename="textures/skybox_w.rgb" />
          <east  filename="textures/skybox_e.rgb" />
          <up    filename="textures/skybox_u.rgb" />
          <down  filename="" />
        </textures>
      </sky>

Cube faces without a texture will not be rendered.

There are several tools available that deal with artificial landscape/sky generation. Most of them should be able to generate a set of textures for the sky box. TerraGen, for example, works like a charm. Just generate a flat terrain (remember, we're interested in the sky, not the terrain!) and set up the sky. Set up the camera with a 90 degrees field of vision (FOV) in the center of the terrain at zero altitude, zero pitch, heading north. Render a 512x512 pixel image (or any other power-of-two square format, like 256x256 or 1024x1024, if your graphics card can handle it). This is the "north" texture. Now only change the camera heading to 90 deg. and render the "east" texture, while 180 deg. and 270 deg. are the setups for "south" and "west". Then point the camera back north and pitch it up 90 degrees to render the "up" texture. If you also want to add a "down" texture, pitch the camera down to -90 degrees while looking north and render. Remember to save all textures after rendering! The textures will be saved as ".bmp" (Windows bitmap) files, please convert them to SGI format (".rgb", turning on RLE compression is strongly recommended). Then fill in the texture names in the XML file, copy the textures to the "textures" subdirectory and enjoy your new sky.

## 8 The scene description: section `scene`

The last tag in the current files tells CRRCsim what to render in addition to the sky. This description starts with the `scene` tag. The `type` attribute of this tag defines the semantics of the tags inside the `scene` section.

The optional `altitude` attribute of this tag defines the altitude (in feets) of scenery. It is useful in scenery of mountain to take into account the variation of air density. The height parameters in the scenery description are values relative to this altitude.

### Built-in sceneries: `type="built-in"`

There are two built-in sceneries in CRRCsim: Davis field and the slope at Cape Cod. To render these sceneries, specify either `DAVIS` or `CAPE_COD` as the value of the `variant` attribute of the `scene` tag.

Rendering the Davis field scenery:

      <scene type="built-in" variant="DAVIS" />

Rendering the Cape Cod scenery:

      <scene type="built-in" variant="CAPE_COD" />

There's nothing more to configure for these `scene` variants.

### Model-based sceneries: `type="model-based"`

#### Adding objects to the scenery

Everything between <scene> and </scene> describes graphical objects. The order of the objects is not important.

The `object` tag loads a 3D model and adds it to the scenery. A lot of different file formats are supported. AC3D files (.ac) and (.3ds) should work quite well. In theory, the SSG library loads many more formats (.x, .dxf, .ase, .atg, .mdl, .flt, .m, .md2, .obj, .tri, VRML), but this is not yet tested with CRRCsim due to the lack of models. Other SSG-based projects show that it works.

A `terrain` attribute declares the object to be part of the terrain contour. This means that the object will add to the terrain height at this point and therefore be included in wind calculations. Be careful, each `terrain` object will also increase the CPU workload more than non-terrain-objects! The default value for the `terrain` attribute is "1", so `terrain="0"` must explicitely be specified to exclude an object from terrain height calculations.

An object can be loaded once and then placed several times in the scenery. This saves texture memory, because all textures are shared between the instances of the object. Each instance must have position coordinates (`north`|`east`|`height`) and optional orientation parameters (`h`|`p`|`r` for heading, pitch and roll). North, east and height coordinates must always be specified as absolute world coordinates (remember, the unit is "ft."). Heading, pitch and roll are related to local body coordinates of the object (in degrees). The orientation of the heading/pitch/roll rotations is similar to the coordinate system used for the airplane model: heading specifies a rotation around the vertical (z) axis, pitch rotates around the horizontal lateral (y) axis, and roll rotates around the longitudinal (x) axis.

Here's a simple example:

        <object filename="freqboard.ac" terrain="0">
          <instance north="20.0" east="-160" height="0" h="90" p="0" r="0" />
        </object>

This frequency board is located 20 feet north and 160 feet west of the scene origin. It faces east (it is rotated 90 degrees around the vertical axis). The board is excluded from height calculations.

#### Collision boxes

If you exclude complex models from being part of the terrain by setting `terrain="0"`, the airplane can fly right through them. The usual solution for this issue is to add a collision box to the scene. A collision box is an object of very low complexity that is not rendered (so it is not visible in the scenery). Instead it is only used for collision detection and height calculation.

Although the term "collision box" is widely used for this kind of object, their shape is not limited to boxes. In theory, arbitrary objects can be loaded, but please bear in mind that the goal of using collision boxes is to reduce the triangle count for collision detection, so using a box, a pyramid or a similar low-poly shape is a good idea.

The objects can have arbitrary material properties, colours or textures. CRRCsim will exclude them completely from the rendering stage, so the models don't have to be transparent. But textures and materials will consume memory, so the collision objects should be made from a single material without a texture.

To add an object as a collision box, simply set the `visible` attribute of an object to "0":

        <!-- A collision box for a static aircraft model -->
        <object filename="aircraft_collbox.ac" visible="0">
          <instance north="-70.0" east="60" height="0" h="45" />
        </object>

#### Embedded collision boxes

Instead of adding two separate objects for the visible representation and the collision box, you can combine both objects in a single 3D model file. To tell CRRCsim which parts of the 3D model shall be visible and which parts belong to the collision box, make use of the node naming feature of your 3D modelling tool. CRRCsim will treat everything up to the first space character as the part's real name, everything else is interpreted as an attribute. Each attribute consists of a plus or minus sign followed directly by a keyword. The following attributes are supported:

Attribute | Effect
--- | ---
-visible | Exclude this part from rendering (make it invisible)
-terrain | Exclude this part from height-of-terrain calculations

For example, in Blender, each part of a model is called an "object". You can assign individual names to each object. Let's assume that you model a picnic table to be placed in your scenery. Create a new object and call it "table -terrain" (object panel, edit the datablock name field to read "OB:table -terrain"). Model your table. Then create a new object, call it "box -visible" and model the collision box. Select table and box and export both to an AC3D model. Then add this model to your scenery file in the usual way, but don't specify any "terrain" or "visible" attributes in the XML file. CRRCsim will automatically make the box invisible and ignore the table for height calculations.

## 9 End of file

      </crrcsimSceneryFile>