Restructured modeling documentation.

author: Stijn Buys <ingar@osirion.org> 2010-11-30 14:22:34 +0000
committer: Stijn Buys <ingar@osirion.org> 2010-11-30 14:22:34 +0000
commit: a7a274bfda04a87009788b705a2d90e01b1041c7 (patch)
tree: b323ace6a9d74c7c3f95436ac87d5579189e5779 /doc/models.html
parent: 9a80afe0994b9b565b6eb28dac8929bdd3b15ba8 (diff)
1 files changed, 188 insertions, 157 deletions
diff --git a/doc/models.html b/doc/models.html
index 5a0e270..e0667ba 100644
--- a/doc/models.html
+++ b/doc/models.html
@@ -3,40 +3,35 @@
 <head>
 	<meta HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=UTF-8">
 	<link rel="stylesheet" type="text/css" href="main.css">
-	<TITLE>Project::OSiRiON - Creating models</TITLE>
+	<TITLE>Project::OSiRiON - Creating 3D models</TITLE>
 </head>
 
 <body>
 <div class="banner">
 	<img src="images/banner.png" ALT="Project::OSiRiON">
 	<br>
-	Creating models
+	Creating 3D models
 </div>
 
 <div class="text">
 <p>
-	The engine supports two kind of models: The first one are
-	Quake 3 style .map files with custom entities, the second
-	one are .ase models. Textures are supported, but no advanced 
-	features like normal maps.
-</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 model tags like lights, 
-	particle effects 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
-	Radiant and contains mostly information specific to creating
-	models for Project::OSiRiON. Even if you can handle Radiant,
-	it is still worth a read.
+	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 (<span style="fixed">.ase</span> files) and the Quake 3
+	map format (<span style="fixed">.map</span> files).
+</p><p>
+	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.
+</p><p>
+	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 <i>misc_model</i> entity) and add Project::OSiRiON-specific
+	entities like lights, engine flares and weapon locations.
+</p><p>
+	The engine uses submodel instancing making it possible to re-used
+	submodels with a minimal performace impact.
 </p>
 </div>
 
@@ -47,22 +42,152 @@
 <div class="text">
 <p>
 <ul>
-	<li><a href="#gtkradiant">Creating models with Radiant</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="#materials">Textures and 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>
+
+	<li><a href="#gtkradiant">Creating models with Radiant</a>
+	<ul>
+		<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="#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>
+	<li><a href="#commands">Useful commands</a>
 </ul>
 </div>
 
+
+<!-- =============================================================== -->
+<div class="title" id="materials">
+	Textures and Materials
+</div>
+<div class="text">
+<p>
+	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.
+</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 class="code">
+common
+colors
+glass
+kuroto
+</pre>
+<p>
+	On startup, the engine will read materials from the files <span class="fixed">materials/common.shader</span>
+	and <span class="fixed">materials/colors.shader</span>. 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 <span class="fixed">colors/</span> directory can be used to
+	draw brush faces with a specified color. The actual RGB color is defined
+	by the material script. Examples are <span class="fixed">red</span>,
+	<span class="fixed">green</span> and <span class="fixed">blue</span>.
+</p><p>
+	The default set of colors is rather limited, more colors can be added by 
+	using the <span class="fixed">common/</span> family of materials. The actual in-game
+	color information for these faces will be provided by the engine.
+</p><p>
+	The <span class="fixed">common/entity</span> 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 <span class="fixed">common/entity_second</span> represents the secondary
+	color of an entity. <span class="fixed">common/entity_third</span> will be a mix of the primary and secondary color.
+	Each of these materials also has a <span class="fixed">_dark</span> variant.
+</p><p>
+	There are two special material that will cause the brush faces to be ignored
+	by the engine: as explained above, the <span class="fixed">common/caulk</span> material can be used
+	on hidden faces. The <span class="fixed">common/clip</span> 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  <span class="fixed">common/entity</span>, 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 <i>ase material name</i> is used, not the name of the diffuse texture
+	used by that material.
+</p><p>
+	If a model material has no special definition, the engine will try to load the texture with the same name,
+	like the material <span class="fixed">models/cargo/crate/crate</span>.
+</div>
+
+<!-- =============================================================== -->
+<div class="title" id="shader_files">
+	Shader files
+</div>
+<div class="text">
+<p>
+	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.
+</p>
+<p>
+	for example, the definition of the <span class="fixed">textures/common/caulk</a> material:
+</p>
+<pre class=code>
+// material name
+textures/common/caulk
+{
+    // image used by the map editor
+    qer_editorimage textures/common/caulk.tga
+    // polygons using this material are ignored
+    ignore
+}
+</pre>
+<p>
+	This material has the name <span class="fixed">textures/common/caulk</span>, 
+	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 <span class="fixed">common/caulk</span> texture
+	(note that Radiant doesn't show the <span class="fixed">textures/</span> prefix). For .ase files,
+	it means every triangle with a material that is called <span class="fixed">textures/common/caulk</span>.
+</p>
+<p>
+	This material has the <span class="fixed">ignore</span> flag: model geometry with this material will simply
+	be ignored.
+</p>
+<p>
+	A second example is the <span class="fixed">textures/common/entity</span> material:
+</p>
+<pre class=code>
+// material name
+textures/common/entity
+{
+    // image used by the map editor
+    qer_editorimage textures/common/entity.tga
+    // use entity color
+    entity
+}
+</pre>
+<p>
+	This material has the <span class="fixed">entity</span> flag set: it means model geometry with this material
+	will be rendered in entity color. For spaceship this means player color.
+</p>
+<pre class=code>
+// 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
+}
+</pre>
+</div>
+
 <!-- =============================================================== -->
 <div class="title" id="radiant">
 	Creating models with Radiant
