From: Paul Hänsch <paul@plutz.net>
Date: Wed, 12 Feb 2020 19:39:36 +0000 (+0100)
Subject: proper code commenting ;-)
X-Git-Url: https://git.plutz.net/?a=commitdiff_plain;h=d11b2e0a1de035ac7b8a9bb522aa8f0b7561eaa9;p=flarejs

proper code commenting ;-)
---

diff --git a/engine.js b/engine.js
index 8f5291a..4321640 100644
--- a/engine.js
+++ b/engine.js
@@ -1,7 +1,9 @@
 var gamedata = {
+  // associative array for gamedata files
   load: def => this[def] ? this[def] : this[def] = new Textfile(def)
 }
 var gfx = {
+  // associative array for game graphics
   load: function(def) {
     if (!this[def]) {
       this[def] = document.createElement("img");
@@ -12,62 +14,85 @@ var gfx = {
 };
 
 function Textfile(txtfile) {
+  // fetch and parse gamedata file into structured object
   var lines, fetch = new XMLHttpRequest();
   fetch.open("GET", txtfile, false);
   fetch.send();
 
   var line, key, value, ref = this, section;
   for (line of fetch.responseText.split('\n')) switch(true) {
+    // section headers that always become array elements
+    case /^\[(npc|event|layer|dialog)\]$/.test(line):
+      section = line.split(/[\]\[]/)[1]; ref = {};
+      if                     (!this[section]) this[section] = [ref];
+      else if ( Array.isArray(this[section])) this[section].push(ref);
+      break;
+    // general section headers (may or may not be unique)
     case /^\[.*\]$/.test(line):
       section = line.split(/[\]\[]/)[1]; ref = {};
       if                     (!this[section]) this[section] = ref;
       else if (!Array.isArray(this[section])) this[section] = [this[section],ref];
       else if ( Array.isArray(this[section])) this[section].push(ref);
       break;
+    // frame definition from animation files
+    // frame=#frame,direction,srcX,srcY,width,height,dstX,dstY
     case /^frame=[0-9]+,[0-7](,[0-9-]+){6}$/.test(line):
       key = line.split(/[=,]/).slice(1,3);  value = line.split(/,/).slice(-6);
       if (!ref.frame) ref.frame = [];
       if (!ref.frame[key[0]]) ref.frame[key[0]] = [];
       ref.frame[key[0]][key[1]] = value.map(x => parseInt(x));
       break;
+    // order of gfx draw from engine/hero_layers.txt
+    // layer=direction,list,of,limbs,...
     case /^layer=[0-9]+,/.test(line):
       key = line.split(/[=,]/)[1];  value = line.split(/,/).slice(1);
       if (!ref.layer) ref.layer = []; ref.layer[key] = value;
       break;
+    // empty data= line starting map data in map files
     case /^data=$/.test(line):
       ref.data = [];
       break;
+    // map data array
     case /^[0-9,]+,$/.test(line):
       value = line.split(/,/).slice(0,-1);
       ref.data = ref.data.concat(value);
       break;
+    // map data array (last line)
     case /^[0-9,]+$/.test(line):
       value = line.split(/,/);
       ref.data = ref.data.concat(value);
       ref.data = ref.data.map(x => parseInt(x));
       break;
+    // tile description from tiledef file
+    // tile=#tile,srcX,srcY,width,height,dstX,dstY
     case /^tile=[0-9]+,/.test(line):
       key = line.split(/[=,]/)[1];  value = line.split(/,/).slice(1);
       if (!ref.tile) ref.tile = []; ref.tile[key] = value.map(x => parseInt(x));
       break;
+    // animated tile from tiledef file
+    // animation=#tile;(srcX,srcY,duration;)...
     case /^animation=[0-9]+;.*;$/.test(line):
       key = line.split(/[=;]/)[1];  value = line.split(/;/).slice(1,-1);
       value = value.map(x => x.split(/,/));
       value.forEach(x => x[2] = parseInt(x[2]));
       if (!ref.animation) ref.animation = []; ref.animation[key] = value;
       break;
+    // frame duration from animation file (im millisec)
     case /^duration=[0-9]+ms$/.test(line):
       ref["duration"] = line.split(/=|ms$/)[1];
       break;
+    // frame duration from animation file (in whole seconds)
     case /^duration=[0-9]+s$/.test(line):
       ref["duration"] = line.split(/=|s$/)[1] * 1000;
       break;
+    // general numeric value (key=#)
     case /^[^#].*=[0-9]+$/.test(line):
       key = line.split(/[=]/)[0];  value = line.split(/=/).slice(1) * 1;
       if                     (!ref[key]) ref[key] = value;
       else if (!Array.isArray(ref[key])) ref[key] = [ref[key],value];
       else if ( Array.isArray(ref[key])) ref[key].push(value);
       break;
+    // general key=value (non-numeric or non-scalar)
     case /^[^#].*=.+$/.test(line):
       key = line.split(/[=]/)[0];  value = line.split(/=/).slice(1).join("=");
       if                     (!ref[key]) ref[key] = value;
@@ -78,6 +103,7 @@ function Textfile(txtfile) {
 }
 
 function Map(textdef) {
+  // object for map operations (drawing coorinate transformation, etc.)
   this.info = gamedata.load(textdef);
   const tileset = gamedata.load(this.info.header.tileset);
   const frametime = performance.now();
@@ -87,31 +113,40 @@ function Map(textdef) {
   const th = this.info.header.tileheight, tw = this.info.header.tilewidth;
   var posx = canvas.canvas.width / 2, posy = canvas.canvas.height / 2 - h * th/2;
 
-  const dx = [], dy = [];  // precalculated tile positions
+  canvas.fillStyle = "rgba("+this.info.header.background_color+")";
+
+  // precalculated tile positions
+  // assign x/y coordinates to each tile index
+  // looks dumb but is faster than on the fly isometric calculations
+  const dx = [], dy = [];
   for ( let y = 0; y < h; y++ ) for ( let x = 0; x < w; x++ ) {
     dx[y * w + x] = (w + x - y) * tw / 2;
     dy[y * w + x] = (x + y) * th / 2;
   }
 
-  canvas.fillStyle = "rgba("+this.info.header.background_color+")";
-
+  // tile index for pixel position on map
   this.tileAt = function(x, y) {
     var r = (y + th / 2) / th; var c = (x - w * tw /2) / tw;
     var nx = r + c |0; var ny = r - c |0;
     return ny * w + nx;
   }
 
+  // center map to pixel position (by setting drawing offsets)
   this.center = function(x, y) {
     posx = canvas.canvas.width  / 2 - x;
     posy = canvas.canvas.height / 2 - y;
     return this;
   }
 
+  // draw the entire map, including all mobs
+  // mobs in an array of all heros, enemies, loot, npcs, etc.
   this.draw = function(mobs) {
     const bg = this.info.layer.find(l => l.type == "background").data;
     const ob = this.info.layer.find(l => l.type == "object").data;
     var x, y, i, mm = [];
 
+    // mobs only have x/y pixel positions, to draw them in order with map tiles
+    // we set up an array with current tile positions of mobs
     mobs.forEach(m => {
       let i = this.tileAt(m.position[0], m.position[1]);
       mm[i] = mobs.filter(m => i == this.tileAt(m.position[0], m.position[1]));
@@ -129,6 +164,8 @@ function Map(textdef) {
     }
   }
 
+  // draw a single map tile at screen position x/y
+  // tile may be animated, if so defined in tiledef
   function draw_tile(tile, x, y) {
     const t = tileset.tile[tile];
     const f = tileset.animation[tile];
@@ -146,6 +183,8 @@ function Map(textdef) {
 }
 
 function Mob(textdef) {
+  // any mobile object, mostly for gfx representation
+  // may be hero, enemy, loot, npc, etc.
   this.position = [0, 0];
   const info = gamedata.load(textdef);
   var direction = 0;
@@ -154,11 +193,19 @@ function Mob(textdef) {
   var frametime = performance.now();
   gfx.load(info.image)
 
+  // place mob on x/y pixel coordinates
+  // e.g. when spawning, walking, etc.
   this.place = function(x, y) {
     this.position[0] = x, this.position[1] = y;
     return this;
   }
+
+  // change facing direction of mob
   this.direct = function(d) { direction = d % 8; return this; }
+
+  // set animation cycle for drawing
+  // play_once animations will automatically fall back
+  // to previous loop after completion
   this.animate = function(a) {
     if ( a != animation ) {
       previous_animation = animation;
@@ -168,10 +215,12 @@ function Mob(textdef) {
     return this;
   }
 
+  // draw this mob to screen position x/y
   this.draw = function(x, y){
     var f, a = info[animation];
     var f, frame = ( performance.now() - frametime ) * a.frames / a.duration | 0;
 
+    // determine current animation frame
     switch(a.type){
       case "looped":
         frame = frame % a.frames;
@@ -200,6 +249,7 @@ function Mob(textdef) {
                      f[2], f[3]);
   }
 
+  // shortcut functions for specific animations
   this.block  = () => this.animate("block" );
   this.cast   = () => this.animate("cast"  );
   this.die    = () => this.animate("die"   );
@@ -211,22 +261,26 @@ function Mob(textdef) {
 }
 
 function Hero(gender = "female", hair = "short"){
+  // Object for player character
+  // unique in single player
   this.position = [0,0];
   this.stats = gamedata.load("/engine/stats.txt");
   const layers = gamedata.load("/engine/hero_layers.txt");
   var direction = 0, animation = "stance";
   hair = (gender == "female")?"long":hair;
 
+  // hero consists of multiple mobs, one for each clothing/item overlay
   var limbs = {
     head : new Mob("/animations/avatar/"+gender+"/head_"+hair+".txt"),
     chest: new Mob("/animations/avatar/"+gender+"/cloth_shirt.txt"),
     hands: new Mob("/animations/avatar/"+gender+"/default_hands.txt"),
     legs : new Mob("/animations/avatar/"+gender+"/cloth_pants.txt"),
     feet : new Mob("/animations/avatar/"+gender+"/default_feet.txt"),
-    main : null,// new Mob("/animations/avatar/"+gender+"/default_hands.txt"),
-    off  : null // new Mob("/animations/avatar/"+gender+"/default_hands.txt")
+    main : null, // main hand, e.g. melee weapon, magic weapon
+    off  : null  // off hand, e.g. shield, ranged weapon
   }
 
+  // "dress" the player, i.e. assign clothing/item to limb
   this.dress = function(limb, item) {
     limbs[limb] = new Mob("/animations/avatar/"+gender+"/"+item+".txt")
     limbs[limb].place(this.position[0], this.position[1]).direct(direction);
@@ -234,16 +288,21 @@ function Hero(gender = "female", hair = "short"){
     return this;
   }
 
+  // // Wrapper functions for Mob class // //
+
+  // place all mobs beloning to hero (when spawning, walking, teleporting, etc.)
   this.place   = function(x,y) {
     this.position[0] = x, this.position[1] = y;
     for (var limb in limbs) limbs[limb] && limbs[limb].place(x,y);
     return this;
   }
+  // change facing direction of hero (i.e. of all mobs)
   this.direct  = function(d)   {
     direction = d;
     for (var limb in limbs) limbs[limb] && limbs[limb].direct(d);
     return this;
   }
+  // start animation cycle
   this.animate = function(anim){
     animation = anim;
     for (var limb in limbs) limbs[limb] && limbs[limb].animate(anim);
@@ -254,6 +313,7 @@ function Hero(gender = "female", hair = "short"){
     return this;
   }
 
+  // shortcuts for animation
   this.block  = () => this.animate("block" );
   this.cast   = () => this.animate("cast"  );
   this.die    = () => this.animate("die"   );
@@ -265,6 +325,9 @@ function Hero(gender = "female", hair = "short"){
 }
 
 function Controls(hero, map){
+  // processes keyboard / touch / mouse
+  // causes according player actions
+  // single player only, conrol will be assigned to server in multi player
   var kbdmap = {
        up: 87,    altup: 38,
      down: 83,  altdown: 40,
@@ -278,6 +341,10 @@ function Controls(hero, map){
   window.addEventListener("keyup"  , e => keys[e.keyCode] = false);
   setInterval(() => input(), 33.33)
 
+  // cause player to walk, processes blocked terrain and player speed
+  // x/y are factors of speed and direction
+  //     i.e. +/-1 for diagonal movement
+  //     and  +/-1.4 for horizontal/vertical movement
   function translate(x, y){
     var sx = map.info.header.tilewidth  * hero.stats.speed / 33.33;
     var sy = map.info.header.tileheight * hero.stats.speed / 33.33;
@@ -300,11 +367,15 @@ function Controls(hero, map){
     map.center(hero.position[0], hero.position[1]);
   }
 
+  // process input and decide on according action
   function input(){
+    // facing directions, indexed by OR of key press combinations
     const dir   = [ -1, 0, 4, -1, 2, 1, 3, 2, 6, 7, 5, 6, -1, 0, 4, -1 ];
+    // translation speed and direction, indexed by facing direction of movement
     const trans = [ [-1.4,0], [-1,-1], [0,-1.4], [1,-1], [1.4,0], [1,1], [0,1.4], [-1,1] ];
     var k = 0;
 
+    // OR of direction key presses
     k += (keys[kbdmap.left]  || keys[kbdmap.altleft])  ? 1 : 0;
     k += (keys[kbdmap.right] || keys[kbdmap.altright]) ? 2 : 0;
     k += (keys[kbdmap.up]    || keys[kbdmap.altup])    ? 4 : 0;