# 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.
2012-01-25 | J. Liénard | Added preview sections
2015-12-30 | L. Gasparini | Added details about new object attributes
2016-01-20 | L. Gasparini | Added details about new object population feature and translucent rendering attribute
2016-03-28 | L. Gasparini | Added details about new object attribute "shadow"

## 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, but you may select a different one from the "Launch" dialog: selecting "Launch from start" instead of the default "Launch from player" shows a drop list of the available start position.

      <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 Preview

A preview image is a small image of the scenery. It is used in the dialogue of scenery selection `(Options / Location)`. This image has to have, preferably, a dimension of 256x128 pixels and be in a file format accepted by Plib for textures. The format `.jpg` is accepted.

The file used as preview is indicated by the tag `<preview>`

      <preview filename="textures/simple_preview.jpg" />

### Only one preview by scene

The definition is placed at the same level as the other sections

### Several previews

If the scenery contains some variant of sky, it is possible to indicate a specific preview has each. It is necessary for it to put the definition in the accordant sky section.

      <sky type="box" size="10.0">
        <preview filename="textures/simple_thunderstorm_preview.jpg" />
        <descr_short>
          <en>Sky of thunderstorm</en>
        </descr_short>
        <textures>
          <north filename="textures/skybox_th_n.rgb" />
          <south filename="textures/skybox_th_s.rgb" />
          <west  filename="textures/skybox_th_w.rgb" />
          <east  filename="textures/skybox_th_e.rgb" />
          <up    filename="textures/skybox_th_u.rgb" />
          <down  filename="" />
        </textures>
      </sky>

It is possible to mix both syntaxes: if a varying of sky has no preview, the generic preview is used.

## 9 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 mostly not important but it may actually influence: rendering speed, rendering effects of translucent objects, vertical position of an objects if attribute `above_ground="0"`. For faster rendering opaque object should be defined in order front-to-back, while for best rendering quality translucent objects should be defined last and ordered back-to-front.

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.

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. There currently are two options to place objects in the scenery: `instance` and `population`. An `instance` adds a single copy of the object in a specific location, while a `population` adds several copies of the object distributed over an area of the scene.

#### Object attributes

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.

A `visible` attribute declares the object to be visible. Invisible objects are not rendered but they add to terrain height and are thus included in wind calculation. They are used to define collision boxes (see below). A non-visible object which is also non-terrain is actually useless... The default value for the `visible` attribute is "1".

The `translucent` attribute (default value "1") influences how translucent objects (i.e. objects having alpha information) are rendered. The actual meaning depends on the object being terrain or non-terrain.

A terrain object with `translucent="1"` is rendered translucent (using so-called alpha blending), while if `translucent= "0"` then it is assumed that it shall be rendered fully transparent and it only has the purpose of: a) being used for terrain height and wind computations, b) hide objects behind it. This is different from an invisible terrain object, which does not hides objects further back. Terrain objects with `translucent="0"` are in fact intended to be used for terrain in photo-realistic sceneries, where the visual apparence of the terrain is actually incorporated into the skybox textures, but the terrain shall anyway mask objects located behind it. In theory, setting `translucent="0"` allows a faster rendering than leaving it to 1, while achieving the same effects.

A non-terrain object with `translucent="1"` is also rendered translucent (using alpha blending), but additionally all areas with alpha < 0.1 (i.e. almost fully transparent) are discarded so that objects behind stay visible. This allows rendering of objects with highly transparent areas (e.g. a tree texture applied to a simple rectangle) without unrealistically masking objects behind. However, correct rendering of the translucency requires back-to-front order, and rendering is slower. If `translucent="0"`, instead, the texture is assumed to be an on-off one (alpha either 0 or 1), and only areas with alpha almost 1 are rendered as fully-opaque, while other areas are discarded. This allow a similar but faster and fully order-independent rendering of partially transparent objects (again think about a tree as before), althoug with lower rendering quality. Actually a trick is implemented which allows for a nice, order-independent, artifact-free, although slower, rendering of partially transparent objects.

The `cutout` attribute declares the object to be automatically rotated along its vertical (z) axis so to always face the viewer (i.e. the x-z plane is kept parallel to the camera). It is useful to render such things as trees using a low poly object and a texture. As such it is typically used for non-terrain objects. The default value for the `cutout` attribute is "0"

