Like many other games engines, Project::OSiRiON supports the loading of object geometry saved as 3D model files. The engine supports the ASCII Scene Export format (.ase files) and the Quake 3 map format (.map files).

Modelers using 3D modeling packages like 3D Studio Max or Blender can export their creations to the .ase format. Mappers used to working with GtkRadiant, NetRadiant or other Quake 3 level editors, can use the .map format directly, there is no map compiler involved.

The .map format can also be used as a container: it is possible to import other models as sub-model in a .map file (see the misc_model entity) and add Project::OSiRiON-specific entities like lights, engine flares and weapon locations.

The engine uses submodel instancing making it possible to re-used submodels with a minimal performace impact.

• Textures and Materials
  • Shader files
• Creating models with Radiant
  • Brushes and sizes
  • Caulk
  • Clip
  • Detail brushes
  • Lights
  • Flares
  • Particles
  • Function groups
  • Submodels
  • Other entities
• Useful commands

The engine can use TGA, JPEG and PNG images as textures and uses a simple script based materials system similar to Quake 3 Arena shader files. Materials make it possible to use special textures like player and engine color, or to apply certain effects to a texture image.

The file materials/shaderlist.txt contains a list of shader files that can be used by the engine. Each shader file can contain several materials.

The default shaderlist.txt looks like this:

common
colors
glass
kuroto

On startup, the engine will read materials from the files materials/common.shader and materials/colors.shader. When loading a .map or .ase file the engine will check if a texture name matches a known material. If a match is found, the engine will use the settings found in the material script.

In radiant, the materials can be used as normal textures, like you can with Quake 3 Arena shaders. A number of default materials are already defined and can be used out of the box.

The materials in the colors/ directory can be used to draw brush faces with a specified color. The actual RGB color is defined by the material script. Examples are red, green and blue.

The default set of colors is rather limited, more colors can be added by using the common/ family of materials. The actual in-game color information for these faces will be provided by the engine.

The common/entity material represents an object's primary color. In-game the faces with this texture will be drawn with the primary color of the entity that uses the model. For example, a player's ship will have its owner's color. Similar, the material common/entity_second represents the secondary color of an entity. common/entity_third will be a mix of the primary and secondary color. Each of these materials also has a _dark variant.

There are two special material that will cause the brush faces to be ignored by the engine: as explained above, the common/caulk material can be used on hidden faces. The common/clip material is reserved for future use brush faces using this texture will be ignored as well.

For .ase models, the material name inside the .ase file is interpreted as an osirion material. If you'd use a material called common/entity, those model faces will rendered using the object's primary in-game color, regardless of the actual material settings in the .ase file. Note that the actual ase material name is used, not the name of the diffuse texture used by that material.

If a model material has no special definition, the engine will try to load the texture with the same name, like the material models/cargo/crate/crate.

Shader files contain material definitions: each material is defined by its name, and for each material a number of flags can be set to tell the engine how to handle it.

for example, the definition of the textures/common/caulk material:

// material name
textures/common/caulk
{
    // image used by the map editor
    qer_editorimage textures/common/caulk.tga
    // polygons using this material are ignored
    ignore
}

