Ticket #1449: 1449_rms_wall_overlap6_comments.patch

binaries/data/mods/public/maps/random/rmgen/library.js

@@ -331 +331 @@
     }
 }
 
+/**
+ * Placed an entity with template "type" belonging to the given player at the specified X/Z location (in world units),
+ * and with the given rotation angle. 
+ *  
+ * @param type    Template name of the entity to be placed
+ * @param player  Owning player ID
+ * @param angle   TODO: document convention used for this angle
+ */
 function placeObject(x, z, type, player, angle)
 {
     g_Map.addObject(new Entity(type, player, x, z, angle));

binaries/data/mods/public/maps/random/rmgen/wall_builder.js

@@ -33 +33 @@
 // ?Think of something to enable splitting walls into two walls so more complex walls can be build and roads can have branches/crossroads?
 // ?Readjust placement angle for wall elements with bending when used in linear/circular walls by their bending?
 
+/**
+ * Note: this library uses its own coordinate system conventions and nomenclature that may not necessarily match those used in the rest of the game.
+ * Refer to http://trac.wildfiregames.com/wiki/Rmgen_Library for documentation.
+ */
 
-//////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
-//  WallElement class definition
-//
-//  Concept: If placed unrotated the wall's course is towards positive Y (top) with "outside" right (+X) and "inside" left (-X) like unrotated entities has their droppoints right (in rmgen)
-//  The coure of the wall will be changed by corners (bending != 0) and so the "inside"/"outside" direction
-//
-//  type    Descriptive string, example: "wallLong". NOTE: Not really needed. Mainly for custom wall elements and to get the wall element type in code
-//  entity  Optional. Template name string of the entity to be placed, example: "structures/cart_wall_long". Default is undefined (No entity placed)
-//  angle   Optional. The angle (float) added to place the entity so "outside" is right when the wall element is placed unrotated. Default is 0
-//  width   Optional. How far this wall element enlengthens the wall (float), if unrotated the Y space needed. Default is 0
-//  indent  Optional. The lateral indentation of the entity, drawn "inside" (positive values) or pushed "outside" (negative values). Default is 0
-//  bending Optional. How the course of the wall is changed after this element, positive is bending "in"/left/counter clockwise (like entity placement)
-//      NOTE: Bending is not supported by all placement functions (see there)
-//////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
+/**
+ * WallElement constructor.
+ * 
+ * Defines a type of wall element, i.e. entities that are atomic parts of a wall. Walls are conceptualized as a sequence of wall elements (or actually
+ * their identifier strings -- see below), thus forming a 2D polygonal path.
+ * 
+ * Wall elements have the concept of an "inside" and "outside" direction. The "outside" direction is equivalent to the normal vector of the face formed
+ * by the element in the polygonal path traced by its wall. By default, i.e. unrotated, the "outside" direction is taken to point towards the
+ * positive X axis, i.e. to the right, and the "inside" direction similarly towards the negative X axis, i.e. to the left.
+ * 
+ * At each step, consecutive wall elements are appended in the direction that is to the perpendicular left of the face normal (that is, the face normal
+ * angle + 90 degrees anticlockwise). Hence, when placed without rotation (as is the default), the wall's course is straight up towards positive Y.
+ * The course of the wall can be changed by means of the 'bending' property of individual wall elements; see parameter documentation for details.
+ * 
+ * For the entity models to line up visually, they must all agree on a particular side to display towards this "outside" direction. Since models are free
+ * to be modeled pointing any which way in their local object space, wall elements include a corrective angle to make the desired side of the model
+ * correspond to the "outside" direction, i.e., to make that side point towards the right in their object space.
+ * 
+ * @param type     Identifier for this wall element, e.g. "wallLong".
+ * @param entity   Template name of the in-game entity for this element, e.g. "structures/cart_wall_long". Defaults to undefined (no entity placed).
+ * @param angle    Corrective angle applied at placement time to ensure that the in-game entity aligns correctly with the "outside" direction.
+ *                   Defaults to 0 (no correction applied).
+ * @param width    Distance by which this wall element increases a wall's length, in world units. Defaults to 0 (no length increase).
+ * @param indent   Lateral indentation of the wall element, in world units. May be positive for displacement along the "inside" vector, or negative
+ *                   for displacement along the "outside" vector. Defaults to 0 (no lateral indentation).
+ * @param bending  Change of course of a wall *after* having placed this element in its sequence, expressed as a change in the direction of the
+ *                   face normal vector (aka. "outside" direction). May be positive for curving "inwards"/anticlockwise, or negative for curving
+ *                   "outwards"/clockwise. Defaults to 0 (no change of course after this element).
+ *                   NOTE: Not supported by all wall placement functions. See below for details.
+ */
 function WallElement(type, entity, angle, width, indent, bending)
 {
     this.type = type;
@@ -79 +99 @@
     this.bending = (bending !== undefined) ? bending : 0*PI;
 }
 
-/////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
-//  Fortress class definition
-//
-//  A "fortress" here is a closed wall build of multiple wall elements attached togather defined in Fortress.wall
-//  It's mainly the abstract shape defined in a Fortress instances wall because different styles can be used for it (see wallStyles)
-//
-//  type                  Descriptive string, example: "tiny". Not really needed (WallTool.wallTypes["type string"] is used). Mainly for custom wall elements
-//  wall                  Optional. Array of wall element strings. Can be set afterwards. Default is an epty array.
-//      Example: ["entrance", "wall", "cornerIn", "wall", "gate", "wall", "entrance", "wall", "cornerIn", "wall", "gate", "wall", "cornerIn", "wall"]
-//  centerToFirstElement  Optional. Object with propertys "x" and "y" representing a vector from the visual center to the first wall element. Default is undefined
-/////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
+/**
+ * Fortress constructor.
+ * 
+ * Defines a type of closed wall, where a wall is a sequence of WallElement identifiers as defined above. Not to be confused with in-game
+ * fortress entities/models.
+ * 
+ * Note that Fortresses are style-agnostic since they only reference WallElement identifiers (see below).
+ * The corresponding WallElement instances for any particular style can be looked up via the global wallStyles map.
+ * 
+ * @param {String} type  Identifier for this fortress, e.g. "tiny".
+ * @param {Array}  wall  Optional; array of WallElement identifiers that make up the wall. Can be set/modified after construction. Defaults to the empty array.
+ *                         Example value: ["entrance", "wall", "cornerIn", "wall"].
+ * @param {Object} centerToFirstElement Optional; vector from the (visual) center of the fortress to the center of the first wall element, assuming a zero
+ *                                        rotation. Defaults to undefined, in which case it will be taken to equal the center of mass when needed.
+ */
 function Fortress(type, wall, centerToFirstElement)
 {
-    this.type = type; // Only usefull to get the type of the actual fortress
+    this.type = type;
     this.wall = (wall !== undefined) ? wall : [];
     this.centerToFirstElement = undefined;
 }
 
-
-////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
-//  wallStyles data structure for default wall styles
-//
-//  A wall style is an associative array with all wall elements of that style in it associated with the wall element type string
-//  wallStyles holds all the wall styles within an associative array with the civ string or another descriptive strings as key
-//  Examples: "athen", "rome_siege", "palisades", "fence", "road"
-////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
+/**
+ * wallStyles data structure for default wall styles
+ * 
+ * A single wall style is an associative array that maps a set of WallElement identifier strings to their corresponding WallElements.
+ * This global wallStyles data structure, then, holds a set of predefined wall styles, indexed by a style identifier (usually a civilization
+ * name or another descriptive string, e.g. "athen", "rome_siege", "palisades", "fence", "road").
+ */
 var wallStyles = {};
 
-// Generic civ dependent wall style definition. "rome_siege" needs some tweek...
+// Generic civ-dependent wall style definitions. "rome_siege" needs some tweaking still ...
 var wallScaleByType = {"athen" : 1.5, "brit" : 1.5, "cart" : 1.8, "celt" : 1.5, "gaul" : 1.5, "hele" : 1.5, "iber" : 1.5, "mace" : 1.5, "pers" : 1.5, "rome" : 1.5, "spart" : 1.5, "rome_siege" : 1.5};
 for (var style in wallScaleByType)
 {
     var civ = style;
     if (style == "rome_siege")
         civ = "rome";
+    
     wallStyles[style] = {};
+    
     // Default wall elements
     wallStyles[style]["tower"] = new WallElement("tower", "structures/" + style + "_wall_tower", PI, wallScaleByType[style]);
     wallStyles[style]["endLeft"] = new WallElement("endLeft", "structures/" + style + "_wall_tower", PI, wallScaleByType[style]); // Same as tower. To be compatible with palisades...
@@ -125 +150 @@
     wallStyles[style]["wall"] = new WallElement("wall", "structures/" + style + "_wall_medium", 0*PI, 4*wallScaleByType[style]);
     wallStyles[style]["wallMedium"] = new WallElement("wall", "structures/" + style + "_wall_medium", 0*PI, 4*wallScaleByType[style]);
     wallStyles[style]["wallLong"] = new WallElement("wallLong", "structures/" + style + "_wall_long", 0*PI, 6*wallScaleByType[style]);
+    
     // Gate and entrance wall elements
     if (style == "cart")
         var gateWidth = 3.5*wallScaleByType[style];
@@ -132 +158 @@
         var gateWidth = 4*wallScaleByType[style];
     else
         var gateWidth = 6*wallScaleByType[style];
+    
     wallStyles[style]["gate"] = new WallElement("gate", "structures/" + style + "_wall_gate", 0*PI, gateWidth);
     wallStyles[style]["entry"] = new WallElement("entry", undefined, 0*PI, gateWidth);
     wallStyles[style]["entryTower"] = new WallElement("entryTower", "structures/" + civ + "_defense_tower", PI, gateWidth, -4*wallScaleByType[style]);
     wallStyles[style]["entryFort"] = new WallElement("entryFort", "structures/" + civ + "_fortress", 0*PI, 8*wallScaleByType[style], 6*wallScaleByType[style]);
+    
     // Defensive wall elements with 0 width outside the wall
     wallStyles[style]["outpost"] = new WallElement("outpost", "structures/" + civ + "_outpost", PI, 0, -4*wallScaleByType[style]);
     wallStyles[style]["defenseTower"] = new WallElement("defenseTower", "structures/" + civ + "_defenseTower", PI, 0, -4*wallScaleByType[style]);
+    
     // Base buildings wall elements with 0 width inside the wall
     wallStyles[style]["barracks"] = new WallElement("barracks", "structures/" + civ + "_barracks", PI, 0, 4.5*wallScaleByType[style]);
     wallStyles[style]["civilCentre"] = new WallElement("civilCentre", "structures/" + civ + "_civil_centre", PI, 0, 4.5*wallScaleByType[style]);
@@ -149 +178 @@
     wallStyles[style]["market"] = new WallElement("market", "structures/" + civ + "_market", PI, 0, 4.5*wallScaleByType[style]);
     wallStyles[style]["mill"] = new WallElement("mill", "structures/" + civ + "_mill", PI, 0, 4.5*wallScaleByType[style]);
     wallStyles[style]["temple"] = new WallElement("temple", "structures/" + civ + "_temple", PI, 0, 4.5*wallScaleByType[style]);
+    
     // Generic space/gap wall elements
     wallStyles[style]["space1"] = new WallElement("space1", undefined, 0*PI, wallScaleByType[style]);
     wallStyles[style]["space2"] = new WallElement("space2", undefined, 0*PI, 2*wallScaleByType[style]);
     wallStyles[style]["space3"] = new WallElement("space3", undefined, 0*PI, 3*wallScaleByType[style]);
     wallStyles[style]["space4"] = new WallElement("space4", undefined, 0*PI, 4*wallScaleByType[style]);
 }
-// Add wall fortresses for all generic styles
+
+// Add wall fortresses for all generic styles.
+// Not to be confused with Fortress instances!
 wallStyles["athen"]["wallFort"] = new WallElement("wallFort", "structures/athen_fortress", 2*PI/2 /* PI/2 */, 5.1 /* 5.6 */, 1.9 /* 1.9 */);
 wallStyles["brit"]["wallFort"] = new WallElement("wallFort", "structures/brit_fortress", PI, 2.8);
 wallStyles["cart"]["wallFort"] = new WallElement("wallFort", "structures/cart_fortress", PI, 5.1, 1.6);
@@ -167 +199 @@
 wallStyles["pers"]["wallFort"] = new WallElement("wallFort", "structures/pers_fortress", PI, 5.6/*5.5*/, 1.9/*1.7*/);
 wallStyles["rome"]["wallFort"] = new WallElement("wallFort", "structures/rome_fortress", PI, 6.3, 2.1);
 wallStyles["spart"]["wallFort"] = new WallElement("wallFort", "structures/spart_fortress", 2*PI/2 /* PI/2 */, 5.1 /* 5.6 */, 1.9 /* 1.9 */);
+
 // Adjust "rome_siege" style
 wallStyles["rome_siege"]["wallFort"] = new WallElement("wallFort", "structures/rome_army_camp", PI, 7.2, 2);
 wallStyles["rome_siege"]["entryFort"] = new WallElement("entryFort", "structures/rome_army_camp", PI, 12, 7);
@@ -237 +270 @@
 wallStyles["other"]["cornerOut"] = new WallElement("cornerOut", undefined, 0, 0, 0, -PI/2);
 
 
-////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
-//  fortressTypes data structure for some default fortress types
-//
-//  A fortress type is just an instance of the Fortress class with actually something in it
-//  fortressTypes holds all the fortressess within an associative array with a descriptive string as key (e.g. maching the map size)
-//  Eexamples: "tiny", "veryLarge"
-////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
+/**
+ * fortressTypes data structure for some default fortress types. Holds a set of predefined Fortresses, indexed by a descriptive string
+ * (e.g. matching the map size: "tiny", "veryLarge", etc).
+ */
+
 var fortressTypes = {};
-// Setup some default fortress types
+
 // Add fortress type "tiny"
 fortressTypes["tiny"] = new Fortress("tiny");
 var wallPart = ["entry", "wall", "cornerIn", "wall"];
 fortressTypes["tiny"].wall = wallPart.concat(wallPart, wallPart, wallPart);
+
 // Add fortress type "small"
 fortressTypes["small"] = new Fortress("small");
 var wallPart = ["entry", "endLeft", "wall", "cornerIn", "wall", "endRight"];
 fortressTypes["small"].wall = wallPart.concat(wallPart, wallPart, wallPart);
+
 // Add fortress type "medium"
 fortressTypes["medium"] = new Fortress("medium");
 var wallPart = ["entry", "endLeft", "wall", "outpost", "wall",
     "cornerIn", "wall", "outpost", "wall", "endRight"];
 fortressTypes["medium"].wall = wallPart.concat(wallPart, wallPart, wallPart);
+
 // Add fortress type "normal"
 fortressTypes["normal"] = new Fortress("normal");
 var wallPart = ["entry", "endLeft", "wall", "tower", "wall",
     "cornerIn", "wall", "tower", "wall", "endRight"];
 fortressTypes["normal"].wall = wallPart.concat(wallPart, wallPart, wallPart);
+
 // Add fortress type "large"
 fortressTypes["large"] = new Fortress("large");
 var wallPart = ["entry", "endLeft", "wall", "outpost", "wall", "cornerIn", "wall",
     "cornerOut", "wall", "cornerIn", "wall", "outpost", "wall", "endRight"];
 fortressTypes["large"].wall = wallPart.concat(wallPart, wallPart, wallPart);
+
 // Add fortress type "veryLarge"
 fortressTypes["veryLarge"] = new Fortress("veryLarge");
 var wallPart = ["entry", "endLeft", "wall", "tower", "wall", "cornerIn", "wall",
     "cornerOut", "wall", "cornerIn", "wall", "tower", "wall", "endRight"];
 fortressTypes["veryLarge"].wall = wallPart.concat(wallPart, wallPart, wallPart);
+
 // Add fortress type "giant"
 fortressTypes["giant"] = new Fortress("giant");
 var wallPart = ["entry", "endLeft", "wall", "outpost", "wall", "cornerIn", "wall", "outpost", "wall",
     "cornerOut", "wall", "outpost", "wall", "cornerIn", "wall", "outpost", "wall", "endRight"];
 fortressTypes["giant"].wall = wallPart.concat(wallPart, wallPart, wallPart);
 
-// Setup some better looking semi default fortresses for "palisades" style
+// Setup some better looking semi default fortresses for the "palisades" style
 var fortressTypeKeys = ["tiny", "small", "medium", "normal", "large", "veryLarge", "giant"];
 for (var i = 0; i < fortressTypeKeys.length; i++)
 {
@@ -301 +338 @@
 // TODO
 
 // Add some "fortress types" for roads (will only work with style "road")
-// ["start", "short", "xRight", "xLeft", "cornerLeft", "xStraight", "long", "xLeft", "xRight", "cornerRight", "tRight", "tLeft", "xRight", "xLeft", "curveLeft", "xStraight", "curveRight", "end"];
+// ["start", "short", "xRight", "xLeft", "cornerLeft", "xStraight", "long", "xLeft", "xRight", "cornerRight", "tRight", "tLeft",
+//  "xRight", "xLeft", "curveLeft", "xStraight", "curveRight", "end"];
 var wall = ["short", "curveLeft", "short", "curveLeft", "short", "curveLeft", "short", "curveLeft"];
 fortressTypes["road01"] = new Fortress("road01", wall);
+
 var wall = ["short", "cornerLeft", "short", "cornerLeft", "short", "cornerLeft", "short", "cornerLeft"];
 fortressTypes["road02"] = new Fortress("road02", wall);
+
 var wall = ["xStraight", "curveLeft", "xStraight", "curveLeft", "xStraight", "curveLeft", "xStraight", "curveLeft"];
 fortressTypes["road03"] = new Fortress("road03", wall);
+
 var wall = ["start", "curveLeft", "tRight", "cornerLeft", "tRight", "curveRight", "short", "xRight", "curveLeft", "xRight", "short", "cornerLeft", "tRight", "short",
     "curveLeft", "short", "tRight", "cornerLeft", "short", "xRight", "curveLeft", "xRight", "short", "curveRight", "tRight", "cornerLeft", "tRight", "curveLeft", "end"];
 fortressTypes["road04"] = new Fortress("road04", wall);
+
 var wall = ["start", "tLeft", "short", "xRight",
     "curveLeft", "xRight", "tRight", "cornerLeft", "tRight",
     "curveLeft", "short", "tRight", "cornerLeft", "xRight",
@@ -322 +364 @@
 // Define some helper functions
 ///////////////////////////////
 
-/////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
-//  getWallAlignment
-//
-//  Returns a list of objects containing all information to place all the wall elements entities with placeObject (but the player ID)
-//  Placing the first wall element at startX/startY placed with an angle given by orientation
-//  An alignement can be used to get the "center" of a "wall" (more likely used for fortresses) with getCenterToFirstElement
-/////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
+/**
+ * Returns a list of objects specifying the placement parameters for the entities required to build the given wall at the specified
+ * starting location and orientation. Each object contains data suitable for use with placeObject (see library.js).
+ * 
+ * The returned value is called an "alignment", and is of the form:
+ *     [{x: ..., y: ..., entity: ..., angle: ...},
+ *       ...]
+ * 
+ * @param startX       X location (in world units) of the center of the first wall element to be placed.
+ * @param startY       Y location (in world units) of the center of the first wall element to be placed.
+ * @param wall         Array of WallElement identifier strings. Should exist as keys in wallStyles[style] (see the style parameter).
+ * @param style        Style identifier string to use for the wall elements. See the global wallStyles array.
+ * @param orientation  Initial rotation of the "outside" direction (or face normal vector) to begin placement with, relative CCW to the
+ *                       positive X-axis.
+ */
 function getWallAlignment(startX, startY, wall, style, orientation)
 {
     orientation = (orientation || 0);
     var alignment = [];
     var wallX = startX;
     var wallY = startY;
+    
     for (var i = 0; i < wall.length; i++)
     {
         var element = wallStyles[style][wall[i]];
-        if (element === undefined && i == 0)
+        if (element === undefined/* && i == 0*/)
             warn("No valid wall element: " + wall[i]);
+        
         // Indentation
         var placeX = wallX - element.indent * cos(orientation);
         var placeY = wallY - element.indent * sin(orientation);
+        
         // Add wall elements entity placement arguments to the alignment
         alignment.push({"x": placeX, "y": placeY, "entity": element.entity, "angle":orientation + element.angle});
+        
         // Preset vars for the next wall element
         if (i+1 < wall.length)
         {
@@ -352 +406 @@
             var nextElement = wallStyles[style][wall[i+1]];
             if (nextElement === undefined)
                 warn("No valid wall element: " + wall[i+1]);
+            
             var distance = (element.width + nextElement.width)/2;
+            
             // Corrections for elements with indent AND bending
             var indent = element.indent;
             var bending = element.bending;
@@ -372 +428 @@
     return alignment;
 }
 
-//////////////////////////////////////////////////////////////////////////////////////////////////////////////////
-//  getCenterToFirstElement
-//
-//  Center calculation works like getting the center of mass assuming all wall elements have the same "weight"
-//
-//  It returns the vector from the center to the first wall element
-//  Used to get centerToFirstElement of fortresses by default
-//////////////////////////////////////////////////////////////////////////////////////////////////////////////////
+/**
+ * Returns a vector from the center of mass of the given wall to the center of its first entity, at zero rotation of the wall,
+ * and assuming all wall entities have the same weight. Used to compute the centers of Fortresses if none is otherwise given
+ * (see the Fortress class).
+ */
 function getCenterToFirstElement(alignment)
 {
     var centerToFirstElement = {"x": 0, "y": 0};
@@ -417 +470 @@
 //
 //  Places a wall with wall elements attached to another like determined by WallElement properties.
 //
-//  startX, startY  Where the first wall element should be placed
-//  wall            Array of wall element type strings. Example: ["endLeft", "wallLong", "tower", "wallLong", "endRight"]
-//  style           Optional. Wall style string. Default is the civ of the given player, "palisades" for gaia
-//  playerId        Optional. Number of the player the wall will be placed for. Default is 0 (gaia)
-//  orientation     Optional. Angle the first wall element is placed. Default is 0
-//                  0 means "outside" or "front" of the wall is right (positive X) like placeObject
-//                  It will then be build towards top/positive Y (if no bending wall elements like corners are used)
-//                  Raising orientation means the wall is rotated counter-clockwise like placeObject
+//  startX, startY  Location of the center of the first wall element, in world units.
+//  wall            Array of WallElement identifier strings. Example: ["endLeft", "wallLong", "tower", "wallLong", "endRight"]
+//  style           Optional. Wall style string. Default is the civ of the given player, or "palisades" for gaia or if no player is given.
+//                    See the global wallStyles array.
+//  playerId        Optional. Player ID of the owner of the wall. Default is 0 (gaia).
+//  orientation     Optional. Initial rotation of the "outside" direction (or face normal vector) to begin placement with, relative CCW to the
+//                    positive X-axis (as in placeObject).
 /////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
 function placeWall(startX, startY, wall, style, playerId, orientation)
 {
@@ -435 +487 @@
     else
         style = (style || g_MapSettings.PlayerData[playerId-1].Civ);
     orientation = (orientation || 0);
+    
     // Get wall alignment
     var AM = getWallAlignment(startX, startY, wall, style, orientation);
+    
     // Place the wall
     for (var iWall = 0; iWall < wall.length; iWall++)
     {
@@ -449 +503 @@
 /////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
 //  placeCustomFortress
 //
-//  Place a fortress (mainly a closed wall build like placeWall) centered at centerX/centerY
-//  The fortress wall should always start with the main entrance (like "entry" or "gate") to get the orientation right (like placeObject)
-//
-//  fortress       An instance of Fortress with a wall defined
-//  style          Optional. Wall style string. Default is the civ of the given player, "palisades" for gaia
-//  playerId       Optional. Number of the player the wall will be placed for. Default is 0 (gaia)
-//  orientation    Optional. Angle the first wall element (should be a gate or entrance) is placed. Default is 0
+//  Places a fortress centered at centerX/centerY.
+//  The fortress wall should always start with a main entrance (e.g. the WallElements "entry" or "gate") to get the orientation right
+//  (like placeObject).
+//  
+//  centerX, centerY  Location of the center of mass of the fortress, in world units.
+//  fortress          An instance of Fortress, with a wall defined.
+//  style             Optional. Wall style string. Default is the civ of the given player, "palisades" for gaia or if no player is given.
+//                      See the global wallStyles array.
+//  playerId          Optional. Player ID of the owner of the wall. Default is 0 (gaia).
+//  orientation       Optional. Initial rotation of the "outside" direction (or face normal vector) to begin placement with, relative CCW to the
+//                      positive X-axis (as in placeObject).
 /////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
 function placeCustomFortress(centerX, centerY, fortress, style, playerId, orientation)
 {
@@ -467 +525 @@
     else
         style = (style || g_MapSettings.PlayerData[playerId-1].Civ);
     orientation = (orientation || 0);
+    
     // Calculate center if fortress.centerToFirstElement is undefined (default)
     var centerToFirstElement = fortress.centerToFirstElement;
     if (centerToFirstElement === undefined)
         centerToFirstElement = getCenterToFirstElement(getWallAlignment(0, 0, fortress.wall, style));
+    
     // Placing the fortress wall
     var startX = centerX + centerToFirstElement.x * cos(orientation) - centerToFirstElement.y * sin(orientation);
     var startY = centerY + centerToFirstElement.y * cos(orientation) + centerToFirstElement.x * sin(orientation);
-    placeWall(startX, startY, fortress.wall, style, playerId, orientation)
+    placeWall(startX, startY, fortress.wall, style, playerId, orientation);
 }
 
 ///////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
 //  placeFortress
 //
-//  Like placeCustomFortress just it takes type (a fortress type string, has to be in fortressTypes) instead of an instance of Fortress
+//  Like placeCustomFortress, but takes a fortress type identifier instead of an instance of Fortress (which must be defined in fortressTypes). 
 ///////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
 function placeFortress(centerX, centerY, type, style, playerId, orientation)
 {
@@ -492 +552 @@
     else
         style = (style || g_MapSettings.PlayerData[playerId-1].Civ);
     orientation = (orientation || 0);
+    
     // Call placeCustomFortress with the given arguments
     placeCustomFortress(centerX, centerY, fortressTypes[type], style, playerId, orientation);
 }
@@ -520 +581 @@
     else
         style = (style || g_MapSettings.PlayerData[playerId-1].Civ);
     endWithFirst = typeof endWithFirst == "undefined" ? true : endWithFirst;
+    
     // Check arguments
     for (var elementIndex = 0; elementIndex < wallPart.length; elementIndex++)
     {
@@ -527 +589 @@
         if (bending != 0)
             warn("Bending is not supported by placeLinearWall but a bending wall element is used: " + wallPart[elementIndex] + " -> wallStyles[style][wallPart[elementIndex]].entity");
     }
+    
     // Setup number of wall parts
     var totalLength = getDistance(startX, startY, targetX, targetY);
     var wallPartLength = 0;
@@ -537 +600 @@
         numParts = ceil((totalLength - wallStyles[style][wallPart[0]].width) / wallPartLength);
     else
         numParts = ceil(totalLength / wallPartLength);
+    
     // Setup scale factor
     var scaleFactor = 1;
     if (endWithFirst == true)
         scaleFactor = totalLength / (numParts * wallPartLength + wallStyles[style][wallPart[0]].width);
     else
         scaleFactor = totalLength / (numParts * wallPartLength);
+    
     // Setup angle
     var wallAngle = getAngle(startX, startY, targetX, targetY); // NOTE: function "getAngle()" is about to be changed...
     var placeAngle = wallAngle - PI/2;
+    
     // Place wall entities
     var x = startX;
     var y = startY;
@@ -554 +620 @@
         for (var elementIndex = 0; elementIndex < wallPart.length; elementIndex++)
         {
             var wallEle = wallStyles[style][wallPart[elementIndex]];
+            
             // Width correction
             x += scaleFactor * wallEle.width/2 * cos(wallAngle);
             y += scaleFactor * wallEle.width/2 * sin(wallAngle);
+            
             // Indent correction
             var placeX = x - wallEle.indent * sin(wallAngle);
             var placeY = y + wallEle.indent * cos(wallAngle);
+            
             // Placement
             var entity = wallEle.entity;
             if (entity !== undefined)
@@ -587 +656 @@
 //  The orientation then determines where this open part faces (0 means right like unrotated building's droppoints)
 //
 //  centerX/Y     Coordinates of the circle's center
-//  radius        How wide the circle should be (aproximate, especially if maxBendOff != 0)
+//  radius        How wide the circle should be (approximately, especially if maxBendOff != 0)
 //  wallPart      Optional. An array of NON-BENDING wall element type strings. Default is ["tower", "wallLong"]
 //  style         Optional. Wall style string. Default is the civ of the given player, "palisades" for gaia
 //  playerId      Optional. Integer number of the player. Default is 0 (gaia)
@@ -597 +666 @@
 //  maxBendOff    Optional. How irregular the circle should be. 0 means regular circle, PI/2 means very irregular. Default is 0 (regular circle)
 //
 //  NOTE: Don't use wall elements with bending like corners!
-//  TODO: Perhaps add eccentricity and maxBendOff functionality (untill now an unused argument)
+//  TODO: Perhaps add eccentricity and maxBendOff functionality (until now an unused argument)
 //  TODO: Perhaps add functionality for spirals
 /////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
 function placeCircularWall(centerX, centerY, radius, wallPart, style, playerId, orientation, maxAngle, endWithFirst, maxBendOff)
@@ -611 +680 @@
         style = (style || g_MapSettings.PlayerData[playerId-1].Civ);
     orientation = (orientation || 0);
     maxAngle = (maxAngle || 2*PI);
+    
     if (endWithFirst === undefined)
     {
         if (maxAngle >= 2*PI - 0.001) // Can this be done better?
@@ -619 +689 @@
             endWithFirst = true;
     }
     maxBendOff = (maxBendOff || 0);
+    
     // Check arguments
     if (maxBendOff > PI/2 || maxBendOff < 0)
         warn("placeCircularWall maxBendOff sould satisfy 0 < maxBendOff < PI/2 (~1.5) but it is: " + maxBendOff);
@@ -628 +699 @@
         if (bending != 0)
             warn("Bending is not supported by placeCircularWall but a bending wall element is used: " + wallPart[elementIndex]);
     }
+    
     // Setup number of wall parts
     var totalLength = maxAngle * radius;
     var wallPartLength = 0;
@@ -642 +714 @@
     {
         numParts = ceil(totalLength / wallPartLength);
     }
+    
     // Setup scale factor
     var scaleFactor = 1;
     if (endWithFirst == true)
         scaleFactor = totalLength / (numParts * wallPartLength + wallStyles[style][wallPart[0]].width);
     else
         scaleFactor = totalLength / (numParts * wallPartLength);
+    
     // Place wall entities
     var actualAngle = orientation + (2*PI - maxAngle) / 2;
     var x = centerX + radius*cos(actualAngle);
@@ -657 +731 @@
         for (var elementIndex = 0; elementIndex < wallPart.length; elementIndex++)
         {
             var wallEle = wallStyles[style][wallPart[elementIndex]];
+            
             // Width correction
             var addAngle = scaleFactor * wallEle.width / radius;
             var targetX = centerX + radius * cos(actualAngle + addAngle);
@@ -664 +739 @@
             var placeX = x + (targetX - x)/2;
             var placeY = y + (targetY - y)/2;
             var placeAngle = actualAngle + addAngle/2;
+            
             // Indent correction
             placeX -= wallEle.indent * cos(placeAngle);
             placeY -= wallEle.indent * sin(placeAngle);
+            
             // Placement
             var entity = wallEle.entity;
             if (entity !== undefined)
                 placeObject(placeX, placeY, entity, playerId, placeAngle + wallEle.angle);
+            
             // Prepare for the next wall element
             actualAngle += addAngle;
             x = centerX + radius*cos(actualAngle);
@@ -723 +801 @@
     orientation = (orientation || 0);
     numCorners = (numCorners || 8);
     skipFirstWall = (skipFirstWall || true);
+    
     // Setup angles
     var angleAdd = 2*PI/numCorners;
     var angleStart = orientation - angleAdd/2;
+    
     // Setup corners
     var corners = [];
     for (var i = 0; i < numCorners; i++)
         corners.push([centerX + radius*cos(angleStart + i*angleAdd), centerY + radius*sin(angleStart + i*angleAdd)]);
+    
     // Place Corners and walls
     for (var i = 0; i < numCorners; i++)
     {
@@ -778 +859 @@
         style = (style || "palisades");
     else
         style = (style || g_MapSettings.PlayerData[playerId-1].Civ);
+    
     // Generating a generic wall part assortment with each wall part including 1 gate enlengthend by walls and towers
     // NOTE: It might be a good idea to write an own function for that...
     var defaultWallPartsAssortment = [["wallShort"], ["wall"], ["wallLong"], ["gate", "tower", "wallShort"]];
@@ -800 +882 @@
             defaultWallPartsAssortment.push(wallPart);
         }
     }
+    
     // Setup optional arguments to the default
     wallPartsAssortment = (wallPartsAssortment || defaultWallPartsAssortment);
     cornerWallElement = (cornerWallElement || "tower"); // Don't use wide elements for this. Not supported well...
@@ -809 +892 @@
     numCorners = (numCorners || randInt(5, 7));
     irregularity = (irregularity || 0.5);
     skipFirstWall = (skipFirstWall || false);
+    
     // Setup angles
     var angleToCover = 2*PI;
     var angleAddList = [];
@@ -818 +902 @@
         angleAddList.push(angleToCover/(numCorners-i) * (1 + randFloat(-irregularity, irregularity)));
         angleToCover -= angleAddList[angleAddList.length - 1];
     }
+    
     // Setup corners
     var corners = [];
     var angleActual = orientation - angleAddList[0]/2;
@@ -827 +912 @@
         if (i < numCorners - 1)
             angleActual += angleAddList[i+1];
     }
+    
     // Setup best wall parts for the different walls (a bit confusing naming...)
     var wallPartLengths = [];
     var maxWallPartLength = 0;
@@ -840 +926 @@
     var wallPartList = []; // This is the list of the wall parts to use for the walls between the corners, not to confuse with wallPartsAssortment!
     for (var i = 0; i < numCorners; i++)
     {
-        var bestWallPart = []; // This is a simpel wall part not a wallPartsAssortment!
+        var bestWallPart = []; // This is a simple wall part not a wallPartsAssortment!
         var bestWallLength = 99999999;
-        // NOTE: This is not exsactly like the length the wall will be in the end. Has to be tweeked...
+        // NOTE: This is not exactly like the length the wall will be in the end. Has to be tweaked...
         var wallLength = getDistance(corners[i][0], corners[i][1], corners[(i+1)%numCorners][0], corners[(i+1)%numCorners][1]);
         var numWallParts = ceil(wallLength/maxWallPartLength);
         for (var partIndex = 0; partIndex < wallPartsAssortment.length; partIndex++)
@@ -856 +942 @@
         }
         wallPartList.push(bestWallPart);
     }
+    
     // Place Corners and walls
     for (var i = 0; i < numCorners; i++)
     {
@@ -897 +984 @@
         style = (style || "palisades");
     else
         style = (style || g_MapSettings.PlayerData[playerId-1].Civ);
+    
     irregularity = (irregularity || 1/2);
     gateOccurence = (gateOccurence || 3);
     maxTrys = (maxTrys || 100);
+    
     // Setup some vars
     var startAngle = randFloat(0, 2*PI);
     var actualOffX = radius*cos(startAngle);
     var actualOffY = radius*sin(startAngle);
     var actualAngle = startAngle;
     var pointDistance = wallStyles[style]["wallLong"].width + wallStyles[style]["tower"].width;
+    
     // Searching for a well fitting point derivation
     var tries = 0;
     var bestPointDerivation = undefined;
@@ -922 +1012 @@
             var tmpAngle = getAngle(actualOffX, actualOffY,
                 (radius + indent)*cos(actualAngle + (pointDistance / radius)),
                 (radius + indent)*sin(actualAngle + (pointDistance / radius)));
+            
             actualOffX += pointDistance*cos(tmpAngle);
             actualOffY += pointDistance*sin(tmpAngle);
             actualAngle = getAngle(0, 0, actualOffX, actualOffY);
             pointDerivation.push([actualOffX, actualOffY]);
             distanceToTarget = getDistance(actualOffX, actualOffY, pointDerivation[0][0], pointDerivation[0][1]);
+            
             var numPoints = pointDerivation.length;
             if (numPoints > 3 && distanceToTarget < pointDistance) // Could be done better...
             {
@@ -951 +1043 @@
         var targetY = centerY + bestPointDerivation[(pointIndex + 1) % bestPointDerivation.length][1];
         var angle = getAngle(startX, startY, targetX, targetY);
         var wallElement = "wallLong";
+        
         if ((pointIndex + 1) % gateOccurence == 0)
             wallElement = "entry"; // Has to be changed to "gate" if gates work...
+        
         var entity = wallStyles[style][wallElement].entity;
         if (entity)
         {
@@ -960 +1054 @@
                 startY + (getDistance(startX, startY, targetX, targetY)/2)*sin(angle), // placeY
                 entity, playerId, angle - PI/2 + wallStyles[style][wallElement].angle);
         }
+        
         // Place tower
         var startX = centerX + bestPointDerivation[(pointIndex + bestPointDerivation.length - 1) % bestPointDerivation.length][0];
         var startY = centerY + bestPointDerivation[(pointIndex + bestPointDerivation.length - 1) % bestPointDerivation.length][1];