1 files changed, 182 insertions, 0 deletions
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>