<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html lang="en">
<head>
	<meta HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=UTF-8">
	<link rel="stylesheet" type="text/css" href="style.css">
	<TITLE>The Osirion Project - Creating models</TITLE>
</head>
<body>
<H1>
	The Osirion Project - Creating models
</H1>
<p>
	The engine supports two kind of models: The first one are
	Quake 3 style .map files with custom osirion entities. The second
	one are .ase models. Textures are supported, but no advanced features
	like normal mapping.
</p>
<p>
	The .map format allows for a quick and easy way to create usable
	3D models, while the .ase format allows importing more complex
	models made with modelling packages. The .map format is also used
	as a container format to place tags on models, like lights, 
	smoke trails and weapon locations.
</p>
<p>
	.ase models can be loaded as sub-models into a .map file,
	making modular spaceship design possible. Ship parts like engines
	can be placed into seperate files and reused in other models.
</p>
<p>
	The rest of the document describes how to create models using
	GtkRadiant and contains mostly information specific to creating
	models for The Osirion Project. Even if you can handle GtkRadiant,
	it is still worth a read.
</p>
<h2>
	Content
</h2>
<p>
<ul>
	<li><a href="#gtkradiant">Creating models with GtkRadiant</a>
	<li><a href="#brushes_and_sizes">Brushes and sizes</a>
	<li><a href="#caulk">Caulk</a>
	<li><a href="#clip">Clip</a>
	<li><a href="#detail_brushes">Detail brushes</a>
	<li><a href="#materials">Materials</a>
	<li><a href="#shaders_files">Shader files</a>
	<li><a href="#lights">Lights</a>
	<li><a href="#flares">Flares</a>
	<li><a href="#particles">Particles</a>
	<li><a href="#groups">Function groups</a>
	<li><a href="#submodels">Submodels</a>
	<li><a href="#other_entities">Other entities</a>
</ul>

<h2 id="gtkradiant">
	Creating models with GtkRadiant
</h2>
<p>
	All the models for the game were created with GtkRadiant 1.5,
	in theory any editor capable of exporting Quake 2 .map files could
	be used. Support for files for 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.
<p>
	If you are using a linux-based operating system, you can also use 
	the GtkRadiant distribution from <a href="http://ingar.satgnu.net/gtkradiant">http://ingar.satgnu.net/gtkradiant</a>.
	Note that it does not include the Osirion support files by default.
<p>
	This document 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.
<p>
	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.
<p>
	Because there is no map compile involved, and the engine is fundamentally
	different, some points should be take under consideration.

<h2 id="brushes_and_sizes">
	Brushes and sizes
</h2>
<p>
	The engine 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.
<p>
	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.
<p>
	The limits of map coordinates are placed on +/-16384 map units. Placing
	brushes outside these bounds will have unpredictable results. The map 
	will be scaled down to make 1024 units in radiant correspond to 1 game unit.
	One game unit corresponds to 100m in-game. 16 units in radiant will
	therefor correspond to 1.5625 meters in-game.
<p>
	The front of a model points along the positive X-axis, the positive
	Z-axis is up, the positive Y-axis is left. In GtkRadiant, the nose of
	the spacesip or the front of a spacestation should point to the right.

<h2 id="caulk">
	Caulk
</h2>
<p>
	Any brush face that has the <i>common/caulk</i> texture will be ignored on load.
</p>
<h2 id="clip">
	Clip
</h2>
<p>
	Any brush face that has the <i>common/clip</i> texture will be ignored on load.
	Clip is reserved for future use.
</p>
<h2 id="detail_brushes">
	Detail brushes
</h2>
<p>
	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.
</p>
<p>
	This means that any object that could only been seen from close by
	should be made from detail brushes.
</p>
<p>
	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.
<p>

<h2 id="materials">
	Textures and Materials
</h2>
<p>
	The engine can use tga, jpg and tng images as textures and uses a simple
	script based materials system similar to Quake 3 Arena shader files.
	Materials make it possible use special textures like player and engine color,
	or to apply certain effects to a texture.
</p><p>
	The file <i>materials/shaderlist.txt</i> contains a list of shader files
	that can be used by the engine. Each shader file can contain several materials.
</p><p>
	The default shaderlist.txt looks like this:
</p>
<pre>
common
colors
glass
</pre>
<p>
	On startup, the engine will read materials from the files <i>materials/common.shader</i>
	and <i>materials/colors.shader</i>. 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.
</p><p>
	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. 
</p><p>
	The materials in the <i>colors/</i> directory can be used to
	draw brush faces with a specified color. The actual RGB color is defined
	by the material script. Examples are <i>red</i>, <i>green</i> and <i>blue</i>.
</p><p>
	The default set of colors is rather limited, more colors can be added by 
	using the <i>common/</i> family of materials. The actual in-game
	color information for these faces will be provided by the engine.
</p><p>
	The <i>common/entity</i> 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 <i>common/entity_second</i> represents the secondary
	color of an entity. <i>common/entity_third</i> will be a mix of the primary and secondary color.
	Each of these materials also has a <i>_dark</i> variant.
</p><p>
	There are two special material that will cause the brush faces to be ignored
	by the engine: as explained above, the <i>common/caulk</i> material can be used
	on hidden faces. The <i>common/clip</i>	material is reserved for future use
	brush faces using this texture will be ignored as well.
