documentation updates

1 files changed, 137 insertions, 62 deletions

diff --git a/doc/world.html b/doc/world.html
index 8e91ce5..82908dd 100644
--- a/doc/world.html
+++ b/doc/world.html
@@ -15,19 +15,20 @@
 	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>
+</p><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
+</p><p>
+	I recommend you do not edit the original game data, copy the files you want
+	to edit toyour 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.
-
+</p><p>
+	On Linx and other Unix-systems your personal osirion is a hidden directory called
+	<i>.osirion</i> in your home directory.	On windows, your personal osirion directory
+	is <i>My Documents\My Games\Osirion</i>.
+</p>
 <h2>
 	File structure
 </h2>
@@ -36,29 +37,32 @@
 	Every section starts with a section name enclosed in square brackets and contains a list of 
 	<i>value=key</i> pairs to describe the properties for the current section. 
 	Lines starting with a semicolon are considered comments and are ignored.
-<p>	
-	For example, a section <i>planet</i> describing an iceworld:
+</p><p>	
+	For example, a section <i>planet</i> describing a planet called Seymour:
+</p>
+
 <pre>
-; The iceworld, a very dark and cold place
 [planet]
-label=iceworld
-name=The World of Ice
-radius=32
-texture=planets/iceworld
+label=seymour
+name=planet Seymour
+location=-128 1024 -32
+color=1 .9 .5
+texture=planets/seymour
+radius=68
 </pre>
 
 <h2>
-	world.ini
+	World
 </h2>
 
 <p>
-	The <i>world.ini</i> file contains a list of zone labels. A zone is a seperate compartment in the gameworld,
+	The file <i>world.ini</i> contains a list of zone labels. A zone is a seperate compartment in the gameworld,
 	like a solar system or a remote sector in space. It contains a single <i>world</i> section containting multiple
 	<i>zone</i> keys.
+</p>
 <h3>
-	[world]
+    [world]
 </h3>
-
 <table>
 	<tr>
 		<td class="wide"><i>zone =</i></td>
@@ -67,31 +71,32 @@ texture=planets/iceworld
 	</tr>
 </table>
 <p>
-	<i>Note:</i> a label can only contain lowercase letters, numbers and underscores. Any other character is deleted.
-	This applies to any in-game label in any .ini-file.
-
+	<i>Note:</i> a label can only contain letters, numbers and underscores. Any other character is deleted. This applies to any label in any .ini-file.
+</p>
 <pre>
-; a world.ini example with two zones
+; a world.ini with two zones
 [world]
-zone=solarsystem
-zone=remotesector
+zone=ghant
+zone=brogha
 </pre>
+
 <h2>
-	zones/<i>label</i>.ini
+	Zones
 </h2>
 <p>
 	Each zone has its own zone description file. The actual name of the file depends on the zone label. 
-	If your <i>world.ini</i> contains the line <i>zone=remotesector</i>, the content of the zone with 
-	the label <i>remotesector</i> would be described in the file <i>ini/zones/remotesector.ini</i>.
-<p>
+	If your <i>world.ini</i> contains the line <i>zone=ghant</i>, the content of the zone with 
+	the label <i>ghant</i> would be described in the file <i>zones/ghant.ini</i>.
+</p><p>
 	The .ini-file containts a list of objects populating that zone, and the basic properties of those
 	objects. In the context of the engine, such an object is called an <i>entity</i>.
+</p>
 <h3>
-	[zone]
+    [zone]
 </h3>
-
 <p>
 	Every zone description file has a <i>zone</i> section describing a few of its basic properties:
+</p>
 <table>
 	<tr>
 		<td class="wide"><i>name =</i></td>
@@ -109,25 +114,24 @@ zone=remotesector
 		<td>mark this zone as the default zone for the game, only one zone can have this key set to yes, can be omitted elsewhere</td>
 	</tr>
 </table>
+
 <pre>
-; remotesector.ini
-; zone description file for the Remote Sector
-[sector]
-name=Remote Sector
-sky=sky_texture
-default=no
+; ghant.ini
+; zone description file for the Ghant system
+[zone]
+name=Ghant system
+sky=sky12
+default=yes
 </pre>
+
 <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.
+	You can add several <i>entity</i> sections to define the objects occupying your zones. Entities come in two flavours: basic geometrical shapes and entities with models. Both have a similar	definition and set of properties. A simple <i>entity</i> is considered decoration by the engine and won't change direction or location.
+</p><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.
+</p>
 <table>
 	<tr>
 		<td class="wide"><i>label =</i></td>
@@ -140,8 +144,10 @@ default=no
 		<td>the in-game name of the entity</td>
 	</tr>
 </table>
+
 <p>
 	Set the <i>shape</i> key to define a basic geometrical shape:
+</p>
 <table>
 	<tr>
 		<td class="wide"><i>shape =</i></td>
@@ -166,6 +172,7 @@ default=no
 </table>
 <p>
 	The size of the entity can be set with the <i>radius</i> key:
+</p>
 <table>
 	<tr>
 		<td class="wide"><i>radius =</i></td>
@@ -179,8 +186,8 @@ default=no
 <p>
 
 <p>
-	An entity with a model can be created by setting the <i>model</i> key. The radius of a model is automaticly
-	calculated:
+	An entity with a model can be created by setting the <i>model</i> key. The radius of a model is automaticly	calculated:
+</p>
 <table>
 	<tr>
 		<td class="wide"><i>model =</i></td>
