From 555bdddeb96ff723db64e662b7a8e40800bf40df Mon Sep 17 00:00:00 2001
From: RandumKiwi <RandumKiwi@users.noreply.github.com>
Date: Wed, 13 Aug 2008 09:54:46 +0000
Subject: [PATCH] [DOCS] More mapping guidance :)

git-svn-id: svn://svn.code.sf.net/p/actiongame/code/trunk/ac@2309 e016b1c5-ed68-44aa-a2f7-31cac88cffde
---
 docs/README.xml       |  13 ++-
 docs/introduction.xml |   2 +-
 docs/mapediting1.xml  |  17 ++--
 docs/mapediting2.xml  |  89 +++++++++++++++-----
 docs/mapediting3.xml  | 186 ++++++++++++++++++++++++++++++++++++++++++
 docs/mapediting4.xml  |  32 ++++++++
 docs/mapediting5.xml  |  12 +++
 7 files changed, 318 insertions(+), 33 deletions(-)
 create mode 100644 docs/mapediting3.xml
 create mode 100644 docs/mapediting4.xml
 create mode 100644 docs/mapediting5.xml

diff --git a/docs/README.xml b/docs/README.xml
index b6f35a9e..a3084384 100644
--- a/docs/README.xml
+++ b/docs/README.xml
@@ -82,13 +82,22 @@
       </li>
     </ul>
 
-    <h2>Modding</h2>
+    <h2>Mapping/Modding</h2>
     <ul>
         <li>
           <a href="mapediting1.xml">Map editing: Interface &amp; controls</a> - An introduction to the interface &amp; controls used in map editing.  
         </li>
         <li>
-          <a href="mapediting2.xml">Map editing: Introduction</a> - Start map editing!
+          <a href="mapediting2.xml">Map editing: Beginners</a> - Start map editing!
+        </li>
+        <li>
+          <a href="mapediting3.xml">Map editing: Entities</a> - Learn how to place lights, spawns, mapmodels, etc.
+        </li>
+        <li>
+          <a href="mapediting4.xml">Map editing: Tips</a> - Some handy tips that aren't mentioned elsewhere.
+        </li>
+        <li>
+          <a href="mapediting5.xml">Map editing: Config files</a> - Learn how to add custom content through the configuration files.
         </li>
         <li>
         <a href="mappers_readme.txt">Mappers readme</a> - Information about creating maps suitable for the 
diff --git a/docs/introduction.xml b/docs/introduction.xml
index ef6f5ba4..23e9f239 100644
--- a/docs/introduction.xml
+++ b/docs/introduction.xml
@@ -251,7 +251,7 @@
 
     <p>
       AssaultCube offers 7 different multi-player game modes, 3 single-player game modes and 1 mode for co-operative map editing.
-      Information about co-operative editing can be found in <a href="mapediting2.xml#co-op">Map editing: Beginners</a>.
+      Information about co-operative editing can be found in <a href="mapediting4.xml#co-op">Map editing: Tips</a>.
     </p>
     <h3>Multi-player modes</h3>
     <p>
diff --git a/docs/mapediting1.xml b/docs/mapediting1.xml
index d1dfe385..0aaacb0e 100644
--- a/docs/mapediting1.xml
+++ b/docs/mapediting1.xml
@@ -27,27 +27,29 @@
           <td>
             <b>Heightfield cubes</b><br />
             <p>
-              These are the light green cubes in the grid.<br /> These cubes indicate heightfields, which will be explained later <a herf="#LINK">here</a>.
+              These are the light green cubes in the grid.<br /> These cubes indicate heightfields, which will be explained 
+              later <a href="mapediting2.xml#heightfield">here</a>.
             </p>                        
           </td>
         </tr>
         <tr>
-          <td><img src="pics/editmode-entity.jpg" alt="Indicates an entity"/></td>
+          <td><img src="pics/editmode-entity.jpg" id="sparkles" alt="Indicates an entity"/></td>
           <td>
             <b>Entity sparkles</b><br />
             <p>
-              These are shown as blue sparkly things. They are known as "entities", which will be explained later <a herf="#LINK">here</a>.
+              These are shown as blue sparkly dots. They are known as "entities", which will be explained later <a href="mapediting3.xml">here</a>.
             </p>                        
           </td>
         </tr>
         <tr>