</p>
<p>
	For .ase models, the material name inside the .ase file is interpreted as an osirion material.
	If you'd use a material called  <i>common/entity</i>, those model faces will rendered using
	the object's primary in-game color, regardless of the actual material settings in the .ase file.
</p>
	
<h2 id="shader_files">
	Shader files
</h2>
<p>
	TODO: write a section on shader files.
</p>
<pre>
// material name
textures/common/clip
{
    // image used by the map editor
    qer_editorimage textures/common/clip.tga
    // image transparency in the map editor
    qer_trans 0.20
    // polygons using this material are ignored
    ignore
}
</pre>
<pre>
// material name
textures/common/entity_dark_bright
{
    // image used by the map editor
    qer_editorimage textures/common/entity_dark.tga
    // use entity color
    entity
    // material color
    color 0.5 0.5 0.5
    // polygons using this material are rendered fullbright
    bright
}
</pre>
<pre>
// material name
textures/ship/stripes
{
    // use entity color
    entity
    // use a texture, texture name and material name don't have to be the same
    texture textures/ship/stripes
}
</pre>

<h2 id="lights">
	Lights
</h2>	
<p>
	Unlike quake, <i>light</i> 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.
<p>
	The <i>flare</i> value indicates what texture will be used to draw the light.
	The flare value is translated to a texture name, <i>bitmaps/fx/flare??</i>. 
	The default flare texture is <i>flare00</i>.
<p>
	The <i>light</i> value is used to determine the size of the flare. The engine
	default is 100, resulting in rather large flares.
<p>
	The default <i>_color</i> is white, but the color can be set through radiant's
	color menu (K key). If the <i>entity</i> 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. 
<p>
	The <i>strobe</i> 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.
<p>
	The <i>frequency</i> value changes the number of flashes per second.
<p>
	The <i>offset</i> value changes the moment the light will be on. Offset is
	measured in seconds.
<p>
	The <i>time</i> value sets the fraction of time the light will be on. 
	The default is 0.5.
<p>
	Lights will only be rendered if the model is within detail range.
<p>
	I also came across this usefull information: <a href="http://en.wikipedia.org/wiki/Starboard">http://en.wikipedia.org/wiki/Starboard</a><br>

	In short, the green light should be on the right side, the red light on the left side.

<h2 id="flares">
	Flares
</h2>
<p>
	The default light entity creates omnidirectional lights. To create
	a directional flare, use the <i>fx_flare</i> entity. Values for a 
	<i>fx_flare</i> 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.
</p><p>
	Setting the <i>entity</i> option (spawnflag 2) will assign the entities
	primary colour as flare colour.
</p><p>
	Use the <i>engine</i> option (spawnflag 4) to create a flare that
	lights up depending on engine power.
</p><p>
	The direction of the flare can be set with the <i>direction</i>,
	<i>pitch</i> and <i>roll</i> keys. <i>angle</i> is an alias for
	<i>direction</i>.
</p><p>
	Flares will only be rendered if the entity is within detail range.
</p>

<h2 id="particles">
	Particles
</h2>
<p>
	Add a <i>fx_particles</i> 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 <i>particles.ini</i> before it can be used.
</p><p>
	The <i>script</i> value must be set to the label of the particles script.
</p><p>
	Setting the <i>entity</i> option (spawnflag 2) will assign the entities
	primary colour as particle system colour.
</p><p>
	Use the <i>engine</i> option (spawnflag 4) will assign the models engine colour
	as particle system colour.
</p><p>
	The direction of the particle system can be set with the <i>direction</i>,
	<i>pitch</i> and <i>roll</i> keys. <i>angle</i> is an alias for
	<i>direction</i>.
</p><p>
	Particles will only be rendered if the entity is within detail range.
</p>
<h2 id="groups">
	Function groups
</h2>
<p>
	Brushes can be grouped together into funcion groups. These groups can be used
	to create moving parts in a model.
</p>
<p>
	<i>func_door</i> will be used to create animated doors (not implemented)
</p>
<p>
	<i>func_group</i> an editor utility to group brushes together.
</p>
<p>
	<i>func_rotate</i> 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 <i>direction</i>,	<i>pitch</i> and <i>roll</i> keys. <i>angle</i> is an alias for <i>direction</i>.
</p>
<h2 id="submodels">
	Submodels
</h2>
<p>
	<i>misc_model</i> can be used to add a submodel.
</p>
<h2 id="other_entities">
	Other entities
</h2>
<p>
	<i>location_cockpit</i>, <i>location_dock</i>, <i>location_turret</i> and <i>location_cannon</i> are reserved but have not yet been implemented.
</p><p>
	<i>location_cockpit</i> will be used to indicate where the cockpit of a vessel is located
	and will be used to place the camera in cockpit mode.
</p><p>
	<i>location_dock</i> will be used to indicate the location of docking ports.
</p><p>
	<i>location_cannon</i> will create an attachment point for a cannon. Cannons are forward
	shooting guns.
</p><p>
	<i>location_turret</i> will create an attachment point for turrets. Turrets point upwards or downwards.
</p>
<h2 class="navigate">
		<a href="index.html">back</a>
</h2>
</body>
</html>