The `shadow` attribute declares that the object shall cast shadows. So far casted shadow, for both airplanes and scenery objects, are computed usign the "shadow volumes" algorithm. The default value for the `shadow` attribute is "0"

#### Instance

Each instance must have position coordinates (`north`|`east`|`height` or `x`|`y`|`z`) 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.

The additional attribute `above_ground="1"` may be used to specify that the given height is to be intended above local ground level: thus `height="0"` is a handy way to place the object right on the ground (assuming that the origin of the 3D object model is located at its lowest point). Note that by default `above_ground="0"`.

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.

#### Population

Objects in a population are distributed regularly (like a matrix of objects) in a parallelogram-shaped area of the scene. One vertex of the parallelogram is the origin of the area, whose position in absolute world cordinates is specified by (`north`|`east`|`height` or `x`|`y`|`z`). The two sides of the parallegram exiting from the origin are given by vectors (`d1_north`|`d1_east`|`d1_height` or `d1_x`|`d1_y`|`d1_z`) and (`d2_north`|`d2_east`|`d2_height` or `d2_x`|`d2_y`|`d2_z`). Every component of d1 and d2 vectors defaults to 0.

The total number of objects in the population is `n1` times `n2`, with `n1` the number of objects along each line parallel to edge d1, and `n2` the number of objects along each line parallel to edge d2.

The regular distribution of the objects may be perturbed to make it somewhat irregular, hence more "natural". Spacing in d1 and d2 directions may be perturbed by `d1_noise` and `d2_noise`, with location being altered by up to +/-0.5 times noise value.

The size of the objects can be altered too (bigger/smaller) as well as their vertical dimension (taller/shorter) and horizontal dimension (fatter/slimmer) specifying respectively non-zero `s_noise`, `sz_noise` and `sx_noise`. Size noise values are in percentage of original object size. They all sum-up to define actual object size and shape. Note that overall scale noise only reduces object size, while x and z scale noise perturbes object size both increasing and reducing the respective original dimension.

The additional attribute `above_ground="1"` is again used to specify that the given height is to be intended above local ground level.

Here's a simple example:

        <object filename="populus_nigra.ac" terrain="0" cutout="1">
          <population above_ground="1"
            north="-450" east="500" height="0"
            n1="61" d1_north="900" d1_east="0" d1_noise="3"
            n2="9" d2_north="0" d2_east="240" d2_noise="3"
            s_noise="0.03" sx_noise="0.05" sz_noise="0.05"/>
        </object>

This is a small woods occupying a rectangular area of size 900x240 feets, the longer edge being aligned in north-south direction. The trees are distributed along 9 rows of 61 trees each. The location of each tree is perturbed up to +/-1.5 feets in each direction. Tree size may be reduced up to 3%; additionally, tree may be taller/shorter or larger/thinner by up to +/-2.5%. The trees are excluded from height calculations. In fact they are simple 2D images, as indicated by the attribute `cutout="1"`. A collision box (see below) will likely be specified subsequently. Note that because using `above_ground="1"` the collision box must in fact be specified AFTER the population, otherwise it will sit on top of the collision box!

#### 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 (hence wind calculation as well).

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>

The default value for the `visible` attribute is "1", so `visible="0"` must explicitely be specified to make an object invisible.

#### Embedded attributes

Instead of adding two separate objects for the visible representation and the collision box/terrain height, 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 terrain (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 may be changed within an object file:

Attribute | Effect
--- | ---
+terrain | Include this part in height-of-terrain calculations
-terrain | Exclude this part from height-of-terrain calculations
+visible | Include this part in the rendering (make it visible)
-visible | Exclude this part from rendering (make it invisible)
+translucent | Translucent (alpha blending) rendering
-translucent | Non-translucent (fully opaque or fully transparent) rendering

Note that the attributes optionally assigned to each individual object in the file override the default setting specified in the scenery file. Also note that the `cutout` attribute cannot be altered within a file. Additionally, only the `-shadow` attribute can be used within a file to avoid an object casting shadows, however by default NO object will cast shadow unless the `shadow = 1` attribute is specified in the scenery description. The use of `+shadow` embedded attribute has no effect in this respect.

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.

## 10 End of file

      </crrcsimSceneryFile>