-          <td><img src="pics/editmode-selector.jpg" alt="Selects cubes"/></td>
+          <td><img src="pics/editmode-selector.jpg"  id="selector" alt="Selects cubes"/></td>
           <td>
             <b>Cube selector</b><br />
             <p>
               This appears as a small white box with a red dot in the corner. It will appear in the middle of the screen and you can use it to select
-              geometery, a bit like a crosshair. <br />The red dot indicates which corner of a cube you are manipulating, if you are using heightfields, 
-              or where your entity will be placed if you are creating an entity, but you don't need to worry about knowing how to use that red dot just yet.
+              geometery, a bit like a crosshair. <br />The red dot indicates which corner of a cube you are manipulating, if you are using 
+              <a href="mapediting2.xml#heightfield">heightfields</a>, or where your <a href="mapediting3.xml">entity</a> 
+              will be placed if you are creating an entity.
             </p>                        
           </td>
         </tr>
@@ -56,8 +58,7 @@
           <td>
             <b>"Nearest entity" text</b><br />
             <p>
-              This is the white writing along the bottom. It will tell you the locaton of the closest entity and its properties, but you don't need 
-              to worry about how to use that just yet.
+              This is the white writing along the bottom. It will tell you the locaton of the closest entity and its properties.
             </p>                        
           </td>
         </tr>
diff --git a/docs/mapediting2.xml b/docs/mapediting2.xml
index 72584b2f..be032d18 100644
--- a/docs/mapediting2.xml
+++ b/docs/mapediting2.xml
@@ -31,7 +31,9 @@
     </p>
     <p>
       You can save your map at any time by typing: <i>/savemap</i> and then the name you would like it saved as. The map gets
-      saved in the <i>packages/maps</i> directory. Save your map often, to avoid the frustration of losing all of your work if something goes wrong.
+      saved in the <i>packages/maps</i> directory. Save your map often, to avoid the frustration of losing all of your work if something goes wrong. 
+      Each time you do save your map, a backup of your last save is created with a timestamp that ends with the extension ".BAK". 
+      If you need to utilize these backups, all you will need to do, is rename the ".BAK" extension to ".cgz".
     </p>
     <p>
       <b>Note:</b> Make sure when you start a map, to use the <i>/newmap</i> command, rather than editing an existing map, otherwise your map may get saved
@@ -50,7 +52,7 @@
       by simply manipulating the geometry.
     </p>
     <p>
-      There are five different ways to manipulate geometry:
+      There are six different ways to manipulate geometry:
       <ul>
         <li>
           Make cubes "solid".
@@ -65,7 +67,10 @@
           Move cubes in the ceiling.
         </li>
         <li>
-          Manipulate cubes by using heightfields (a bit more complex, so this is covered later).
+          Turn a cube into a corner
+        </li>
+        <li>
+          Manipulate cubes by using heightfields.
         </li>
       </ul>
     </p>
@@ -74,6 +79,7 @@
       The reason we are covering solids and spaces, before moving cubes, is because solids block visibility and do not need to be rendered, so they 
       are more efficient to use in maps. The use of solids in a map is <u>essential</u> to creating a good map. Without enough solids AssaultCube maps 
       would lag too much for the average user and would be unplayable. Solids are also easy to create and can be used to make walls with a single keystroke!
+      <br /><b>Tip:</b> When you've finished your map, change any unused space into solids.
     </p>
     <ul>
       <li>
@@ -103,6 +109,50 @@
         </p>
       </li>
     </ul>