@@ -192,8 +199,8 @@ default=no
 <p>
 	The <i>color</i> key sets the primary color of the entity. This color 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.
-<p>
 	The <i>colorsecond </i> key can be used to set the secondary color of entities with a model.
+</p>
 <table>
 	<tr>
 		<td class="wide"><i>color =</i></td>
@@ -207,6 +214,8 @@ default=no
 </table>
 <p>
 	The <i>location</i> sets the in-game position:
+</p>
+
 <table>
 	<tr>
 		<td class="wide"><i>location =</i></td>
@@ -216,8 +225,9 @@ default=no
 </table>
 <p>
 	1 game unit on the x, y, or z-axis translates to 100m in-game.
-<p>
+</p><p>
 	Orientation can be set thought the <i>direction</i>, <i>pitch</i>, and <i>roll</i> keys:
+</p>
 <table>
 	<tr>
 		<td class="wide"><i>direction =</i></td>
@@ -237,9 +247,9 @@ default=no
 </table>
 <p>
 	An example of an entity with a basic shape:
+</p>
 
 <pre>
-; The Galactic origin
 [entity]
 label=origin
 name=Galactic origin
@@ -252,41 +262,95 @@ color=1 1 0
 
 <p>
 	An example of an entity with a model:
+</p>
 <pre>
-; Alexandria outpost
 [entity]
+label=ikarus
+name=Ikarus satellite
+model=satellites/ikarus
+; blue
+color=100 100 230
+location=64 0 0
+direction=120
+pitch=15
+</pre>
+
+<h3>
+	[station]
+</h3>
+<p>
+    A <i>station</i> section defines an entity that can be visited by a player. This section
+	can contain the same keys as the <i>entity</i> section, but the entity will be marked as 
+	dockable and the player will be able to target it for docking.
+</p>
+<p>
+    The engine will load the stations menu descriptions from the file <i>zones/zonelabel/entitylabel.ini</i>.
+	For example, if your zone has the label <i>ghant</i> and your entity has the label <i>alexandria</i> then
+	the engine will try to read <i>zones/ghant/alexandria.ini</i>. Read the section on entity menus for more
+	information.
+</p>
+
+<pre>
+[station]
 label=alexandria
 name=Alexandria outpost
 model=stations/alexandria
-location=-116 -68 16
-direction=315
-; light brown
+location=-192 -704 32
+; brown
 color=222 192 145
+direction=45
 </pre>
 
 <h3>
+	[jumpgate]
+</h3>
+<p>
+		TODO
+</p>
+<h3>
+	[jumppoint]
+</h3>
+<p>
+		TODO
+</p>
+<h3>
 	[navpoint]
 </h3>
 <p>
-	Space is a big place. Navigation points can help players to find their way around.
+	Space is huge and barren wastland.  Navigation points are an easy way to provide players
+	with landmarks. The default navigation point is a diamond-shaped entity.
+</p>
 <pre>
 [navpoint]
-label=navpoint_north
-name=Navigation point North
-location=1024 0 0
+label=navpoint_east
+name=Navigation point East
+location=716 -1008 20
 </pre>
+
 <h3>
 	[planet]
 </h3>
 <p>
 	A planet is spherical entity with a texture. and a default radius of 64. The planet globe will
-	be rendered with lighting enabled.
+	be rendered with lighting enabled. A planet can be marked as dockable. In this case it can be
+    visited by a player and menu descriptions will be loaded.
+</p>
 <table>
 	<tr>
 		<td class="wide"><i>texture =</i></td>
 		<td class="narrow"><strong>[string]</strong></td>
 		<td>name of the planet texture in <i>textures</i> directory</td>
 	</tr>
+	<tr>
+		<td class="wide"><i>rotationspeed =</i></td>
+		<td class="narrow"><strong>[float]</strong></td>
+		<td>rotation speed in degrees per second</td>
+	</tr>
+	<tr>
+		<td class="wide"><i>dock =</i></td>
+		<td class="narrow"><strong>[bool]</strong></td>
+		<td>set to true to create a planet the players can visit</td>
+	</tr>
 </table>
 
 <pre>
@@ -295,6 +359,7 @@ location=1024 0 0
 label=iceworld
 name=The World of Ice
 texture=planets/iceworld
+rotationspeed=1
 ; a grey-blue colour
 color =0.5 0.5 0.8
 </pre>
@@ -307,25 +372,35 @@ color =0.5 0.5 0.8
 	will be rendered fullbright and serve as the main source of light for the current system. 
 	At the moment only one system light source is supported. If you define multiple stars, 
 	the last one will serve as light source. Stars can have a texture.
+</p>
+
 <pre>
+; a yellow star
 [star]
 label=whitedwarf
 name=White Dwarf
-; light yellow
 color=1.0 1.0 0.9
+radius=96
 </pre>
 
 <h2>
-	ships.ini
+	Ships
 </h2>
 <p>
-	Definition of the shopping list.
-
+	TODO Definition of the shopping list.
+</p>
+<h2>
+    Entity menus
+</h2>
+<p>
+	TODO
+</p>
 <h2>
 	Textures
 </h2>
 <p>
 	The engine supports textures in the TGA, PNG and JPG file formats. The filename extension
 	should be lowercase and the texture should be in 24bit RGB or 32bit RGBA format.
+</p>
 </body>
 </html>