Documentation update

2 files changed, 148 insertions, 21 deletions

diff --git a/MODELS b/MODELS
new file mode 100644
index 0000000..00d5a31
--- /dev/null
+++ b/MODELS
@@ -0,0 +1,125 @@
+ 
+The Osirion Project - MODELS
+
+Creating 3D models for The Osirion Project
+
+Introduction
+
+	The engine supports loading of Quake 2 .map files with custom osirion
+	entities. While it might look like a weird choice for a file format
+	it has been a well-considered pragmatic choice. 
+
+	First of all, creating commercial grade graphics has never been 
+	my goal. Polished high-quality models demand a lot of time, 
+	skill and effort.
+
+	The same goes for 3D modelling packages like Blender or 3D Studio Max.
+	They are capable of producing awesome results, but the learning curve
+	is quite steep and the number of availble 3D artists is rather limited.
+
+	GtkRadiant on the other hand has been my personal tool for some time
+	now. For an experienced mapper, creating a LEGO-style model is only
+	a matter of hours and without the usual technical difficulties of 
+	creating a map for shoot'em'up.
+
+	Creating game content is usually a chicken-and-egg in a small game
+	project. I hope to solve it by choosing a widely available and
+	easy to master format.
+
+	The rest of this document contains information specific to creating
+	models for the Osirion Project. Even if you can handle GtkRadiant,
+	it is still worth a read.
+
+Creating models with GtkRadiant
+
+	All the models for the game were created with GtkRadiant 1.5.0,
+	in theory any editor capable of exporting Quake 2 .map files could
+	be used. Support for files for GtkRadiant 1.5.0 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.
+
+	If you are using a linux-based operating system, you can also use 
+	the GtkRadiant distribution from http://ingar.soliter.org.
+	Note that it does not include the Osirion support files by default.
+
+	This document will not explain how to use the editor. Consult google
+	for numerous tutorials on this subject. Any basic brush-creating 
+	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.
+
+Brushes and sizes
+
+	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.
+
+	When the model is loaded, the bounding box is calculated. The center 
+	of the model will be placed at the center of the bounding box.
+
+	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 map units correspond to 1 game unit.
+
+	The front of a model points along the positive X-axis, the positive
+	Z-axis is up, the positive Y-axis is left.
+
+Caulk
+
+	Any brush face that has the common/caulk texture will be ignored on load.
+
+Clip
+	Any brush face that has the common/clip texture will be ignored on load.
+	Clip is reserved for future use.
+
+Detail brushes
+
+	As with other engines, Osirion supports the use of detail brushes, but
+	witha  twist: detail brushes will only be rendered if the model 
+	is close enough to the camera. When it is further away, only structural 
+	brushes will be rendered.
+
+	This means that any objects 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.
+
+Textures
+	
+	The engine supports no textures. Any real texturing information 
+	is ignored.
+
+	The textures in the directory /textures/colors can be used by 
+	the editor. The engine translates these textures into RGB colors 
+	when the model is loaded. Unknown textures will be colored hot pink.
+
+	You can also use two special textures from the /textures/common
+	directory: as explained above, faces with the common/caulk texture
+	will be ignored on load. The use of common/clip is reserved for
+	future use. At the moment they will be ignored as well.
+
+	At the time of writing, texture names are hardcoded in src/core/model.cc
+	
+Entities
+
+	Add an info_engine entity to add an engine exhaust to a ship model.
+	An engine always points to the rear (negative Z-axis). Engines
+	will only be rendered if the model is close enough.
+
+Lights
+
+	Support for light entities is very basic, the end result is far 
+	from pleasing for the eye. They do have their use, since lights	
+	are only rendered if the model is close enough. The engine does support
+	coloured lights (with the 'K' menu in GtkRadiant).
+
+	The strobe option (spawnflag 1) will create a flashing light.
diff --git a/README b/README
index 6a88cca..b16d74b 100644
--- a/README
+++ b/README
@@ -97,6 +97,9 @@ Organization of the distribution
 	C++ source code
 
 	/src
+		README			this file
+		INSTALL			documentation in installation
+		MODELS			documentation on creating models
 
 		/math			mathematical classes
 		/sys			low-level system functions
@@ -117,6 +120,7 @@ Organization of the distribution
 				/satellites	sattelites
 				/ships		spaceships
 				/stations	space stations
+			scripts		gtkradiant shader files
 			/textures	textures
 		/gtkradiant		gtkradiant support files
 	
@@ -136,24 +140,9 @@ Editing game data
 	there will get precedence over the corresponding file in 
 	the game data directory.
 
-Adding models
-
 	The models are basic Quake2 style .map files with custom entities
-	and can	be created with a program like gtkradiant. No map compiler is 
-	necessary, the engine reads the .map files directly. Refer to the file 
-	INSTALL on how to install the support files for gtkradiant 1.5.0.
-
-	The textures in the textures/colors/ directory are mapped to RGB colors
-	when the models are loaded, any real texturing information is ignored.
-	Unknown textures will be colored hot pink in-game.
-
-	Two special textures are supported: any brush faces textures with
-	common/caulk will be ignored by the engine, similar to the caulk
-	feature in quake-like engines. Brush faces with the common/entity
-	texture will get the current game entity color. This makes it possible
-	to use the current player color on ship models.
-
-	Add an info_engine entity to add an engine exhaust to a ship model.
+	and can	be created with a program like gtkradiant. Refer to the 
+	file MODELS for more information on creating 3D models.
 
 Notes
 
@@ -183,8 +172,7 @@ Acknowledgements
 
 	This project could not have been possible without the work of others:
 
-	Id Software, for releasing the quake source code, which obviously 
-	acted as a example.
+	Id Software, for releasing the quake source code
 
 	Id Software and the GtkRadiant project contributers
 
@@ -200,8 +188,22 @@ Acknowledgements
 	
 License
 
-	The program is distributed under the terms and conditions of the 
-	GNU General Public License version 2.
+	The Osirion Project is distributed under 
+	the terms and conditions of 
+	the GNU General Public License version 2.
+
+	This includes the source code, project documentation and game data.
 
 	Copyright 2007-2008
 	Ingar=KCT= <ingar@telenet.be>
+
+	Contact me if you want to use (portions of) this project
+	under a non-compatible, but otherwise free, licence.
+	
+Trademarks
+	 
+	QUAKE and ID are registered trademarks of Id Software, Inc.
+	LEGO is a reigstered trademark of the LEGO Group.
+	
+	The Osirion Project is an independent not-for-profit project 
+	and has no affiliation with these corporations.