Inserted and restructured some doc-strings and homogenized naming schemes

TODO

@@ -1,5 +1,14 @@
 ToDo for JSDSH:
  - Implement FrontEnd (Add Player, etc) ?
- - Implement Player, Creatures
  - Background and Wall Editing/Importing
- - Shoot, Attack
+ - Basic Modifiers
+ - on-the-fly-adding of characters
+ - traps etc.
+ - JSON instead of JavaScript importing
+ - second adventure
+ - "walking" distance (show with circle?)
+ - add avatars for players and monsters
+ - attack distance
+ - Testvalues > 20
+ - Objects: Pass object to initializer
+ - Hitbox on "things"

assets/adv01/adv01.js

@@ -1,10 +1,10 @@
 {
+    // Setup play area
     start_init(400,387);
-
-    var wall = [];
-
     Crafty.background("url('/assets/adv01/adv01_bg.jpg') 100% 0");
     
+    // Ojects get saved within an array primary for easier debugging
+    var wall = [];
     wall.push(Crafty.e("Wall").wall(0,0,150,37));
     wall.push(Crafty.e("Wall").wall(242, 0, 160,39));
     wall.push(Crafty.e("Wall").wall(130, 0, 115,11));
@@ -13,9 +13,10 @@
     wall.push(Crafty.e("Wall").wall(40, 377, 360,10));
     wall.push(Crafty.e("Wall").wall(390,0,10,387));
   
-    var cur_sel;
+    var cur_sel; // "Pointer" to current selected creature
   
     var player={};
+    /* iniitialize Players and creatures */
     player["Gesina"]=new Player({"pname":"Gesina", "cname":"Aknya", "class":"Zauberin", "level":0,
 				 "experience":0, "race":"Mensch", "size":2},
 			   {"body":6, "agility":6, "spirit":8},
@@ -41,6 +42,5 @@
 			      {"x":200,"y":80,"w":20,"h":20,"col":"red"},
 			      {"life": 8, "defense": 7, "ini":9, "walk":4.5, "melee":7, "shoot":0, "chant":0,
 			       "shoot_chant":0});
-
     end_init();
 }

index.html

@@ -14,11 +14,12 @@
       <button id="load">Load</button>
       <div id="output"></div>
     </div>
+    <!-- Include 3rd-Party Libraries -->
     <script type="text/javascript" src="lib/crafty.js"></script>
     <script type="text/javascript" src="lib/jquery-1.11.1.min.js"></script>
+    <!-- Own JS-Files -->
     <script type="text/javascript" src="src/jsds_crafty.js"></script>
     <script type="text/javascript" src="src/jsds.js"></script>
     <script type="text/javascript" src="src/base_ui.js"></script>
-    <!--    <script type="text/javascript" src="" id="adv"></script>-->
   </body>
 </html>

src/base_ui.js

@@ -1,3 +1,4 @@
+// Currently, only one Adventure is selectable
 $(document).ready( function() {
-    $('#load').click(function() { $.getScript("/assets/adv01/adv_01.js"); $('#load').hide();});
+    $('#load').click(function() { $.getScript("/assets/adv01/adv01.js"); $('#load').hide();});
 });

src/jsds.js

@@ -75,6 +75,8 @@
 	$('#ui').empty();
     };
     
+    // Probe-Function: checks, whether a given "effort" is succesfull, according to the rules of DS
+    // Not yet implemented: Tests for values larger than 20
     var dice = function(probe) {
 	var diceval = Math.floor(Math.random() * (21 - 1)) + 1;
 	if ( diceval <= probe ) {
@@ -82,23 +84,32 @@
 	}
 	else {
 	    if (diceval === 20) {
-		alert ("Patzer!");
+		alert ("Patzer!"); // We need alert here, because most "Patzer"
+		// affect gameplay (dropping equipement and so on)
 	    };
 	    return 0;
 	};
     };
 
-    // Own Classes for Creatures, etc
+    // Own Classes for Creatures, derived from the Basic Object class from above
 