+    <h3>Corners</h3>
+    <p>
+      Corners are simple to create. Select a cube and press <b>K</b>. This will cut the cube in half diagonally, keeping one 
+      half and giving the other half to the nearest cube - making it a corner. The corner needs to be a power of 2 squares 
+      for this to work. To undo this a corner, press <b>G</b>.
+    </p>
+    <h3 id="heightfield">Heightfields</h3>
+    <p>
+      You can use heightfields to manipulate the corners of cubes and create slopes/arches. Heightfields are somewhat restrictive, so there are a 
+      few things to know about before creating a heightfield: 
+      <ol>
+        <li>
+          On a single cube, only the floor <b>OR</b> the ceiling can be a heightfield. A single cube can't have both.
+        </li>
+        <li>
+          All cubes that are going to be heightfielded need to be level (the same height) as each other if they are right next to each other. 
+          If they aren't, they will become glitchy.
+        </li>
+        <li>
+          Heightfields <b>can't</b> be corners too.
+        </li>
+        <li>
+          Pickups placed on heightfields will remain at the original height of the cube that was heightfielded.
+        </li>
+        <li>
+          Sometimes, when saved, textures on the wall/upper-wall part of a heightfield (or its surrounding cubes) may change. 
+          To fix this, try selecting all cubes in the surrounding area of this heightfield and change them to the texture you wanted.
+        </li>
+      </ol>
+      To create a heightfield, select a cube and press "<b>H</b>" or "<b>I</b>". "H" allows the heightfield to occur on the 
+      floor and "I" allows the heightfield to occur on the ceiling. You can hold down <b>Q and scroll</b> to manipulate each 
+      corner that the red dot on the <a href="mapediting1.xml#selector">cube selector</a> is, or you can use <b>8</b> or <b>9</b>
+      to move the cubes corner up/down. To undo a heightfield, press <b>G</b>.
+    </p>
+    <p>
+      Slopes and arches can be created by selecting an area and using the arch or slope command.
+    </p>
+    <p>	
+      <b>Slopes:</b> Type <b>/slope X Y</b>. Replace "X" and "Y" with different numbers to make your slope shape in different 
+      directions (you can use negative values here, for example: <i>/slope 0 -2</i>).
+    </p>
+    <p>
+      <b>Arches:</b> Type <b>/slope X</b> and replace "X" with a number to create different types of arches.
+    </p>    
 
     <h2>Textures</h2>
     <p>
@@ -172,25 +222,20 @@
       <br />Note: The "upper-wall" are the sides of the wall that protrudes from the ceiling.
     </p>  
     
+
+    <h2>Useful commands</h2>
+    <h3>Undo</h3>
+    <p>
+      Pressing <b>U</b> will undo the last texture/geometry action that was done. It will not undo entities.
+    </p>
+    <h3>Copy/paste</h3>
+    <p>
+      Selecting some cubes and pressing <b>C</b> will copy them. Then, select a cube and press <b>V</b> to paste it. 
+      The cubes will be pasted from the red dot on the <a href="mapediting1.xml#selector">cube selector</a>.
+    </p>
     
-    
-    
-    <h2 id="co-op">Co-operative map editing</h2>
-    <p>
-      Co-operative map editing lets you build and modify maps with others easily. This mode allows you to edit maps online with other players
-      who could help speed up repetitive or boring tasks, bring in fresh ideas or spot errors you may have missed.
-    </p>
-    <p>
-      To start co-operative map editing, when in a server, type: <i>/mode 1</i> and then type: <i>/map</i> and then your mapnames name and press ENTER.
-      You will have to of made a "newmap" previous to entering the server to be able to co-op edit it.
-    </p>
-    <p>
-      You will then need to <b>send</b> the map. You can do this by typing: <i>/sendmap</i> and then your mapnames name and press ENTER. Note: Custom 
-      materials can't be sent, they will have to be downloaded another way if you are using them. If you are using a custom "cfg" file, it will automatically
-      be sent with the map, if there is a cfg file present.
-    </p>
-    <p>
-      Note: Some useful editing commands can't be used in co-op editing, such as: copy, paste, slope, arch, undo, etc.
-    </p>
+    <h4>
+      The next step? Go to <a href="mapediting3.xml">Map editing: Entities</a> to learn how to place lights, spawns, etc.
+    </h4>
   </body>
 </html>