@@ -80,7 +205,7 @@
 	<a href="http://ingar.satgnu.net/gtkradiant">http://ingar.satgnu.net/gtkradiant</a>.
 	Note that it does not include the Project::OSiRiON support files by default.
 <p></p>
-	This document will not explain how to use the editor. Consult google
+	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.
 <p></p>
@@ -93,7 +218,7 @@
 </p>
 </div>
 
-<div class="title" id="brushes_and_sizes">
+<div class="subtitle" id="brushes_and_sizes">
 	Brushes and sizes
 </div>
 <div class="text">
@@ -111,10 +236,9 @@
 	might be placed in a system filled with player ships and other objects.
 <p></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.
+	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.
 <p></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 Radiant, the nose of
@@ -123,7 +247,7 @@
 </div>
 
 <!-- =============================================================== -->
-<div class="title" id="caulk">
+<div class="subtitle" id="caulk">
 	Caulk
 </div>
 
@@ -138,7 +262,7 @@
 </div>
 
 <!-- =============================================================== -->
-<div class="title" id="clip">
+<div class="subtitle" id="clip">
 	Clip
 </div>
 <div class="text">
@@ -150,7 +274,7 @@
 </div>
 
 <!-- =============================================================== -->
-<div class="title" id="detail_brushes">
+<div class="subtitle" id="detail_brushes">
 	Detail brushes
 </div>
 <div class="text">
@@ -171,112 +295,7 @@
 </div>
 
 <!-- =============================================================== -->
-<div class="title" id="materials">
-	Textures and Materials
-</div>
-<div class="text">
-<p>
-	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 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 class="code">
-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.
-	Note that it is the actual <i>ase material name</i> that is used, not the name of the diffuse texture
-	used by that material.
-</p>
-</div>
-
-<!-- =============================================================== -->
-<div class="title" id="shader_files">
-	Shader files
-</div>
-<div class="text">
-<p>
-	TODO: write a section on shader files.
-</p>
-<pre class=code>
-// 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 class=code>
-// 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 class=code>
-// 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
-}
-</pre>
-</div>
-
-<!-- =============================================================== -->
-<div class="title" id="lights">
+<div class="subtitle" id="lights">
 	Lights
 </div>
 <div class="text">
@@ -317,7 +336,7 @@ textures/ship/plating_entity
 </div>
 
 <!-- =============================================================== -->
-<div class="title" id="flares">
+<div class="subtitle" id="flares">
 	Flares
 </div>
 <div class="text">
@@ -344,7 +363,7 @@ textures/ship/plating_entity
 </div>
 
 <!-- =============================================================== -->
-<div class="title" id="particles">
+<div class="subtitle" id="particles">
 	Particles
 </div>
 <div class="text">
@@ -370,7 +389,7 @@ textures/ship/plating_entity
 </div>
 
 <!-- =============================================================== -->
-<div class="title" id="groups">
+<div class="subtitle" id="groups">
 	Function groups
 </div>
 <div class="text">
@@ -394,7 +413,7 @@ textures/ship/plating_entity
 </div>
 
 <!-- =============================================================== -->
-<div class="title" id="submodels">
+<div class="subtitle" id="submodels">
 	Submodels
 </div>
 <div class="text">
@@ -404,7 +423,7 @@ textures/ship/plating_entity
 </div>
 
 <!-- =============================================================== -->
-<div class="title" id="other_entities">
+<div class="subtitle" id="other_entities">
 	Other entities
 </div>
 <div class="text">
@@ -435,7 +454,19 @@ textures/ship/plating_entity
 <pre class="code">
 testmodel maps/colonial/alexandria
 </pre>
-
+<p>
+	You can load all models referenced by the game at once by executing the <span class="fixed">r_loadmodels</span> command.
+	This makes it easy to find missing models, missing textures or to spot other related problems. 
+</p>
+<pre class="code">
+r_loadmodels
+</pre>
+<p>
+	Use the <span class="fixed">list_model</span> command to get a list of currently loaded models:
+</p>
+<pre class="code">
+list_model
+</pre>
 </div>
 
 </body>
author	Stijn Buys <ingar@osirion.org>	2010-11-30 14:22:34 +0000
committer	Stijn Buys <ingar@osirion.org>	2010-11-30 14:22:34 +0000
commit	a7a274bfda04a87009788b705a2d90e01b1041c7 (patch)
tree	b323ace6a9d74c7c3f95436ac87d5579189e5779 /doc/models.html
parent	9a80afe0994b9b565b6eb28dac8929bdd3b15ba8 (diff)