more documentation, world.html

5 files changed, 205 insertions, 194 deletions

diff --git a/doc/MODELS b/doc/MODELS
deleted file mode 100644
index 4ecd03a..0000000
--- a/doc/MODELS
+++ /dev/null
@@ -1,180 +0,0 @@
- 
-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
-	with a 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 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.
-
-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/model/mapfile.cc
-
-Surface flags
-
-	The only supported surface flag is light. This will render
-	the brush face fullbright. The light flag does not work
-	in conjunction with the common/entity shader.
-	
-Lights
-
-	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 maps to bitmaps/fx/flare??.tga. The default flare is 0.
-
-	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 the time the light will be on. 
-	The default is 0.5.
-
-	Lights will only be rendered if the model is close enough.
-
-	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.
-
-Flares
-
-	The default light entity creates omnidirectional lights. To create
-	a directional flare, use the target_flare entity. Values for a 
-	target_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.
-
-	target_flares can only be rotated in the XY-plane.
-
-Engines
-
-	Add a target_engine entity to add an engine exhaust to a ship model.
-	An engine exhaust always points to the rear (negative X-axis).
-
-	An engine is rendered as a pulsating light flare. The size of the flare
-	can be set through the radius value. The default engine radius is 100.
-
-	Engines	will only be rendered if the model is close enough.
-
-Other entities
-
-	target_cockpit, target_turret and target_cannon are not yet implemented.
-
diff --git a/doc/index.html b/doc/index.html
index 301a9aa..2aeb747 100644
--- a/doc/index.html
+++ b/doc/index.html
@@ -51,7 +51,7 @@
 		<li><a href="manual.html">User manual</a>
 	</ul>
 	<ul>
-		<li>Editing the world
+		<li><a href="world.html">Editing the world</a>
 		<li><a href="models.html">Creating models</a>
 	</ul>
 	<ul>
diff --git a/doc/manual.html b/doc/manual.html
index c1f11b4..494b29f 100644
--- a/doc/manual.html
+++ b/doc/manual.html
@@ -108,22 +108,22 @@ Console functions
 <p>
 	The following commands are always available on the console:
 <table>
-	<tr><td>connect		</td><td>connect the client to the game module</td></tr>
-	<tr><td>disconnect	</td><td>disconnect the client from the game module</td></tr>
-	<tr><td>list_ent	</td><td>list registered entities</td></tr>
-	<tr><td>list_func	</td><td>list registered functions</td></tr>
-	<tr><td>list_model	</td><td>list registered models</td></tr>
-	<tr><td>list_var	</td><td>list registered variables</td></tr>
-	<tr><td>quit		</td><td>exit the application</td></tr>
-	<tr><td>r_restart	</td><td>restart the video subsystem</td></tr>
+	<tr><td class="wide">connect</td><td>connect the client to the game module</td></tr>
+	<tr><td class="wide">disconnect</td><td>disconnect the client from the game module</td></tr>
+	<tr><td class="wide">list_ent</td><td>list registered entities</td></tr>
+	<tr><td class="wide">list_func</td><td>list registered functions</td></tr>
+	<tr><td class="wide">list_model</td><td>list registered models</td></tr>
+	<tr><td class="wide">list_var</td><td>list registered variables</td></tr>
+	<tr><td class="wide">quit</td><td>exit the application</td></tr>
+	<tr><td class="wide">r_restart	</td><td>restart the video subsystem</td></tr>
 </table>
 <p>
 	The following commands are available when you are connected to a game:
 <table>
-	<tr><td>join		</td><td>join the game</td></tr>
-	<tr><td>spectate	</td><td>spectate</td></tr>
-	<tr><td>buy		</td><td>purchase a new ship</td></tr>
-	<tr><td>who		</td><td>list connected players</td></tr>
+	<tr><td class="wide">join</td><td>join the game</td></tr>
+	<tr><td class="wide">spectate</td><td>spectate</td></tr>
+	<tr><td class="wide">buy</td><td>purchase a new ship</td></tr>
+	<tr><td class="wide">who</td><td>list connected players</td></tr>
 </table>
 <p>
 	To change the video resolution, set the r_width and 
@@ -225,7 +225,7 @@ osiriond +set sv_framerate 30
 <p>
 	On windows32, the game uses the <i>home</i> subdirectory as your personal
 	directory. For example, the client.ini can be found as <i>home\base\client.ini</i>.
-<html>
+<p>
 	There is also a problem that prevents the game from creating directories.
 	If you need any subdirectories in your personal folder, like <i>screenshots</i>,
 	you will have to create it manually.
