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.
| 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" |
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.
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).
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.
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>
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>
Some default values. Right now, you may only specify the default wind parameters.
<default>
<wind velocity="3" direction="180" />
</default>
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.
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>
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" />
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.
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" />
The definition is placed at the same level as the other sections
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.
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.
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.
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.
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"
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.
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!
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.
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.
</crrcsimSceneryFile>