+    // Creature is the base class for every "living" (or dead) "being"
     var Creature = Class.extend({
 	init: function(info,attributes,properties,drawinfo,battle){
-	    /* info: pname, cname,class, level, experience, race, size
+	    /* info cotains basic information about a Creature:
-	     * attributes: body, agility, spirit
+	     * pname (playername), experience, race, size (as a categorie)
-	     * properties: strength, hardness, movement, skill, mind, aura
+	     *
-	     * drawinfo: x,y,w,h,col
+	     * attributes are personal values that don't change very often:
+	     * body, agility and spirit
+	     *
+	     * properties may change more often, i.e. by weapon bonuses:
+	     * strength, hardness, movement, skill (in a crafty way), mind, aura
+	     *
+	     * drawinfo contains informations needed for graphical representation:
+	     * x,y,w,h,col,cx,cy (Coord. of center)
 	     */
-	    this.info = {"pname":  info["pname"]+"", "experience": info["experience"]*1, "race":info["race"]+"",
+	    this.info = {"pname":  info["pname"]+"", "experience": info["experience"]*1,
-			 "size":info["size"]*1};
+			 "race":info["race"]+"", "size":info["size"]*1}; 
 	    this.attributes = {"body": attributes["body"]*1, "agility": attributes["agility"]*1,
 			       "spirit": attributes["spirit"]*1};
 	    this.properties = {"strength": properties["strength"]*1 , "hardness": properties["hardness"]*1,
@@ -107,13 +118,18 @@
 	    this.graphelement = Crafty.e("Creature").creature(this.info["pname"],drawinfo["x"],drawinfo["y"],
 							      drawinfo["w"],drawinfo["h"],drawinfo["col"]);
 	    
+	    /* Battle-info may either be set as an argument, or need to be calculated from attributes
+	     * and properties
+	     */
 	    this.battle = {};
 	    if(battle) {
 		this.battle={"life": battle["life"]*1, "defense": battle["defense"]*1,"ini":battle["ini"]*1,
-			     "walk": battle["walk"]*1, "melee": battle["melee"]*1, "shoot": battle["shoot"]*1,
+			     "walk": battle["walk"]*1, "melee": battle["melee"]*1,
-			     "chant": battle["chant"]*1, "shoot_chant": battle["shoot_chant"]*1};
+			     "shoot": battle["shoot"]*1, "chant": battle["chant"]*1,
+			     "shoot_chant": battle["shoot_chant"]*1};
 	    }
 	    else {
+		// This is given by DS-Rules
 		this.battle["life"] = this.attributes.body + this.properties.strength + 10;;
 		this.battle["defense"] = this.attributes.body + this.properties.hardness;
 		this.battle["ini"] = this.attributes.agility + this.properties.movement;
@@ -123,11 +139,19 @@
 		this.battle["chant"] = this.attributes.spirit + this.properties.aura;
 		this.battle["shoot_chant"] = this.attributes.spirit + this.properties.skill;
 	    };
+	    /* Some special attributes: We need two "life" variables, one to have the maximum value
+	     * (the one within battle), the other to see whether a character is dead or unconscious.
+	     */
 	    this.life = this.battle["life"]*1;
+	    /* Curent attack and whether it is defendible
+	     */
 	    this.att = "melee";
 	    this.defendible = true;
 	},
 
+	/* Attack by now follows only basic rules, the gamemaster has to be sure that an attack is allowed
+	 * (distance), and that no modifier applies (distance-shot, other targets within range)
+	 */
 	attack: function(enem) {
 	    clearui();
 	    var output=$('#output');
@@ -159,6 +183,7 @@
 		};
 		output.append("Schaden: "+attack_val+"<br>");
 		enem.life -= attack_val;
+		// If an "enemie" dies, he should really die, a player-char should only get "unconcious"
 		if( enem.life <= 0 ) {
 		    if ( enem.enem ){
 			output.append(enem.info.cname + " ist besiegt<br>");
@@ -172,6 +197,7 @@
 	    }
 	},
 	
+	// The next three funcs are self-explaining
 	die: function() {
 	    this.graphelement.destroy();
 	    delete(player[this.info.pname]);
@@ -188,6 +214,8 @@
 	    }
 	},
 	
+
+	// Write out the UI for attack-selection, including binding.
 	sel_att: function() {
 	    var outstr="";
 	    outstr += "Angriffstyp?<br>";
@@ -209,13 +237,14 @@
 	    $("#"+this.att).get(0).selected="true";
 	}
     });