diff --git a/doc/style.css b/doc/style.css
index 4508a6e..614f437 100644
--- a/doc/style.css
+++ b/doc/style.css
@@ -47,12 +47,21 @@ p, ul {
 
 table {
  margin-left: 96px;
+ margin-right: 64px;
 }
 
 td {
  padding-right: 16px;
+ vertical-align: top;
+}
+
+td.wide {
+ width: 96px;
 }
 
+td.narrow {
+ width: 64px;
+}
 pre {
  font-family: "Courier New", "Courier", "fixed";
  font-size: 14px;
diff --git a/doc/world.html b/doc/world.html
new file mode 100644
index 0000000..70c8fbe
--- /dev/null
+++ b/doc/world.html
@@ -0,0 +1,182 @@
+<!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 - Editing the world</TITLE>
+</head>
+<body>
+<H1>
+	The Osirion Project - Editing the world
+</H1>
+<p>
+	One of the goals of the project is to create a game world that is
+	easy to adapt and extend. At the moment of writing, the game reads the 
+	world description from <i>ini/world.ini</i> and a list of buyable ships 
+	from <i>ini/ships.ini</i>. These ini-files are plain text files that can be
+	edited with any text editor.
+<p>
+	The world description files are server-side. This means that editing your local
+	copies will not affect the world when you connect to a remote server. Someone
+	connecting to your server will also receive your modified world.
+<p>
+	I recommend you do not edit the original game data, but to make a copy
+	into your personal osirion directory. The files found in this directory will
+	get precedence over the original game data. Your modified files will be used
+	and the original files can still be updated when a new version is available.
+<p>
+	On Linux your personal osirion directory is <i>~/.osirion</i>. On windows, your
+	personal osirion directory is the <i>home</i> subdirectory of the main distribution.
+
+<h2>
+	File structure
+</h2>
+<p>
+	A world description files uses the windows ini-file syntax. Every section starts
+	with a section name enclosed in square brackets. For example, a section called
+	<i>planet</i> would look like:
+<pre>
+[planet]
+</pre>
+<p>
+	Every section contains a list of <i>value=key</i> pairs to describe the properties
+	for the current section. A planet would probably have a radius and a texture and the
+	planet section could look like:
+<pre>
+[planet]
+radius=32
+texture=planets/iceworld
+</pre>
+<p>
+	Lines starting with a semicolon are considered comments and are ignored:
+<pre>
+; The iceworld, a very dark and cold place
+</pre>
+<h2>
+	world.ini
+</h2>
+<p>
+	The <i>world.ini</i> file describes the objects in the game world and their basic properties. 
+	In the context of the engine, an object is called an <i>entity</i>.
+<h3>
+	[entity]
+</h3>
+<p>
+	Entities come in two flavours: basic geometrical shapes and entities with models. Both have a similar
+	definition and set of properties. A simple entity is considered decoration by the engine and won't change
+	direction or location.
+<p>
+	Every in-game entity should have a <i>label</i> key. If the entity in question is going to be used as a base,
+	or any object the could be referenced in possible scripting, it should have a unique label. The label
+	should be lowercase and not contain spaces. A player-friendly name can be provided through the <i>name</i> key.
+<table>
+	<tr>
+		<td class="wide"><i>label =</i></td>
+		<td class="narrow"><strong>[string]</strong></td>
+		<td>the in-game label of the entity</td>
+	</tr>
+	<tr>
+		<td class="wide"><i>name =</i></td>
+		<td class="narrow"><strong>[string]</strong></td>
+		<td>the in-game name of the entity</td>
+	</tr>
+</table>
+<p>
+	Set the <i>shape</i> key to define a basic geometrical shape:
+<table>
+	<tr>
+		<td class="wide"><i>shape =</i></td>
+		<td class="narrow"><strong>axis</strong></td>
+		<td>a 3d-axis with X, Y and Z lines.
+	</tr>
+	<tr>
+		<td class="wide"></td>
+		<td class="narrow"><strong>cube</strong></td>
+		<td>a cube</td>
+	</tr>
+	<tr>
+		<td class="wide"></td>
+		<td class="narrow"><strong>diamond</strong></td>
+		<td>a regular octahedron with an axis</td>
+	</tr>
+	<tr>
+		<td class="wide"></td>
+		<td class="narrow"><strong>sphere</strong></td>
+		<td>a polyhedron approximation of a sphere</td>
+	</tr>
+</table>
+<p>
+	The size of the entity can be set with the <i>radius</i> key:
+<table>
+	<tr>
+		<td class="wide"><i>radius =</i></td>
+		<td class="narrow"><strong>[float]<strong></td>
+		<td>the radius of the entity in game units</td>
+	</tr>
+</table>
+<p>
+	An entity with a model can be created by setting the <i>model</i> key. The radius of a model is automaticly
+	calculated:
+<table>
+	<tr>
+		<td class="wide"><i>model =</i></td>
+		<td class="narrow"><strong>[string]</strong></td>
+		<td>filename of the model in the <i>maps/</i> directory, without extension.</td>
+	</tr>
+</table>
+
+<p>
+	The <i>color</i> key sets the colour of the entity.This colour will be used to draw the entity in case of 
+	a geometrical shape, or to draw model faces that have the <i>common/entity</i> texture. The default entity colour is white.
+<table>
+	<tr>
+		<td class="wide"><i>color =</i></td>
+		<td><strong>[float] [float] [float]</strong></td>
+		<td>entity colour with RGB values in the 0.0 - 1.0 or 0 - 255 range</td>
+	</tr>
+</table>
+<p>
+	The <i>location</i> sets the in-game position:
+<table>
+	<tr>
+		<td class="wide"><i>location =</i></td>
+		<td><strong>[float] [float] [float]</strong></td>
+		<td>x, y, z values of the entity location, z is up</td>
+	</tr>
+</table>
+<p>
+	Orientation can be set thought the <i>direction</i>, <i>pitch</i>, and <i>roll</i> keys:
+<table>
+	<tr>
+		<td class="wide"><i>direction =</i></td>
+		<td class="narrow"><strong>[float]</strong></td>
+		<td>direction angle the entity is pointing to. 0 degrees is north, 90 degrees is west, default is 0
+	</tr>
+	<tr>
+		<td class="wide"><i>pitch =</i></td>
+		<td class="narrow"><strong>[float]</strong></td>
+		<td>pitch angle, default is 0<td>
+	</tr>
+	<tr>
+		<td class="wide"><i>roll =</i></td>
+		<td class="narrow"><strong>[float]</strong></td>
+		<td>roll angle, default is 0<td>
+	</tr>
+</table>
+<h3>
+	[planet]
+</h3>
+<p>
+	A planet.
+<h3>
+	[star]
+</h3>
+<p>
+	A star.
+<h2>
+	ships.ini
+</h2>
+<p>
+	Ships that can be purchased go here.
+</body>
+</html>