documentation updates

1 files changed, 75 insertions, 3 deletions

diff --git a/doc/world.html b/doc/world.html
index 4ae6bba..a8d9790 100644
--- a/doc/world.html
+++ b/doc/world.html
@@ -32,7 +32,7 @@
 	File structure
 </h2>
 <p>
-	A world description files uses the windows ini-file syntax. These files contain one or more sections.
+	World description files use the windows ini-file syntax. These files contain one or more sections.
 	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.
@@ -50,9 +50,73 @@ texture=planets/iceworld
 <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>.
+	The <i>world.ini</i> file 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.
+<h3>
+	[world]
+</h3>
+
+<table>
+	<tr>
+		<td class="wide"><i>zone =</i></td>
+		<td class="narrow"><strong>[string]</strong></td>
+		<td>the in-game label of a zone</td>
+	</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.
+
+<pre>
+; a world.ini example with two zones
+[world]
+zone=solarsystem
+zone=remotesector
+</pre>
+<h2>
+	zones/<i>label</i>.ini
+</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>
+	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>.
+<h3>
+	[zone]
+</h3>
+
+<p>
+	Every zone description file has a <i>zone</i> section describing a few of its basic properties:
+<table>
+	<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>
+	<tr>
+		<td class="wide"><i>sky =</i></td>
+		<td class="narrow"><strong>[string]</strong></td>
+		<td>name of the sky texture in <i>textures/env</i> directory</td>
+	</tr>
+	<tr>
+		<td class="wide"><i>default =</i></td>
+		<td class="narrow"><strong>[bool]</strong></td>
+		<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
+</pre>
 <h3>
 	[entity]
 </h3>
@@ -199,6 +263,14 @@ color=222 192 145
 <p>
 	A planet is spherical entity with a texture. and a default radius of 32. The planet globe will
 	be rendered with lighting enabled.
+<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>
+</table>
+
 <pre>
 ; The iceworld, a very dark and cold place
 [planet]