diff --git a/docs/mapediting3.xml b/docs/mapediting3.xml
new file mode 100644
index 00000000..9175c9a8
--- /dev/null
+++ b/docs/mapediting3.xml
@@ -0,0 +1,186 @@
+<?xml version="1.0" encoding="utf-8" ?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+<?xml-stylesheet type="text/xsl" href="transformations/cubedoc2xhtml.xslt"?>
+
+<html xmlns="http://www.w3.org/1999/xhtml" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" lang="en" xml:lang="en">
+  <head><title>Map editing: Entities</title></head>
+  <body>
+    <h1>Entities</h1>
+
+    <p>
+      <a href="mapediting1.xml#sparkles">Entities</a> are shown as blue sparkly dots when in edit mode. 
+      They are used for adding non-geometery/texture items, such as:
+      <ul>
+        <li>
+          <a href="#light">Lights</a>
+        </li>
+        <li>
+          <a href="#pickup">Item pickups</a>
+        </li>
+        <li>
+          <a href="#spawn">Spawn points</a>
+        </li>
+        <li>
+          <a href="#models">Mapmodels</a>
+        </li>
+        <li>
+          <a href="#ctf">CTF flags</a>
+        </li>
+        <li>
+          <a href="#ladders">Ladders</a>
+        </li>
+        <li>
+          <a href="#sounds">Ambient sounds</a>
+        </li>
+      </ul>
+    </p>
+
+    <p>
+      Each of these entities will be explained soon. All entities are added by the <b>/newent</b> command (or through the editing menu). 
+      When adding entities, they are always added to the red dot on the corner of the cube that you selected and at the height of 
+      which you are currently hovering (note: the physical entity created will always drop down to the ground).
+    </p>
+    <p>
+      Some useful commands to use with entities:
+      <ul>
+        <li>
+          <b><a href="reference.xml#identifier_delent">/delent</a></b> - Typing <i>/delent</i> (you can also press "backspace") will delete the nearest entity. 
+          The nearest entity can be found by reading the white text along the bottom of your screen which tells 
+          you the type of entity that you are nearest to and the properties of that entity.
+        </li>
+        <li>
+          <b><a href="reference.xml#identifier_entproperty">/entproperty</a></b>
+        </li>
+        <li>
+          <b><a href="reference.xml#identifier_clearents">/clearents</a></b>
+        </li>
+      </ul>
+    </p>
+    <h2 id="light">Lighting</h2>
+
+    <p>
+      <b>Tips:</b>
+      <ul>
+        <li>
+          To temporarally light up a map so you can edit it easily, type: <b>/fullbright 1</b>. To remove fullbright, type: <b>/recalc</b>. 
+        </li>
+        <li>
+          Make sure gamma is turned back to the defaults when you're editing so you can properly judge how a lighting will look to an average user.
+        </li>
+      </ul>
+    </p>
+
+    <p>
+      Lights can be added typing "<b>/newent light</b>" and then a number between 1 and 32 to define the size of the light (the radius) 
+      and then a number between 1 and 255 to define the brightness.
+    </p>
+
+    <p>
+      Coloured lighting can be added typing "<b>/newent light</b>" and then a number between 1 and 32 to define the size of the light 
+      (the radius) and then a number between 1 and 255 to define the amount of red light and then a number between 1 and 255 to define 
+      the amount of green light and then a number between 1 and 255 to define the amount of blue light.
+    </p>
+    <p>      
+      <b>Note:</b> The radius and all 3 colour values must be defined for a coloured light to be created correctly. You can't omit 
+      a value as it will not create the light correctly. If you don't want any colour from a specific value, 
+      simply use the value "1" as a place holder.
+    </p>
+
+    <p>
+      There is also a new handy menu that you can use to create lights by pressing L or accessing it through the editing menu. 
+    </p>
+
+    <p>
+      <b>Tip:</b> If you accidentally light a map too brightly (for example, you didn't reset your gamma levels before editing), 
+      instead of deleting lights and starting again, you could utilize the <b><a href="reference.xml#identifier_scalelights">/scalelights</a></b> command.
+    </p>
+
+    <h2 id="pickup">Item pickups</h2>
+
+    <p>
+      Pickups must be placed strategically through maps and do take some time to position correctly. Powerful pickups should be 
+      few and not be too close to each other (unless there is a good risk involved) and pickups should be well spread and not be 
+      too high in number. Try to keep powerful pickups away from the spawn area so players are encouraged to leave their bases. 
+      Strategy is key! A good idea to keep in mind when mapping is "<i>what would I need here to help me pwn?</i>"
+    </p>
+    <p>
+      To place pickups, use the pickups menu inside the editing menu, otherwise type one of the below...
+      <ul>
+        <li>
+          <b>/newent health</b> - To place a health pack.
+        </li>
+        <li>
+          <b>/newent armour</b> - To place armour.
+        </li>
+        <li>
+          <b>/newent akimbo</b> - To place akimbo.
+        </li>
+        <li>
+          <b>/newent grenades</b> - To place grenades.
+        </li>
+        <li>
+          <b>/newent clips</b> - To place a pistol magazine.
+        </li>
+        <li>
+          <b>/newent ammobox</b> - To place an ammunition box.
+        </li>
+      </ul>
+    </p>
+
+    <h2 id="spawn">Spawn points</h2>
+    <p>
+      In AssaultCube, there are three types of spawn points: RVSF spawn points, CLA spawn points and FFA spawn points (free-for-all).
+    </p>
+    <p>
+      As a general rule, you should place as many spawn points as possible in a spawn area so that players aren't spawning from the 
+      same point too often. However, don't over-do it. Make sure that spawn points are not too close to each other. 
+    </p>
+    <p>
+      Also make sure that spawns are not too close to any walls and mapmodels so players don't get stuck inside them. Take care when 
+      placing spawn points to make sure you face the direction you would like the player to face when they spawn, so that they spawn
+      looking in that direction, rather than facing a wall!
+    </p>
+    <p>
+      RVSF and CLA spawn points should be placed in their respective bases. FFA spawns should be placed all over the map in 
+      various places (FFA spawns are for non-team type games, such as Deathmatch or One-shot, one-kill).
+    </p>
+    <p>
+      If spawn points are not created, players will just spawn in the middle of the map, all next to each other, 
+      so please remember to add spawn points.
+    </p>
+    <p>
+      You can add spawn points through the editing menu, or you can type:
+      <ul>
+        <li>
+          <b>/newent playerstart 1</b> - To add an RVSF spawn point.
+        </li>
+        <li>
+          <b>/newent playerstart 0</b> - To add a CLA spawn point.
+        </li>
+        <li>
+          <b>/newent playerstart 100</b> - To add an FFA spawn point.
+        </li>
+      </ul>
+    </p>
+    <h2 id="models">Mapmodels :: TODO</h2>
+    <h2 id="ctf">CTF flags</h2>
+    <p>
+      If you want to enable CTF mode on your map, place a CTF flag in each respective base using the menus or by typing:
+      <ul>
+        <li>
+          <b>/newent ctf-flag 0</b> - Adds the CLA flag.
+        </li>
+        <li>
+          <b>/newent ctf-flag 1</b> - Adds the RVSF flag.
+        </li>
+      </ul>
+    </p>
+    <h2 id="ladders">Ladders :: TODO</h2>
+    <h2 id="sounds">Ambient sounds :: TODO</h2>
+
+
+
+
+
+  </body>
+</html>
diff --git a/docs/mapediting4.xml b/docs/mapediting4.xml
new file mode 100644
index 00000000..0399e02e
--- /dev/null
+++ b/docs/mapediting4.xml
@@ -0,0 +1,32 @@
+<?xml version="1.0" encoding="utf-8" ?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+<?xml-stylesheet type="text/xsl" href="transformations/cubedoc2xhtml.xslt"?>
+
+<html xmlns="http://www.w3.org/1999/xhtml" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" lang="en" xml:lang="en">
+  <head><title>Map editing: Tips</title></head>
+  <body>
+    <h1>Map editing: Tips</h1>
+    <h2 id="co-op">Co-operative map editing</h2>
+    <p>
+      If you'd like to create a map with friends, you can use co-operative map editing to let you build and modify maps with others online easily.
+      This mode allows you to edit maps online with other players
+      who could help speed up repetitive or boring tasks, bring in fresh ideas or spot errors you may have missed.
+    </p>
+    <p>
+      To start co-operative map editing, when in a server, type: <i>/mode 1</i> and then type: <i>/map</i> and then your mapnames name and press ENTER.
+      You will have to of made a "newmap" previous to entering the server to be able to co-op edit it.
+    </p>
+    <p>
+      You will then need to <b>send</b> the map. You can do this by typing: <i>/sendmap</i> and then your mapnames name and press ENTER. Note: Custom 
+      materials can't be sent, they will have to be downloaded another way if you are using them. If you are using a custom "cfg" file, it will automatically
+      be sent with the map, if there is a cfg file present.
+    </p>
+    <p>
+      Note: Some useful editing commands can't be used in co-op editing, such as: copy, paste, slope, arch, undo, etc.
+    </p>
+
+
+
+
+  </body>
+</html>
diff --git a/docs/mapediting5.xml b/docs/mapediting5.xml
new file mode 100644
index 00000000..ffc59259
--- /dev/null
+++ b/docs/mapediting5.xml
@@ -0,0 +1,12 @@
+<?xml version="1.0" encoding="utf-8" ?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+<?xml-stylesheet type="text/xsl" href="transformations/cubedoc2xhtml.xslt"?>
+
+<html xmlns="http://www.w3.org/1999/xhtml" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" lang="en" xml:lang="en">
+  <head><title>Map editing: Config files</title></head>
+  <body>
+    <h1>Map editing: Config files</h1>
+
+
+  </body>
+</html>