From ea74604f34226475f01b82e89cf7f8f0979b2909 Mon Sep 17 00:00:00 2001
From: Zeno Rogue <zeno@attnam.com>
Date: Mon, 29 Apr 2019 13:41:24 +0200
Subject: [PATCH] hyper.h: some extra comments

---
 hyper.h | 37 ++++++++++++++++++++++++++-----------
 1 file changed, 26 insertions(+), 11 deletions(-)

diff --git a/hyper.h b/hyper.h
index 5a976557..70c4ee6c 100644
--- a/hyper.h
+++ b/hyper.h
@@ -554,12 +554,18 @@ enum hstate { hsOrigin, hsA, hsB, hsError, hsA0, hsA1, hsB0, hsB1, hsC };
 struct cell *createMov(struct cell *c, int d);
 struct heptagon *createStep(struct heptagon *c, int d);
 
+// in bitruncated/irregular/Goldberg geometries, heptagons form the 
+// underlying regular tiling (not necessarily heptagonal); in pure
+// geometries, they correspond 1-1 to tiles; in 'masterless' geometries
+// heptagons are unused
+
 struct heptagon {
   // automaton state
   hstate s : 6;
   unsigned int dm4: 2;
   // distance from the origin
   short distance;
+  // note: all the 'val' values may have different meaning in other geometries
   // emerald/wineyard generator
   short emeraldval;
   // fifty generator
@@ -568,10 +574,12 @@ struct heptagon {
   short zebraval;
   // field id
   int fieldval;
-  // evolution data
+  // data for fractal landscapes
   short rval0, rval1;
-  struct cdata *cdata; // for alts, this contains the pointer to the original
-  // central cell
+  // for alternate structures, cdata contains the pointer to the original
+  // for the main map, it contains the fractal landscape data
+  struct cdata *cdata;
+  // central cell of this underlying tiling
   cell *c7;
   // associated generator of alternate structure, for Camelot and horocycles
   heptagon *alt;
@@ -593,14 +601,15 @@ struct heptagon {
   };
 
 struct cell : gcell {
-  char type; // 6 for hexagons, 7 for heptagons
-  int degree() { return type; }
+  char type; int degree() { return type; }
 
   // wall parameter, used for remaining power of Bonfires and Thumpers
   char wparam;
 
+  // used by celllister
   int listindex;
 
+  // heptagon who owns us; for 'masterless' tilings it contains coordinates instead
   heptagon *master;
 
   connection_table<cell> c;
@@ -656,10 +665,14 @@ inline cellwalker operator+ (heptspin hs, cth_t) { return cellwalker(hs.at->c7,
 // kill count for Graveyard/Hive
 #define R100 (inv::on ? 500 : 100)
 
-string XLAT(string x);
-string XLATN(string x);
-string cts(char c);
-string its(int i);
+string XLAT(string x);    // translate the sentence x
+string XLATN(string x);   // translate the sentence x
+string cts(char c);       // character to string
+string its(int i);        // int to string
+
+// a random integer from [0..i), generated by the game's main generator
+// we want the same world to be generated if the seed is the same. For this purpose,
+// hrand should be used for all the game-related generation, and nowhere else
 int hrand(int i);
 
 // size casted to int, to prevent warnings and actual errors caused by the unsignedness of x.size()
@@ -795,12 +808,14 @@ namespace mirror {
 int neighborId(cell *c1, cell *c2);
 
 struct movedir { 
-  int d; // 0 to 6, or one of the following -- warning: not used consistently
+  int d; 
+  // non-negative numbers denote 'rotate +d steps and act in this direction
+  // negative numbers have the following meanings (warning: not used consistently):
   #define MD_WAIT (-1)
   #define MD_DROP (-2)
   #define MD_UNDECIDED (-3)
   #define MD_USE_ORB (-4)
-  int subdir; // for normal movement (0-6): turn left or right
+  int subdir; // for normal movement (0+): turn left or right
   cell *tgt;  // for MD_USE_ORB: target cell
   };