This material has the name textures/common/caulk, this means the rules for this material have to be applied to each model face that uses it. In Radiant, this means every patch or brush with the common/caulk texture (note that Radiant doesn't show the textures/ prefix). For .ase files, it means every triangle with a material that is called textures/common/caulk.

This material has the ignore flag: model geometry with this material will simply be ignored.

A second example is the textures/common/entity material:

// material name
textures/common/entity
{
    // image used by the map editor
    qer_editorimage textures/common/entity.tga
    // use entity color
    entity
}

This material has the entity flag set: it means model geometry with this material will be rendered in entity color. For spaceship this means player color.

// material name
textures/ship/plating_entity
{
    // use entity color
    entity
    // use a texture, texture name and material name don't have to be the same
    texture textures/ship/plating
}

The .map models for the game were created with NetRadiant, in theory any editor capable of exporting Quake 3 .map files could be used. Support for files which can be used with NetRadiant or GtkRadiant 1.5 are included in the data distribution. Refer to the file INSTALL on where to find them and how to install them. No map compiler is necessary, the engine reads the .map files directly.

You can also use the NetRadiant distribution from http://ingar.satgnu.net/gtkradiant. Note that it does not include the Project::OSiRiON support files by default.

This sectio will not explain how to use the editor. Consult google for numerous tutorials on this subject. All basic brush editing techniques for any Quake-engine based game can be used.

The main difference with other games is that you are not creating a map for a 3d-shoot'em'up, but obviously, an object that has to be loaded into a space game.

Because there is no map compile involved, and the engine is fundamentally different, some points should be take under consideration.

The engine only supports brushes only, patches will be ignored. A large number of complex brushes is supported, but I advise not to go below grid size 1. As with any engine it is still possible to create brushwork that gets messed up due to rounding errors.

When the model is loaded, the bounding box is calculated. The model will be automaticly centered around the center of the geometry. All visible faces will be converted to triangles. At the moment the practical triangle count limit for a model is between 20,000 and 30,000 brushes. The engine is capable of handling a lot more, but think about the fact that a large station might be placed in a system filled with player ships and other objects.

The limits of map coordinates are placed on +/-16384 map units. Placing brushes outside these bounds will have unpredictable results. The engine will rescale models as required, therefor the actual size of the map in the editor is not that important.

The front of a model points along the positive X-axis, the positive Z-axis is up, the positive Y-axis is left. In Radiant, the nose of a spacesip or the front of a spacestation should point to the right.

Any brush face that has the common/caulk texture will be ignored on load. Note that common/caulk is actually a special material with the ignore flag set.

Like in Quake 3 maps, all invisible brushes faces should have the this material.

Any brush face that has the common/clip texture will be ignored on load. Note that common/clip is actually a special material with the ignore flag set. Clip is reserved for future use.

As with other engines, Osirion supports the use of detail brushes, but with a twist: detail brushes will only be rendered if the model is within detail range, close enough to the camera. When it is further away, only structural brushes will be rendered. The actual detail range depends on the size of the model.

This means that any object that could only been seen from close by should be made from detail brushes.

This has one improtant implication: if you show the structural brushes only (with the CTRL+D filter in Gtkradiant) there should be no obvious gaps of caulk that were previously hidden behind detail brushes.

Unlike quake, light entities are not used to add lighting information to the level but to add point lights to a model. Adding a light will render a light flare texture in the corresponding location.

The flare value indicates what texture will be used to draw the light. The flare value is translated to a texture name, bitmaps/fx/flare??. The default flare texture is flare00.

The light value is used to determine the size of the flare. The engine default is 100, resulting in rather large flares.

The default _color is white, but the color can be set through radiant's color menu (K key). If the entity option (spawnflag 2) is set, the color value will be ignored and the light will be rendered with the color of the entity it is attached to.

The strobe option (spawnflag 1) will create a blinking light. A number of options can be set to manipulate the flashing behaviour. By default a strobe light will be half a second on, half a second off.

The frequency value changes the number of flashes per second.

The offset value changes the moment the light will be on. Offset is measured in seconds.

The time value sets the fraction of time the light will be on. The default is 0.5.

Lights will only be rendered if the model is within detail range.

I also came across this usefull information: http://en.wikipedia.org/wiki/Starboard
In short, the green light should be on the right side, the red light on the left side.

The default light entity creates omnidirectional lights. To create a directional flare, use the fx_flare entity. Values for a fx_flare are the same as those for a default light, with one small diference: the size of the flare is set through the radius value. The default flare radius is 100. Rotate the entity or set the angle value to point the flare in a different direction.

Setting the entity option (spawnflag 2) will assign the entities primary colour as flare colour.

Use the engine option (spawnflag 4) to create a flare that lights up depending on engine power.

The direction of the flare can be set with the pitch, yaw and roll keys. The angle key is an alias for yaw. The angles key allows you to to set pitch, yaw and roll angles in a single key value.

Flares will only be rendered if the entity is within detail range.

Add a fx_particles entity to attach a particle system to the model. They can be used to add effects like trails and smoke. A particle system must be defined in particles.ini before it can be used.

The script value must be set to the label of the particles script.

Setting the entity option (spawnflag 2) will assign the entities primary colour as particle system colour.

Use the engine option (spawnflag 4) will assign the models engine colour as particle system colour.

The axis of the particle system can be set with the pitch, yaw and roll keys. The angle key is an alias for yaw. The angles key allows you to to set pitch, yaw and roll angles in a single key value.

Particles will only be rendered if the entity is within detail range.

Brushes can be grouped together into funcion groups. These groups can be used to create moving parts in a model.

func_door will be used to create animated doors (not implemented)

func_group an editor utility to group brushes together.

func_rotate will create a rotating set of brushes. The center of the rotation is automaticly calculated as the geometrical center of the group. The rotation axis can be set with the pitch, yaw and roll keys. The angle key is an alias for yaw. The angles key allows you to to set pitch, yaw and roll angles in a single key value.

misc_model can be used to add a submodel.

location_cockpit, location_dock, location_turret and location_cannon are reserved but have not yet been implemented.

location_cockpit will be used to indicate where the cockpit of a vessel is located and will be used to place the camera in cockpit mode.

location_dock will be used to indicate the location of docking ports.

location_cannon will create an attachment point for a cannon. Cannons are forward shooting guns.

location_turret will create an attachment point for turrets. Turrets point upwards or downwards.

The client has a built-in model viewer, you can view any model by executing the testmodel command:

testmodel maps/colonial/alexandria

You can load all models referenced by the game at once by executing the r_loadmodels command. This makes it easy to find missing models, missing textures or to spot other related problems.

r_loadmodels

Use the list_model command to get a list of currently loaded models:

list_model