-	
+    
+    // Maybe the most important class in here
     var Player = Creature.extend({
 	init: function(info,attributes,properties,drawinfo,battle){ // x,y,w,h,col) {
-	    /* info: pname, cname,class, level, experience, race, size
+	    /* Additional to Creature, Player has:
-	     * attributes: body, agility, spirit
+	     * info: Charactername, Class (Human? Elve), Level
-	     * properties: strength, hardness, movement, skill, mind, aura
+	     * extern: for battle modifiers such as weapons
-	     * drawinfo: x,y,w,h,col
+	     * An info-function printing the basic informations
 	     */
 	    this._super(info,attributes,properties,drawinfo,battle);
 	    this.info["cname"]= info["cname"]+"";
@@ -242,12 +271,11 @@
     });
 	
     var Beast = Creature.extend({
-	init: function(info,attributes,properties,drawinfo,battle){ // x,y,w,h,col) {
+	init: function(info,attributes,properties,drawinfo,battle){ 
-	    /* info: pname, experience, race, size
+	    /* Additional to Creature, a Beast has:
-	     * attributes: body, agility, spirit
+	     * Cname for compability reasons in some functions, set to match pname
-	     * properties: strength, hardness, movement, skill, mind, aura
+	     * the "enem"-bool, specifying it as an enemy that really dies
-	     * drawinfo: x,y,w,h,col
+	     * A print-function as in Player
-	     * battle: life, defense,ini,walk,melee,shoot,chant,shoot_chant
 	     */
 	    
 	    this._super(info,attributes,properties,drawinfo,battle);

src/jsds_crafty.js

@@ -1,7 +1,7 @@
 {
     // For Hitbox-Dbg: Add WiredHitBox to Components of the corresponding objects,
-    // and uncomment the section in 
+    
-
+    // Basic properties of Walls (they are black, and do have a hitbox)
     Crafty.c(
 	"Wall", {
 	    init: function() {
@@ -22,6 +22,8 @@
 	}
     );
     
+    // Thing may later be used for treasuries, then it would need a hitox itself.
+    // old_pos is used for distance calculations.
     Crafty.c(
 	"Thing", {
 	    init: function() {
@@ -44,6 +46,7 @@
 	}
     );
     
+    // Creatures are players as well as monsters. They may be moved either by mouse, or by fourway-buttons.
     Crafty.c(
 	"Creature", {
 	    init: function() {
@@ -57,18 +60,30 @@
 		    .collision()
 		    .fourway(4)
 		    .onHit("coll", function(hb) {
+			/* If object hits something it shouldn't, release it from influence of mouse
+			 */
 			this.stopDrag();
 			if (hb[0].normal && (! isNaN(hb[0].overlap)) ) {
+			    /* If it ends up overlapping with oneo r several other objects,
+			     * push it back as long as necessary
+			     */
 			    do {
 				var nor=hb[0].normal;
 				var ol=hb[0].overlap;
 				this.x += Math.ceil(nor.x * -ol);
 				this.y += Math.ceil(nor.y * -ol);
 			    }
-			    while( (hb=this.hit("coll")) && (this.hit("coll")[0].normal) && (this.hit("coll")[0].overlap) );
+			    while( (hb=this.hit("coll")) && (this.hit("coll")[0].normal) && 
+				   (this.hit("coll")[0].overlap) );
 			}
 		    });
 		
+		/* Mouse-actions: 
+		 * left click: select creature, save old position, make only this creature
+		 * controllable by mouse, write output info
+		 * right click: If current selected creature, show battle menu,
+		 * otherwise just attack (by now)
+		 */
 		this.bind('MouseDown', function(e) {
 		    if(e.mouseButton === Crafty.mouseButtons.LEFT) {
 			this.old_pos["x"]=this.x;
@@ -97,6 +112,8 @@
 	}
     );
     
+    /* function for basic setup: creates canvas and small boxes that keep ojects on it
+     */
     var start_init = function(w,h) {
 	var width=w || 500;
 	var height=h|| 400;
@@ -110,6 +127,8 @@
 
     };	
 
+    /* At the end, disable mouse-control for all creatures
+     */
     var end_init = function() {
 	Crafty("Creature").each( function() {
 	    this.disableControl();