flocc 0.5.18 → 0.5.21

package/dist/flocc.es.js

@@ -372,10 +372,19 @@ function sum(arr) {
 }
 
 /**
- * Linearly interpolate between two values.
- * @param x {number} - The first value.
- * @param y {number} - The second value.
- * @param t {number} - The amount by which to interpolate (0 returns x, 1 returns y).
+ * Linearly interpolates between `x` and `y`. The third parameter `t` (usually
+ * a value between `0` and `1`) is the amount by which to interpolate — a value of `0`
+ * returns the `x` value and `1` returns the `y` value.
+ *
+ * ```js
+ * lerp(5, 10, 0.5); // returns 7.5
+ * lerp(0, 100, 0.1); // returns 10
+ * lerp(22, 79, 1); // returns 79
+ * ```
+ *
+ * @param x The first value.
+ * @param y The second value.
+ * @param t The amount by which to interpolate (0 returns x, 1 returns y).
  * @since 0.2.4
  */
 function lerp(x, y, t) {
@@ -386,7 +395,7 @@ function lerp(x, y, t) {
  * Copies the values of `source` to `arr`
  * or to a new Array.
  *
- * @private
+ * @hidden
  * @param {Array} source The Array to copy values from.
  * @param {Array} [arr=[]] The Array to copy values to.
  * @returns {Array}
@@ -403,6 +412,8 @@ function copyArray(source, arr) {
 }
 
 /**
+ * A `Vector` contains multi-dimensional numeric data.
+ *
  * @since 0.1.0
  */
 var Vector = /** @class */ (function () {
@@ -415,20 +426,40 @@ var Vector = /** @class */ (function () {
         this.dimension = data ? data.length : 0;
     }
     /**
+     * Retrieve a value from a `Vector` by its index. If the given index is greater than the
+     * `Vector`'s dimension, this returns `0` by default.
+     *
+     * ```js
+     * const v = new Vector(1, 2, 4);
+     *
+     * v.index(0); // returns 1
+     * v.index(2); // returns 4
+     * v.index(5); // returns 0
+     * ```
      * @since 0.1.0
      */
-    Vector.prototype.index = function (n) {
-        if (this.dimension > n) {
-            return this.data[n];
+    Vector.prototype.index = function (i) {
+        if (this.dimension > i) {
+            return this.data[i];
         }
         // Attempting to access index ${n} on a vector greater than the vector's dimension returns 0 by default
         return 0;
     };
     /**
-     * Overwrite the value at a given index or position. If the index is beyond the dimension of this vector,
-     * the dimension will be increased to the dimensionality implied by the index.
-     * @param i {number | string} - The numerical index (0-based) or lowercase string value ('x') to set.
-     * @param value {number} - The value to set at this index/position.
+     * Set the value at a given index. If the index is greater than the {@linkcode dimension}
+     * of this `Vector`, the dimension will be increased to the dimensionality implied by the index.
+     * @param i The numerical index (0-based) or lowercase string value (e.g. `"x"`) to set.
+     * @param value The value to set at this index/position.
+     *
+     * ```js
+     * const vector = new Vector();
+     * vector.set(0, 10);
+     * vector.set('y', 2);
+     * vector.set(2, 4);
+     *
+     * vector.xyz; // [10, 2, 4]
+     * ```
+     *
      * @since 0.1.0
      */
     Vector.prototype.set = function (i, value) {
@@ -456,128 +487,175 @@ var Vector = /** @class */ (function () {
         return this;
     };
     Object.defineProperty(Vector.prototype, "x", {
+        /** @since 0.1.0 */
         get: function () {
             return this.index(0);
         },
+        /** @since 0.1.0 */
         set: function (n) {
             this.set(0, n);
         },
-        enumerable: true,
+        enumerable: false,
         configurable: true
     });
     Object.defineProperty(Vector.prototype, "y", {
+        /** @since 0.1.0 */
         get: function () {
             return this.index(1);
         },
+        /** @since 0.1.0 */
         set: function (n) {
             this.set(1, n);
         },
-        enumerable: true,
+        enumerable: false,
         configurable: true
     });
     Object.defineProperty(Vector.prototype, "z", {
+        /** @since 0.1.0 */
         get: function () {
             return this.index(2);
         },
+        /** @since 0.1.0 */
         set: function (n) {
             this.set(2, n);
         },
-        enumerable: true,
+        enumerable: false,
         configurable: true
     });
     Object.defineProperty(Vector.prototype, "w", {
+        /** @since 0.1.0 */
         get: function () {
             return this.index(3);
         },
+        /** @since 0.1.0 */
         set: function (n) {
             this.set(3, n);
         },
-        enumerable: true,
+        enumerable: false,
         configurable: true
     });
     Object.defineProperty(Vector.prototype, "xy", {
+        /** @since 0.2.4 */
         get: function () {
             return [this.index(0), this.index(1)];
         },
-        enumerable: true,
+        enumerable: false,
         configurable: true
     });
     Object.defineProperty(Vector.prototype, "xz", {
+        /** @since 0.2.4 */
         get: function () {
             return [this.index(0), this.index(2)];
         },
-        enumerable: true,
+        enumerable: false,
         configurable: true
     });
     Object.defineProperty(Vector.prototype, "yz", {
+        /** @since 0.2.4 */
         get: function () {
             return [this.index(1), this.index(2)];
         },
-        enumerable: true,
+        enumerable: false,
         configurable: true
     });
     Object.defineProperty(Vector.prototype, "xyz", {
+        /** @since 0.2.4 */
         get: function () {
             return [this.index(0), this.index(1), this.index(2)];
         },
-        enumerable: true,
+        enumerable: false,
         configurable: true
     });
     Object.defineProperty(Vector.prototype, "r", {
+        /**
+         * `r` for 'red' (the 1st value)
+         * @since 0.1.0
+         */
         get: function () {
             return this.index(0);
         },
+        /**
+         * `r` for 'red' (the 1st value)
+         * @since 0.1.0
+         */
         set: function (n) {
             this.set(0, n);
         },
-        enumerable: true,
+        enumerable: false,
         configurable: true
     });
     Object.defineProperty(Vector.prototype, "g", {
+        /**
+         * `g` for 'green' (the 2nd value)
+         * @since 0.1.0
+         */
         get: function () {
             return this.index(1);
         },
+        /**
+         * `g` for 'green' (the 2nd value)
+         * @since 0.1.0
+         */
         set: function (n) {
             this.set(1, n);
         },
-        enumerable: true,
+        enumerable: false,
         configurable: true
     });
     Object.defineProperty(Vector.prototype, "b", {
+        /**
+         * `b` for 'blue' (the 3rd value)
+         * @since 0.1.0
+         */
         get: function () {
             return this.index(2);
         },
+        /**
+         * `b` for 'blue' (the 3rd value)
+         * @since 0.1.0
+         */
         set: function (n) {
             this.set(2, n);
         },
-        enumerable: true,
+        enumerable: false,
         configurable: true
     });
     Object.defineProperty(Vector.prototype, "a", {
+        /**
+         * `a` for 'alpha' (the 4th value)
+         * @since 0.1.0
+         */
         get: function () {
             return this.index(3);
         },
+        /**
+         * `a` for 'alpha' (the 4th value)
+         * @since 0.1.0
+         */
         set: function (n) {
             this.set(3, n);
         },
-        enumerable: true,
+        enumerable: false,
         configurable: true
     });
     Object.defineProperty(Vector.prototype, "rgb", {
+        /** @since 0.2.4 */
         get: function () {
             return [this.index(0), this.index(1), this.index(2)];
         },
-        enumerable: true,
+        enumerable: false,
         configurable: true
     });
     Object.defineProperty(Vector.prototype, "rgba", {
+        /** @since 0.2.4 */
         get: function () {
             return [this.index(0), this.index(1), this.index(2), this.index(3)];
         },
-        enumerable: true,
+        enumerable: false,
         configurable: true
     });
     /**
+     * Add another `Vector` to this `Vector`. This *does* mutate the `Vector` that calls this method.
      * @since 0.1.0
      */
     Vector.prototype.add = function (v) {
@@ -592,6 +670,17 @@ var Vector = /** @class */ (function () {
         return this;
     };
     /**
+     * Multiply this `Vector` by a scalar number. This *does* mutate the `Vector` that calls this method.
+     *
+     * ```js
+     * const v = new Vector(1, 2);
+     * v.multiplyScalar(5);
+     * v.xy; // returns [5, 10]
+     *
+     * v.multiplyScalar(-0.5);
+     * v.xy; // returns [-2.5, -5]
+     * ```
+     *
      * @since 0.1.0
      */
     Vector.prototype.multiplyScalar = function (n) {
@@ -599,6 +688,7 @@ var Vector = /** @class */ (function () {
         return this;
     };
     /**
+     * Add a scalar number to all of this `Vector`'s values'. This *does* mutate the `Vector` that calls this method.
      * @since 0.1.0
      */
     Vector.prototype.addScalar = function (n) {
@@ -613,8 +703,14 @@ var Vector = /** @class */ (function () {
         return Math.sqrt(sum(this.data.map(function (x) { return Math.pow(x, 2); })));
     };
     /**
-     * Normalize the vector (turn it into a vector with length = 1).
-     * Has no effect on the 0 vector.
+     * Normalize the `Vector` (turn it into a `Vector` with length = `1`). Has no effect on the 0 `Vector`. This *does* mutate the `Vector` that calls this method.
+     *
+     * ```js
+     * const v = new Vector(5, 3, -1);
+     * v.normalize();
+     * v.length(); // returns 1
+     * ```
+     *
      * @since 0.1.0
      */
     Vector.prototype.normalize = function () {
@@ -625,6 +721,7 @@ var Vector = /** @class */ (function () {
         return this;
     };
     /**
+     * Create a copy of this `Vector`.
      * @since 0.1.0
      */
     Vector.prototype.clone = function () {
@@ -632,8 +729,15 @@ var Vector = /** @class */ (function () {
         return new (Vector.bind.apply(Vector, __spreadArrays([void 0], data)))();
     };
     /**
-     * Rotate a vector about the Z axis.
-     * @param angle {number} - The angle by which to rotate the vector, in radians
+     * Rotate the `Vector` about the z-axis by `angle` radians (updating its `x` and `y` values). This *does* mutate the `Vector` that calls this method.
+     *
+     * ```js
+     * const v = new Vector(1, 0);
+     * v.rotateZ(Math.PI / 2); // rotate by PI / 2 radians = 90 degrees
+     *
+     * v.xy; // returns [0, 1]
+     * ```
+     *
      * @since 0.2.2
      */
     Vector.prototype.rotateZ = function (angle) {
@@ -646,8 +750,8 @@ var Vector = /** @class */ (function () {
         return this;
     };
     /**
-     * Get the dot product of this vector with another.
-     * @param {Vector} v - The other vector.
+     * Get the {@link https://en.wikipedia.org/wiki/Dot_product | dot product} of this `Vector` with another.
+     * @since 0.2.4
      */
     Vector.prototype.dot = function (v) {
         var dimension = Math.max(this.dimension, v.dimension);
@@ -657,11 +761,23 @@ var Vector = /** @class */ (function () {
         return sum;
     };
     /**
-     * Linearly interpolate between this vector and another vector.
-     * Note that this method returns a new vector and does not mutate the vector on which it is called!
-     * @param {Vector} v - The other vector.
-     * @param {number} t - The amount by which to interpolate.
+     * Linearly interpolate between this `Vector` and another `Vector`. This *does not* mutate the original `Vector` that calls this method, but returns a new `Vector`.
+     *
+     * ```js
+     * const a = new Vector(1, 3, -5);
+     * const b = new Vector(4, -2);
+     *
+     * a.lerp(b, 0); // returns a clone of Vector a
+     * a.lerp(b, 1); // returns a clone of Vector b
+     *
+     * const mid = a.lerp(b, 0.5); // returns a Vector halfway between a and b
+     * mid.xyz; // returns [2.5, 0.5, -2.5]
+     * ```
+     *
+     * @param v - The other vector.
+     * @param t - The amount by which to interpolate (usually between `0` and `1`, although it can be any number).
      * @returns {Vector} - The new, interpolated vector.
+     * @since 0.2.4
      */
     Vector.prototype.lerp = function (v, t) {
         var longerVector = this.dimension > v.dimension ? this : v;
@@ -726,16 +842,70 @@ var method = function (obj, name) {
     return obj[name].apply(obj, args);
 };
 /**
+ * The `Rule` class is an experimental interface for adding behavior to {@linkcode Agent}s. A `Rule` object may be used in place of a `tick` function to be added as `Agent` behavior using `agent.set('tick', tickRule)`. As a trivial example, consider the following `Rule`, which increments the `Agent`'s `x` value with every time step:
+ *
+ * ```js
+ * const rule = new Rule(environment, [
+ *   "set", "x", [
+ *     "add", 1, [
+ *       "get", "x"
+ *     ]
+ *   ]
+ * ]);
+ * agent.set("tick", rule);
+ * ```
+ *
+ * Reading from the outer arrays inward, the steps of this `Rule` instructs the `Agent` to:
+ * - `set` the `Agent`'s `"x"` value to...
+ *   - The result of `add`ing `1` and...
+ *     - The `Agent`'s current `"x"` value
+ *
+ * Generally, `Rule` steps are a deeply nested array, where the first value of any given array is always an instruction or operator (e.g. `"set"`, `"add"`, `"filter"`). See the {@linkcode constructor} function for more information about steps.
  * @since 0.3.0
  */
 var Rule = /** @class */ (function () {
+    /**
+     * A single step may be as simple as `["get", "x"]`. This returns the `Agent`'s `"x"` value to the outer step that contains it. So, for example, the step `["add", 1, ["get", "x"]]`, working from the inside out, retrieves the `"x"` value and then adds `1` to it. More complex steps function similarly, always traversing to the deepest nested step, evaluating it, and 'unwrapping' until all steps have been executed.
+     *
+     * A step's first element should be a string that is one of the allowed operators, followed by a certain number of arguments.
+     *
+     * |Operator|Arguments|Notes|
+     * |---|---|---|
+     * |`"add"`|`2`|Pass 2 numbers, or two steps that evaluate to numbers|
+     * |`"subtract"`|`2`|""|
+     * |`"multiply"`|`2`|""|
+     * |`"divide"`|`2`|""|
+     * |`"mod"`|`2`|""|
+     * |`"power"`|`2`|""|
+     * |`"get"`|`1`|Pass the key of `Agent` data to retrieve|
+     * |`"set"`|`2`|Pass the key and value to set|
+     * |`"enqueue"`|`2`|Pass the key and value to enqueue|
+     * |`"local"`|`2`|Pass the key and value to set as local variables|
+     * |`"if"`|`3`|Pass the conditional (usually a step that evaluates to a boolean), the step to run when `true`, and the step to run when `false|
+     * |`"and"`|`2`|Pass the two steps to logically evaluate|
+     * |`"or"`|`2`|""|
+     * |`"gt"`|`2`|""|
+     * |`"gte"`|`2`|""|
+     * |`"lt"`|`2`|""|
+     * |`"lte"`|`2`|""|
+     * |`"eq"`|`2`|""|
+     * |`"map"`|`2`|Pass an array (or step that evaluates to an array) and a lambda to invoke for each element|
+     * |`"filter"`|`2`|""|
+     * |`"key"`|`2`|Pass an object (or step that evaluates to an object) and the key to retrieve from that object|
+     * |`"agent"`|`0`|No arguments; returns the `Agent`|
+     * |`"environment"`|`0`|No arguments, returns the `Environment`|
+     * |`"vector"`|`any`|Creates an n-dimensional {@linkcode Vector} from the supplied arguments|
+     */
     function Rule(environment, steps) {
         var _this = this;
+        /** @hidden */
         this.steps = [];
+        /** @hidden */
         this.locals = {};
         /**
          * interpret single array step
          * @since 0.3.0
+         * @hidden
          */
         this.evaluate = function (agent, step) {
             var first = step && step.length > 0 ? step[0] : null;
@@ -860,6 +1030,7 @@ var Rule = /** @class */ (function () {
     }
     /**
      * @since 0.3.0
+     * @hidden
      */
     Rule.prototype.call = function (agent) {
         return this.evaluate(agent, this.steps);
@@ -915,40 +1086,85 @@ var disallowed = ["tick", "queue"];
 var warnOnce1 = once(console.warn.bind(console));
 var warnOnce2 = once(console.warn.bind(console));
 /**
+ * This class puts the `Agent` in 'agent-based modeling.' More specifically,
+ * an `Agent` represents an individual unit of data and its associated
+ * behaviors.
  * @since 0.0.5
  */
 var Agent = /** @class */ (function () {
+    /**
+     * `Agent`s can be instantiated with or without data. Instantiating
+     * with data is equivalent to creating an `Agent` and immediately
+     * calling {@linkcode Agent.set} to add data.
+     *
+     * ```js
+     * // instantiates an Agent without data
+     * const a = new Agent();
+     *
+     * // instantiates an Agent with data
+     * const b = new Agent({
+     *   x: 50,
+     *   y: 100
+     * });
+     * ```
+     * @param data
+     */
     function Agent(data) {
         if (data === void 0) { data = {}; }
         /**
-         * @member {Environment|null} environment
-         * @member {RuleObj[]} rules
-         * @member {RuleObj[]} queue
-         * @member {Object} data
+         * An `Agent` can only belong to a single {@linkcode Environment}. When
+         * `environment.addAgent(agent);` is called, this is value is updated
+         * to point to that `Environment`.
+         *
+         * ```js
+         * const environment = new Environment();
+         * const agent = new Agent();
+         * agent.environment; // returns `null`
+         *
+         * environment.addAgent(agent);
+         * agent.environment === environment; // returns `true`
          */
         this.environment = null;
+        /** @hidden */
         this.rules = [];
+        /** @hidden */
         this.queue = [];
+        /** @hidden */
         this.data = {};
+        /**
+         * `Agent`s are automatically assigned a unique ID when they are created.
+         * This can be useful when you need to refer to a specific `Agent`, and
+         * they can be retrieved using their ID from their `Environment` by calling
+         * {@link Environment.getAgentById | `environment.getAgentById(id);`}
+         * ```js
+         * const agent = new Agent();
+         * const id = agent.id; // returns "59B4F928-46C8-..." (for example)
+         * ```
+         */
         this.id = uuid$1();
-        // This is used as a temporary store for data that
-        // gets returned from rules. When enqueued rules are executed,
-        // even if there aren't any enqueued rules, .set gets called
-        // on any data that was placed here.
+        /**
+         * This is used as a temporary store for data that
+         * gets returned from rules. When enqueued rules are executed,
+         * even if there aren't any enqueued rules, .set gets called
+         * on any data that was placed here.
+         * @hidden
+         */
         this.__newData = {};
-        // When agent.get('key') is called, this pseudo-private member is set to 'key'.
-        // Once it is retrieved, it is reset to null. If agent.get('key') is called before
-        // this has been reset, that means that there is an infinite loop, and the call
-        // will throw an error.
+        /** When agent.get('key') is called, this pseudo-private member is set to 'key'.
+         * Once it is retrieved, it is reset to null. If agent.get('key') is called before
+         * this has been reset, that means that there is an infinite loop, and the call
+         * will throw an error.
+         * @hidden
+         */
         this.__retrievingData = null;
+        /** @hidden */
         this.__subtree = null;
         this.set(data);
     }
     /**
      * Set a function value. `tick` and `queue` are not automatically called,
      * but any other named value will automatically be called when referenced.
-     * @param {string} name
-     * @param {Function} fn
+     * @hidden
      */
     Agent.prototype._setFunctionValue = function (name, fn) {
         var _this = this;
@@ -964,9 +1180,8 @@ var Agent = /** @class */ (function () {
         }
     };
     /**
-     * Retrieve an arbitrary piece of data associated
-     * with this agent by name.
-     * @param {string} name
+     * Retrieve an arbitrary piece of data associated by name.
+     * If the data has not been {@linkcode set}, returns `null`.
      * @since 0.0.5
      */
     Agent.prototype.get = function (name) {
@@ -984,8 +1199,20 @@ var Agent = /** @class */ (function () {
         return data;
     };
     /**
-     * Retrieve all the data associated with this agent
-     * (useful for destructuring properties).
+     * Retrieve all the data associated with this `Agent` at once.
+     *
+     * ```js
+     * agent.set('x', 3);
+     * agent.set('color', 'blue');
+     * agent.set('active', false);
+     *
+     * agent.getData();
+     * // returns {
+     * //   x: 3,
+     * //   color: 'blue',
+     * //   active: false
+     * // }
+     * ```
      * @since 0.1.0
      */
     Agent.prototype.getData = function () {
@@ -1019,6 +1246,7 @@ var Agent = /** @class */ (function () {
     /**
      * Helper function to set key-value pair depending on whether value
      * is a function (callable) or not
+     * @hidden
      */
     Agent.prototype._setKeyValue = function (key, value) {
         if (typeof value === "function") {
@@ -1057,25 +1285,57 @@ var Agent = /** @class */ (function () {
         }
     };
     /**
-     * Increment a numeric (assume integer) piece of data
-     * associated with this agent. If `n` is included, increments by
-     * `n`. If the value has not yet been set, initializes it to 1.
-     * @param {string} name
-     * @param {number} n
+     * increment a numeric piece of data associated with this `Agent`
+     * (increasing its value by 1). This method is *synchronous* —
+     * it immediately increases the value (to *asynchronously* increase it,
+     * the rule function should instead return a new value.
+     *
+     * ```js
+     * agent.set('x', 50);
+     * agent.increment('x');
+     * agent.get('x'); // returns 51
+     * ```
+     *
+     * If the second parameter `n` is included, decrements by that amount.
+     *
+     * ```js
+     * agent.set('x', 50);
+     * agent.increment('x', 10);
+     * agent.get('x'); // returns 60
+     * ```
+     *
+     * If the value has not yet been set, calling this method sets it to `1`
+     * (or to `n`).
      * @since 0.0.8
      */
     Agent.prototype.increment = function (name, n) {
         if (n === void 0) { n = 1; }
-        if (!this.get(name))
+        if (this.get(name) === null)
             this.set(name, 0);
         this.set(name, this.get(name) + n);
     };
     /**
-     * Decrement a numeric (assume integer) piece of data
-     * associated with this agent. If `n` is included, decrements by
-     * `n`. If the value has not yet been set,
-     * initializes it to -1.
-     * @param {string} name
+     * Decrement a numeric piece of data associated with this `Agent`
+     * (decreasing its value by 1). This method is *synchronous* —
+     * it immediately decreases the value (to *asynchronously* decrease it,
+     * the rule function should instead return a new value.
+     *
+     * ```js
+     * agent.set('x', 50);
+     * agent.decrement('x');
+     * agent.get('x'); // returns 49
+     * ```
+     *
+     * If the second parameter `n` is included, decrements by that amount.
+     *
+     * ```js
+     * agent.set('x', 50);
+     * agent.decrement('x', 10);
+     * agent.get('x'); // returns 40
+     * ```
+     *
+     * If the value has not yet been set, calling this method sets it to `-1`
+     * (or to `-n`).
      * @since 0.0.8
      */
     Agent.prototype.decrement = function (name, n) {
@@ -1083,9 +1343,29 @@ var Agent = /** @class */ (function () {
         this.increment(name, -n);
     };
     /**
-     * Add a rule to be executed during the agent's
-     * environment's tick cycle. When executed, the
-     * @param {Function | Rule} rule
+     * Until v0.5.14, this was the preferred way to add behavior to `Agent`s.
+     * Now, the preferred method is by setting the `Agent`'s `"tick"` value (i.e. `agent.set({ tick: function(agt) { ... }})`).
+     * This method will still be allowed until v0.7.0.
+     *
+     * Adds a rule (a function taking an `Agent` as a callback or a {@linkcode Rule} object) that may be run with every {@linkcode Environment.tick}.
+     * It is possible to add *more than one rule* to an `Agent`, although it
+     * is generally easier to write a longer function or to break it apart
+     * into multiple functions.
+     *
+     * ```js
+     * // adds a rule that *synchronously* increments the Agent's "x" value
+     * agent.addRule(function(agt) {
+     *   agent.increment('x');
+     * });
+     *
+     * // adds a rule that *asynchronously* increments the Agent's "x" value
+     * agent.addRule(function(agt) {
+     *   return {
+     *     x: agt.get('x') + 1
+     *   };
+     * });
+     * ```
+     *
      * @deprecated since version 0.5.14
      * @since 0.0.5
      */
@@ -1101,16 +1381,34 @@ var Agent = /** @class */ (function () {
         });
     };
     /**
-     * Enqueue a function to be executed at the end of
-     * the agent's environment's tick cycle (for example,
-     * if agents in an environment should perform their
-     * calculations and updates separately). Additional/external
-     * data passed in as arguments to the enqueued function will
+     * Like {@linkcode Agent.addRule}, this method is deprecated and the
+     * recommended way is to now call
+     * `agent.set('queue', function(agt) { ... });`
+     *
+     * Calling this method enqueues a function to be executed
+     * *asynchronously* (at the end of the {@linkcode Environment}'s tick cycle).
+     * This is useful if a 'cleanup pass' should be performed between
+     * time steps to adjust `Agent` data.
+     *
+     * Below, the `Agent` sets its `"x"` value to `30` whenever it is
+     * activated during the `Environment`'s tick cycle. After all of that
+     * cycle's `Agent`s have been activated, this `Agent` sets its `"x"`
+     * value to `20`. So if any other `Agent` references its `"x"` value
+     * during a tick cycle after it has been activated, it will return `30`,
+     * but in between tick cycles it will return `20`.
+     *
+     * ```js
+     * agent.addRule(agt => {
+     *   agt.set("x", 30);
+     *   agt.enqueue(a => {
+     *     a.set("x", 20);
+     *   });
+     * });
+     * ```
+     *
+     * Any additional parameters passed to the enqueued function will
      * be remembered and passed through when the function is executed.
      *
-     * The `queue` array is cleared at the very end of
-     * the environment's tick cycle.
-     * @param {Function} enqueuedRule
      * @deprecated since version 0.5.14
      * @since 0.0.5
      */
@@ -1127,7 +1425,7 @@ var Agent = /** @class */ (function () {
     };
     /**
      * From a RuleObj, execute a single rule (function or structured Rule).
-     * @param {RuleObj} ruleObj
+     * @hidden
      */
     Agent.prototype.executeRule = function (ruleObj) {
         var rule = ruleObj.rule, args = ruleObj.args;
@@ -1142,6 +1440,7 @@ var Agent = /** @class */ (function () {
     };
     /**
      * Execute all rules.
+     * @hidden
      */
     Agent.prototype.executeRules = function () {
         var _this = this;
@@ -1158,6 +1457,7 @@ var Agent = /** @class */ (function () {
     };
     /**
      * Execute all enqueued rules.
+     * @hidden
      */
     Agent.prototype.executeEnqueuedRules = function () {
         // if new data from the rules
@@ -1187,9 +1487,15 @@ var Agent = /** @class */ (function () {
 }());
 
 /**
- * Find the mean value of an Array of numbers.
- * @param {Array<number>} arr
- * @returns {number}
+ * Return the mean value from an array of numbers.
+ *
+ * ```js
+ * mean([1, 2, 3]); // returns 2
+ * mean([10]); // returns 10
+ *
+ * mean([]); // returns null for empty arrays
+ * ```
+ *
  * @since 0.0.16
  */
 function mean(arr) {
@@ -1224,6 +1530,7 @@ function shuffle(array) {
 }
 
 /**
+ * @hidden
  * @since 0.3.11
  */
 var NumArray = /** @class */ (function () {
@@ -1235,7 +1542,7 @@ var NumArray = /** @class */ (function () {
         get: function () {
             return this._index;
         },
-        enumerable: true,
+        enumerable: false,
         configurable: true
     });
     NumArray.prototype.set = function (i, n) {
@@ -1286,24 +1593,33 @@ var Array2D = /** @class */ (function () {
 }());
 
 /**
+ * A `Network` allows {@linkcode Agent}s to be connected to each other.
  * @since 0.1.3
  */
 var Network = /** @class */ (function () {
     function Network() {
+        /** @hidden */
         this.adjacencyList = new Map();
-        // instantiated and updated in _resetAdjacencyMatrix
+        /**
+         * instantiated and updated in _resetAdjacencyMatrix
+         * @hidden
+         */
         this.adjacencyMatrix = null;
         /**
-         * list (JS array) of all the agents
-         * in the order they were added to the graph
+         * An array of the {@linkcode Agent}s in this `Network`
+         * (in the order they were added).
          */
         this.agents = [];
     }
     /**
      * Add an agent to the network.
-     * Returns `true` if the agent was successfully added.
-     * Returns `false` if the agent was already in the network.
-     * @param {Agent} agent
+     * @returns Returns `true` if the `Agent` was successfully added, `false` otherwise.
+     *
+     * ```js
+     * const a = new Agent();
+     * network.addAgent(a); // returns true
+     * network.addAgent(a); // returns false since `a` was already in the `Network`
+     * ```
      * @since 0.1.3
      */
     Network.prototype.addAgent = function (agent) {
@@ -1316,8 +1632,8 @@ var Network = /** @class */ (function () {
         return false;
     };
     /**
-     * Add all agents in an environment to this network.
-     * @param {Environment} environment
+     * Given an {@linkcode Environment}, add all the {@linkcode Agent}s in that `Environment`
+     * to this `Network`. (This is a shortcut for calling `environment.getAgents().forEach(a => network.addAgent(a)));`)
      * @since 0.2.1
      */
     Network.prototype.addFromEnvironment = function (environment) {
@@ -1325,10 +1641,20 @@ var Network = /** @class */ (function () {
         environment.getAgents().forEach(function (agent) { return _this.addAgent(agent); });
     };
     /**
-     * Remove an agent from the network.
-     * Returns `true` if the agent was successfully removed.
+     * Removes an {@linkcode Agent} from the `Network`.
+     *
+     * ```js
+     * const a = new Agent();
+     * network.addAgent(a);
+     *
+     * network.removeAgent(a); // returns true
+     *
+     * network.removeAgent(a); // returns false since `a` was no longer in the `Network`
+     * ```
+     *
+     * @returns Returns `true` if the agent was successfully removed.
+     *
      * Returns `false` if the agent was not in the network to begin with.
-     * @param {Agent} agent
      * @since 0.1.3
      */
     Network.prototype.removeAgent = function (agent) {
@@ -1348,7 +1674,17 @@ var Network = /** @class */ (function () {
         return true;
     };
     /**
-     * Removes all agents from the network.
+     * Removes all {@linkcode Agent}s from the `Network`.
+     *
+     * ```js
+     * const network = new Network();
+     * network.addAgent(new Agent());
+     * network.size(); // returns 1
+     *
+     * network.clear();
+     * network.size(); // returns 0
+     * ```
+     *
      * @since 0.2.1
      */
     Network.prototype.clear = function () {
@@ -1358,23 +1694,36 @@ var Network = /** @class */ (function () {
         }
     };
     /**
-     * Returns true if successfully connected the two agents, false otherwise
-     * (for example, if tried to add an edge between an agent + itself
-     * or if the connection already exists).
-     * @param {*} a1
-     * @param {*} a2
+     * Attempts to create a connection between {@linkcode Agent}s `a` and `b`.
+     * @returns Returns `true` if the connection was successfully created (i.e. if `a` and `b` were previously not connected and now are).
+     *
+     * ```js
+     * const a = new Agent();
+     * const b = new Agent();
+     * network.addAgent(a);
+     * network.addAgent(b);
+     *
+     * network.connect(a, b); // returns true
+     *
+     * network.connect(a, b); // returns false since they are now already connected
+     *
+     * const c = new Agent();
+     * network.connect(a, c); // returns false since `c` is not in the `Network`
+     * ```
+     *
+     * Returns `false` otherwise, for example if `a` and `b` are the same `Agent`, or if either is not in the `Network`.
      * @since 0.1.3
      */
-    Network.prototype.connect = function (a1, a2) {
-        if (a1 === a2)
+    Network.prototype.connect = function (a, b) {
+        if (a === b)
             return false;
-        if (!this.isInNetwork(a1) || !this.isInNetwork(a2))
+        if (!this.isInNetwork(a) || !this.isInNetwork(b))
             return false;
-        if (!this.areConnected(a1, a2)) {
-            this.adjacencyList.get(a1).push(a2);
-            this.adjacencyList.get(a2).push(a1);
-            var i1 = this.indexOf(a1);
-            var i2 = this.indexOf(a2);
+        if (!this.areConnected(a, b)) {
+            this.adjacencyList.get(a).push(b);
+            this.adjacencyList.get(b).push(a);
+            var i1 = this.indexOf(a);
+            var i2 = this.indexOf(b);
             this.adjacencyMatrix.set(i1, i2, 1);
             this.adjacencyMatrix.set(i2, i1, 1);
             return true;
@@ -1382,24 +1731,42 @@ var Network = /** @class */ (function () {
         return false;
     };
     /**
-     * Returns `true` if the given agents are connected in the network.
-     * @param {Agent} a1
-     * @param {Agent} a2
+     * @returns Returns `true` if {@linkcode Agent}s `a` and `b` are connected, `false` if they are not.
+     *
+     * ```js
+     * network.connect(a, b);
+     * network.areConnected(a, b); // returns true since they have been connected
+     *
+     * network.disconnect(a, b);
+     * network.areConnected(a, b); // returns false since they have been disconnected
+     * ```
+     *
      * @since 0.1.3
      */
-    Network.prototype.areConnected = function (a1, a2) {
-        if (!this.isInNetwork(a1) || !this.isInNetwork(a2))
+    Network.prototype.areConnected = function (a, b) {
+        if (!this.isInNetwork(a) || !this.isInNetwork(b))
             return false;
-        var i1 = this.indexOf(a1);
-        var i2 = this.indexOf(a2);
+        var i1 = this.indexOf(a);
+        var i2 = this.indexOf(b);
         return (this.adjacencyMatrix.get(i1, i2) === 1 &&
             this.adjacencyMatrix.get(i2, i1) === 1);
     };
     /**
-     * Like with connect, returns `true` if the edge was successfully
-     * removed, false if otherwise (if edge did not exist in the first place).
-     * @param {agent} a1
-     * @param {agent} a2
+     * Attempts to sever the connection between {@linkcode Agent}s `a` and `b`.
+     * @returns Returns `true` if the `Agent`s were successfully disconnected, `false` otherwise.
+     *
+     * ```js
+     * const a = new Agent();
+     * const b = new Agent();
+     * network.addAgent(a);
+     * network.addAgent(b);
+     *
+     * network.connect(a, b);
+     * network.disconnect(a, b); // returns true since they were connected and are no longer
+     *
+     * network.disconnect(a, b); // returns false since they were already not connected
+     * ```
+     *
      * @since 0.1.3
      */
     Network.prototype.disconnect = function (a1, a2) {
@@ -1419,40 +1786,50 @@ var Network = /** @class */ (function () {
         return false;
     };
     /**
-     * Number of agents in the network.
+     * @returns Returns the number of {@linkcode Agent}s in the `Network`.
+     *
+     * ```js
+     * const a = new Agent();
+     * const b = new Agent();
+     * const c = new Agent();
+     * [a, b, c].forEach(agt => network.addAgent(agt));
+     *
+     * network.size(); // returns 3
+     * ```
+     *
      * @since 0.1.3
      */
     Network.prototype.size = function () {
         return this.agents.length;
     };
     /**
-     * Given a callback function, loop over all the agents in the network
-     * and invoke the callback, passing the agent + its index as parameters.
-     * @param {Function} cb
+     * Loop over all the {@linkcode Agent}s in the `Network` (in the order they were added),
+     * and invoke the `callback` function with the `Agent` and an index passed as parameters.
      * @since 0.1.3
      */
-    Network.prototype.forEach = function (cb) {
-        this.agents.forEach(cb);
+    Network.prototype.forEach = function (callback) {
+        this.agents.forEach(callback);
     };
     /**
-     * Same as forEach, but in random order.
-     * @param {Function} cb
+     * The same method as {@linkcode forEach}, but executes in random order.
      * @since 0.1.3
      */
-    Network.prototype.forEachRand = function (cb) {
-        shuffle(this.agents).forEach(cb);
+    Network.prototype.forEachRand = function (callback) {
+        shuffle(this.agents).forEach(callback);
     };
     /**
-     * Returns true if the agent is in the network, false if it is not.
-     * @param {Agent} agent
+     * Returns `true` if the given {@linkcode Agent} is in the `Network`, `false` if it is not.
      * @since 0.1.3
      */
     Network.prototype.isInNetwork = function (agent) {
         return this.adjacencyList.has(agent);
     };
     /**
-     * Get the agent at index i.
-     * @param {number} i
+     * Returns the {@linkcode Agent} at index `i`, where `i = 0` is the first `Agent`
+     * added to the `Network`, `i = 1` the second, etc.
+     *
+     * Negative indices are allowed, so `network.get(-1)` returns the `Agent` that was most recently
+     * added to the `Network`, `-2` the second-most recent, etc.
      * @since 0.1.3
      */
     Network.prototype.get = function (i) {
@@ -1463,17 +1840,26 @@ var Network = /** @class */ (function () {
         return this.agents[i];
     };
     /**
-     * Get the index of a given agent.
-     * @param {Agent} agent
+     * Returns the index of the given {@linkcode Agent} in the {@linkcode agents} array.
      * @since 0.1.3
      */
     Network.prototype.indexOf = function (agent) {
         return this.agents.indexOf(agent);
     };
     /**
-     * Return the agents that are neighbors of a given agent
-     * (in a JS array). If the agent is not in the network, returns `null`.
-     * @param {Agent} agent
+     * Returns an array of {@linkcode Agent}s that are connected to the given `Agent` (in no guaranteed order).
+     *
+     * Returns `null` if the given `Agent` is not in the `Network`.
+     *
+     * ```js
+     * // suppose a, b, and c are connected
+     * network.neighbors(a); // returns [b, c] (or [c, b])
+     *
+     * network.disconnect(a, c);
+     * network.neighbors(a); // returns [b]
+     * network.neighbors(c); // returns [b]
+     * ```
+     *
      * @since 0.1.3
      */
     Network.prototype.neighbors = function (agent) {
@@ -1482,7 +1868,7 @@ var Network = /** @class */ (function () {
         return this.adjacencyList.get(agent);
     };
     /**
-     * Connect every agent in the network to every other agent.
+     * Draw a connection between every pair of {@linkcode Agent}s in the `Network`.
      * @since 0.1.3
      */
     Network.prototype.complete = function () {
@@ -1495,6 +1881,7 @@ var Network = /** @class */ (function () {
     /**
      * Internal helper function to reset the adjacencyMatrix.
      * This gets called when agents are added to or removed from the network.
+     * @hidden
      */
     Network.prototype._resetAdjacencyMatrix = function () {
         var size = this.size();
@@ -1511,11 +1898,7 @@ var Network = /** @class */ (function () {
         this.adjacencyMatrix = newMatrix;
     };
     /**
-     * Returns `true` if a, b, and c are a 'triplet' of agents --
-     * if (at least) one of the three is connected to the other two.
-     * @param {Agent} a
-     * @param {Agent} b
-     * @param {Agent} c
+     * Returns `true` if `Agent`s a, b, and c form a 'triplet' &mdash; if (at least) one of the three is connected to the other two. Returns `false` otherwise.
      * @since 0.5.17
      */
     Network.prototype.isTriplet = function (a, b, c) {
@@ -1529,11 +1912,7 @@ var Network = /** @class */ (function () {
         return connections >= 2;
     };
     /**
-     * Returns `true` if a, b, and c are a 'closed triplet' of agents --
-     * each connected to the other two.
-     * @param {Agent} a
-     * @param {Agent} b
-     * @param {Agent} c
+     * Returns `true` if `Agent`s a, b, and c form a 'closed triplet' &mdash; if each of the three are connected to the other two. Returns `false` otherwise.
      * @since 0.5.17
      */
     Network.prototype.isClosedTriplet = function (a, b, c) {
@@ -1546,6 +1925,7 @@ var Network = /** @class */ (function () {
         ].filter(function (v) { return v; }).length;
         return connections === 3;
     };
+    /** @hidden */
     Network.prototype._globalClusteringCoefficient = function () {
         var _this = this;
         var triplets = 0;
@@ -1567,12 +1947,15 @@ var Network = /** @class */ (function () {
         return closedTriplets / triplets;
     };
     /**
-     * If an agent is passed as the single parameter, returns the local
-     * clustering coefficient for that agent (a measure of how connected that
-     * agent's neighbors are to each other).
-     * If no parameter is passed, returns the global clustering coefficient
-     * of the network (an aggregate measure of how connected are the agents).
-     * @param {Agent} [agent]
+     * The {@link https://en.wikipedia.org/wiki/Clustering_coefficient | clustering coefficient} is a measure of how
+     * closely connected either an individual {@linkcode Agent}'s connections are or the `Network` as a whole is.
+     *
+     * If an `Agent` is passed as the single parameter, returns the {@link https://en.wikipedia.org/wiki/Clustering_coefficient#Local_clustering_coefficient | local
+     * clustering coefficient} for that `Agent`.
+     *
+     * If no parameter is passed, returns the {@link https://en.wikipedia.org/wiki/Clustering_coefficient#Global_clustering_coefficient | global clustering coefficient}
+     * of the `Network` (an aggregate measure of how connected the `Agent`s are).
+     *
      * @since 0.5.17
      */
     Network.prototype.clusteringCoefficient = function (agent) {
@@ -1596,9 +1979,11 @@ var Network = /** @class */ (function () {
         return (2 * clusterConnections) / (k * (k - 1));
     };
     /**
-     * Returns the average clustering coefficient for the network (the average
-     * of the local clustering coefficient across all agents). Note that
-     * this is a different measurement from the _global_ clustering coefficient.
+     * Returns the {@link https://en.wikipedia.org/wiki/Clustering_coefficient#Network_average_clustering_coefficient | average clustering coefficient} for the `Network` (the average
+     * of the {@link Network.clusteringCoefficient | local clustering coefficient} across all `Agent`s).
+     *
+     * Note that this is a different measurement from the _global_ clustering coefficient
+     * (i.e. calling {@linkcode clusteringCoefficient} without any parameters).
      * @since 0.5.17
      */
     Network.prototype.averageClusteringCoefficient = function () {
@@ -1654,6 +2039,14 @@ var BBox = /** @class */ (function () {
 }());
 
 /**
+ * Return the minimum value from an array of numbers.
+ *
+ * ```js
+ * min([1, 2, 3]); // returns 1
+ * min([10]); // returns 10
+ *
+ * min([]); // returns null for empty arrays
+ * ```
  * @since 0.2.0
  */
 function min(arr) {
@@ -1663,6 +2056,15 @@ function min(arr) {
 }
 
 /**
+ * Return the maximum value from an array of numbers.
+ *
+ * ```js
+ * max([1, 2, 3]); // returns 3
+ * max([10]); // returns 10
+ *
+ * max([]); // returns null for empty arrays
+ * ```
+ *
  * @since 0.2.0
  */
 function max(arr) {
@@ -1704,8 +2106,16 @@ function percentile(arr, n) {
 }
 
 /**
- * Find the median value of an array of numbers. If there are an even number
- * of elements in the array, takes the mean of the two values closest to the median.
+ * Return the mean value from an array of numbers.
+ *
+ * ```js
+ * median([1, 2, 3]); // returns 2
+ * median([10]); // returns 10
+ * median([1, 2, 3, 4]); // returns 2.5 (the mean of the two median values)
+ *
+ * median([]); // returns null for empty arrays
+ * ```
+ *
  * @param {number[]} arr
  * @since 0.2.0
  */
@@ -1713,6 +2123,9 @@ function median(arr) {
     return percentile(arr, 0.5);
 }
 
+function isMultipleSampleFunc(f) {
+    return f([1]).length > 0;
+}
 var sample;
 /**
  * Gets a random element from `array`.
@@ -1802,12 +2215,21 @@ function sampler(n) {
 
 /// <reference path="../types/Point.d.ts" />
 /**
- * Finds the distance between `p1` and `p2`. The inputs may be plain objects
- * with `x`, `y`, and/or `z` keys, or Agent-like objects who have
- * `x`, `y`, and/or `z` data.
- * @param {Point|Agent} p1
- * @param {Point|Agent} p2
- * @return {number} The distance between p1 and p2.
+ * Finds the distance between `p1` and `p2`.
+ *
+ * The inputs may be plain objects with `x`, `y`, and/or `z` keys, {@linkcode Vector}s,
+ * or {@linkcode Agent}s with `x`, `y`, and/or `z` data.
+ *
+ * ```js
+ * const a1 = new Agent();
+ * const a2 = new Agent({ x: 3, y: 4 });
+ * distance(a1, a2); // returns 5 (defaults to x = 0 and y = 0 for a1)
+ *
+ * const p1 = { x: 0, y: 2 };
+ * const p2 = { x: 0, y: 4 };
+ * distance(p1, p2); // returns 2
+ * ```
+ *
  * @since 0.0.10
  */
 function distance(p1, p2) {
@@ -2105,6 +2527,14 @@ var KDTree = /** @class */ (function () {
 }());
 
 /**
+ * Finds the {@link https://en.wikipedia.org/wiki/Greatest_common_divisor | greatest common divisor} of `a` and `b`.
+ *
+ * ```js
+ * gcd(7, 13); // returns 1
+ * gcd(9, 15); // returns 3
+ * gcd(12, 24); // returns 12
+ * ```
+ *
  * @since 0.4.5
  */
 function gcd(a, b) {
@@ -2173,32 +2603,80 @@ var defaultTerrainOptions = {
     grayscale: false,
     scale: 1
 };
+var BLACK = { r: 0, g: 0, b: 0, a: 255 };
+var WHITE = { r: 255, g: 255, b: 255, a: 255 };
+var RED = { r: 255, g: 0, b: 0, a: 255 };
+var MAROON = { r: 127, g: 0, b: 0, a: 255 };
+var YELLOW = { r: 255, g: 255, b: 0, a: 255 };
+var BLUE = { r: 0, g: 0, b: 255, a: 255 };
+var GREEN = { r: 0, g: 127, b: 0, a: 255 };
+var LIME = { r: 0, g: 255, b: 0, a: 255 };
+var AQUA = { r: 0, g: 255, b: 255, a: 255 };
+var ORANGE = { r: 255, g: 165, b: 0, a: 255 };
+var FUCHSIA = { r: 255, g: 0, b: 255, a: 255 };
+var PURPLE = { r: 127, g: 0, b: 127, a: 255 };
 /**
+ * Each static member of the `Colors` class (e.g. `Colors.GREEN`, `Colors.RED`) is a pixel-like object with `r`, `g`, `b`, and `a` values that range from `0` to `255`.
  * @since 0.4.0
  */
-var Colors = {
-    BLACK: { r: 0, g: 0, b: 0, a: 255 },
-    WHITE: { r: 255, g: 255, b: 255, a: 255 },
-    RED: { r: 255, g: 0, b: 0, a: 255 },
-    MAROON: { r: 127, g: 0, b: 0, a: 255 },
-    YELLOW: { r: 255, g: 255, b: 0, a: 255 },
-    BLUE: { r: 0, g: 0, b: 255, a: 255 },
-    GREEN: { r: 0, g: 127, b: 0, a: 255 },
-    LIME: { r: 0, g: 255, b: 0, a: 255 },
-    AQUA: { r: 0, g: 255, b: 255, a: 255 },
-    ORANGE: { r: 255, g: 165, b: 0, a: 255 },
-    FUCHSIA: { r: 255, g: 0, b: 255, a: 255 },
-    PURPLE: { r: 127, g: 0, b: 127, a: 255 }
-};
+var Colors = /** @class */ (function () {
+    function Colors() {
+    }
+    /** <div style="width: 100%; height: 20px; background-color: rgb(0, 0, 0);"></div> */
+    Colors.BLACK = BLACK;
+    /** <div style="width: 100%; height: 20px; background-color: rgb(255, 255, 255); border: 1px solid #eee;"></div> */
+    Colors.WHITE = WHITE;
+    /** <div style="width: 100%; height: 20px; background-color: rgb(255, 0, 0);"></div> */
+    Colors.RED = RED;
+    /** <div style="width: 100%; height: 20px; background-color: rgb(127, 0, 0);"></div> */
+    Colors.MAROON = MAROON;
+    /** <div style="width: 100%; height: 20px; background-color: rgb(255,255, 0);"></div> */
+    Colors.YELLOW = YELLOW;
+    /** <div style="width: 100%; height: 20px; background-color: rgb(0, 0, 255);"></div> */
+    Colors.BLUE = BLUE;
+    /** <div style="width: 100%; height: 20px; background-color: rgb(0, 127, 0);"></div> */
+    Colors.GREEN = GREEN;
+    /** <div style="width: 100%; height: 20px; background-color: rgb(0, 255, 0);"></div> */
+    Colors.LIME = LIME;
+    /** <div style="width: 100%; height: 20px; background-color: rgb(0, 255, 255);"></div> */
+    Colors.AQUA = AQUA;
+    /** <div style="width: 100%; height: 20px; background-color: rgb(255, 165, 0);"></div> */
+    Colors.ORANGE = ORANGE;
+    /** <div style="width: 100%; height: 20px; background-color: rgb(255, 0, 255);"></div> */
+    Colors.FUCHSIA = FUCHSIA;
+    /** <div style="width: 100%; height: 20px; background-color: rgb(127, 0, 127);"></div> */
+    Colors.PURPLE = PURPLE;
+    return Colors;
+}());
 /**
+ * The `Terrain` class lets {@linkcode Environment}s function as lattices upon which {@link https://en.wikipedia.org/wiki/Cellular_automaton | cellular automata} can grow. With a `Terrain`, {@linkcode Agent}s may not be necessary, since all the cells of a `Terrain` can follow update rules (similar to but simplified from `Agent`s).
+ *
+ * ### Usage
+ *
+ * ```js
+ * const environment = new Environment();
+ * const terrain = new Terrain(30, 30); // create a 30 x 30 Terrain
+ * environment.use(terrain); // tell the Environment to 'use' this Terrain as a helper
+ * ```
+ *
  * @since 0.4.0
  */
 var Terrain = /** @class */ (function () {
     /**
+     * Instantiate a new `Terrain` by passing its `width` and `height` as the first two parameters, and an optional configuration object as the third.
+     *
+     * ### Options
+     *
+     * - `async` (*boolean* = `false`) &mdash; Whether to run the `Terrain` in synchronous (`true`) or asynchronous (`mode`). Defaults to synchronous. Depending on the timing mode, {@link addRule | Terrain update rules} should be written differently.
+     * - `grayscale` (*boolean* = `false`)
+     *   - In **color mode** (the default), each cell of a `Terrain` is represented by a {@link Colors | pixel-like object} (an object with numeric keys `r`, `g`, `b`, and `a` ranging from 0-255).
+     *   - In **grayscale mode**, each cell of a `Terrain` is represented by a single number ranging from 0 (black) to 255 (white).
+     * - `scale` (*number* = `1`) &mdash; The size, in pixels, of each cell's width and height when the `Terrain` is rendered using a {@linkcode CanvasRenderer}. In the below screenshots, the `Terrain` on the left uses a scale of `1` while the one on the right uses a scale of `5`:
      *
-     * @param {number} width - The width of the terrain
-     * @param {number} height - The height of the terrain
-     * @param options
+     * <img alt="Terrain with scale = 1" style="width: 49%;" src="https://cms.flocc.network/wp-content/uploads/2020/04/terrain-1.png">
+     * <img alt="Terrain with scale = 5" style="width: 49%;" src="https://cms.flocc.network/wp-content/uploads/2020/04/terrain-5.png">
+     *
+     * In addition to the above setup, you will need to {@link init | initialize} the `Terrain` and {@link addRule | add an update rule}.
      */
     function Terrain(width, height, options) {
         if (options === void 0) { options = defaultTerrainOptions; }
@@ -2218,9 +2696,16 @@ var Terrain = /** @class */ (function () {
         this.nextData = new Uint8ClampedArray(this.data);
     }
     /**
-     * Initialize (or overwrite) the terrain data by passing a function with parameters (x, y)
-     * and returning a pixel value.
-     * @param {Function} rule - The rule to follow to instantiate pixel values
+     * Initialize (or overwrite) all cell values. The rule you pass has the same signature
+     * as {@linkcode addRule}, but should always return a value (either a number or {@linkcode Colors | pixel-like object}).
+     *
+     * ```js
+     * // initializes cells randomly to either blue or red
+     * terrain.init((x, y) => {
+     *   return utils.uniform() > 0.5 ? Colors.BLUE : Colors.RED;
+     * });
+     * ```
+     *
      * @since 0.4.0
      */
     Terrain.prototype.init = function (rule) {
@@ -2243,12 +2728,41 @@ var Terrain = /** @class */ (function () {
                 }
             }
         }
+        this.nextData = new Uint8ClampedArray(this.data);
     };
     /**
-     * Like with agents, this adds an update rule for the terrain. The function
-     * passed as the rule should be called with the parameters (x, y), and should return
-     * a pixel-like object { r: number, g: number, b: number, a: number } or number.
-     * @param {Function} rule - The update rule to be called on environment.tick()
+     * Similar to adding behavior to {@linkcode Agent}s, this adds an update rule for the `Terrain`.
+     * The function passed as the rule should be called with the parameters (`x`, `y`). In synchronous mode,
+     * it should return a value that is the color of that cell on the next time step.
+     *
+     * ```js
+     * // turns a cell red if the x-value is greater than 200,
+     * // blue if the x-value is less than 100,
+     * // and leaves it unchanged in between
+     * terrain.addRule((x, y) => {
+     *   if (x > 200) {
+     *     return Colors.RED;
+     *   } else if (x < 100) {
+     *     return Colors.BLUE;
+     *   }
+     * });
+     * ```
+     *
+     * For grayscale mode, functions passed to `addRule` should return a number instead of a {@linkcode Colors | pixel-like object}.
+     *
+     * In asynchronous mode, functions should use the {@linkcode set} method to update either this cell
+     * or a different cell.
+     *
+     * ```js
+     * // swaps the colors of this cell and the one five cells to the right
+     * terrain.addRule((x, y) => {
+     *   const here = terrain.sample(x, y);
+     *   const there = terrain.sample(x + 5, y);
+     *   terrain.set(x, y, there);
+     *   terrain.set(x + 5, y, here);
+     * });
+     * ```
+     *
      * @since 0.4.0
      */
     Terrain.prototype.addRule = function (rule) {
@@ -2256,14 +2770,23 @@ var Terrain = /** @class */ (function () {
     };
     /**
      * Given a local path or remote URL to an image, load that image and set
-     * terrain pixel data accordingly. This will scale the image to match the
-     * dimensionss of the terrain.
+     * `Terrain` data accordingly. This will scale the image to match the
+     * dimensions of the terrain.
+     *
      * A 2nd callback parameter fires once the image has been successfully loaded.
-     * @param {string} path - The path or URL to the image
-     * @param {Function} cb - The function to call once the image loads
+     *
+     * ```js
+     * const terrain = new Terrain(400, 400);
+     * terrain.load("/path/to/local/image.jpg", function() {
+     *   console.log("Image loaded successfully!");
+     * });
+     * ```
+     *
+     * @param {string} path - The path to or URL of the image
+     * @param {Function} cb - The function to call once the image loads (takes no parameters)
      * @since 0.4.0
      */
-    Terrain.prototype.load = function (path, cb) {
+    Terrain.prototype.load = function (path, callback) {
         var _this = this;
         var img = document.createElement("img");
         img.src = path;
@@ -2277,8 +2800,8 @@ var Terrain = /** @class */ (function () {
                 .getContext("2d")
                 .getImageData(0, 0, _this.width, _this.height).data;
             _this.data = data;
-            if (cb)
-                cb();
+            if (callback)
+                callback();
         };
         img.onerror = function () {
             console.error("There was an error loading the image for the terrain. Check the path to the URL to make sure that it exists, \n  or consider saving a local copy to pull from the same origin: https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS/Errors");
@@ -2319,16 +2842,21 @@ var Terrain = /** @class */ (function () {
         }
     };
     /**
-     * Get the neighbors of a coordinate within a certain radius.
-     * Depending on the fourth parameter, retrieves either the von Neumann neighborhood
-     * (https://en.wikipedia.org/wiki/Von_Neumann_neighborhood) or the Moore neighborhood
-     * (https://en.wikipedia.org/wiki/Moore_neighborhood).
+     * Get the values of the neighbors of a cell within a certain radius.
+     * Depending on the fourth parameter, retrieves either the {@link https://en.wikipedia.org/wiki/Von_Neumann_neighborhood | von Neumann neighborhood}
+     * or the {@link https://en.wikipedia.org/wiki/Moore_neighborhood | Moore neighborhood}.
      *
-     * @param {number} x - The x coordinate
-     * @param {number} y - The y coordinate
-     * @param {number} radius - how far to look for neighbors
-     * @param {boolean} moore - whether to use the Moore neighborhood or von Neumann (defaults to von Neumann)
-     * @returns {Pixel[] | number[]} - An array of numbers (grayscale only) or pixel-like objects
+     * ```js
+     * // in grayscale mode:
+     * terrain.neighbors(5, 5, 1); // returns [127, 100, 255, 255] (4 values)
+     *
+     * // in color mode:
+     * terrain.neighbors(5, 5, 1, true);
+     * // returns [{ r: 255, g: 0, b: 0, a: 255 }, { r: 127, ... }, ...] (8 values)
+     * ```
+     *
+     * @param moore - Defaults to using the von Neumann neighborhood.
+     * @returns Either an array of numbers (grayscale mode) or {@link Colors | pixel-like objects} (color mode).
      * @since 0.4.0
      */
     Terrain.prototype.neighbors = function (x, y, radius, moore) {
@@ -2350,6 +2878,7 @@ var Terrain = /** @class */ (function () {
         }
         return neighbors;
     };
+    /** @hidden */
     Terrain.prototype._setAbstract = function (data, x, y, r, g, b, a) {
         var _a = this, width = _a.width, height = _a.height, opts = _a.opts;
         var grayscale = opts.grayscale, scale = opts.scale;
@@ -2402,9 +2931,11 @@ var Terrain = /** @class */ (function () {
     Terrain.prototype.set = function (x, y, r, g, b, a) {
         this._setAbstract(this.data, x, y, r, g, b, a);
     };
+    /** @hidden */
     Terrain.prototype._setNext = function (x, y, r, g, b, a) {
         this._setAbstract(this.nextData, x, y, r, g, b, a);
     };
+    /** @hidden */
     Terrain.prototype._execute = function (x, y) {
         var _a = this, rule = _a.rule, opts = _a.opts;
         var async = opts.async;
@@ -2417,6 +2948,7 @@ var Terrain = /** @class */ (function () {
         // update on nextData
         this._setNext(x, y, result);
     };
+    /** @hidden */
     Terrain.prototype._loop = function (_a) {
         var _b = _a.randomizeOrder, randomizeOrder = _b === void 0 ? false : _b;
         var _c = this, rule = _c.rule, width = _c.width, height = _c.height, opts = _c.opts;
@@ -2446,52 +2978,272 @@ var Terrain = /** @class */ (function () {
     return Terrain;
 }());
 
-var defaultTickOptions = {
-    activation: "uniform",
-    count: 1,
-    randomizeOrder: false
-};
-var defaultEnvironmentOptions = {
-    torus: true,
-    height: 0,
-    width: 0
-};
-var warnOnce = once(console.warn.bind(console));
 /**
- * An environment provides the space and time in which agents interact.
- * Environments, like agents, can store data in key-value pairs
- * that can be updated over time.
+ * Given a `number` and `min` and `max` values, restrict the number
+ * to the range specified.
+ *
+ * ```js
+ * clamp(5, 1, 10); // returns 5
+ * clamp(5, 2, 4); // returns 4
+ * clamp(0, -4, -3); // returns -3
+ * ```
+ *
  * @since 0.0.5
  */
-var Environment = /** @class */ (function (_super) {
-    __extends(Environment, _super);
-    function Environment(opts) {
-        if (opts === void 0) { opts = defaultEnvironmentOptions; }
-        var _this = _super.call(this) || this;
-        /** @member {Agent[]} */
-        _this.agents = [];
-        _this.agentsById = new Map();
-        _this.cache = new Map();
-        _this.helpers = {
-            kdtree: null,
-            network: null,
-            terrain: null
-        };
-        /** @member {AbstractRenderer[]} */
-        _this.renderers = [];
-        /** @since 0.1.4 */
-        _this.time = 0;
-        _this.opts = Object.assign({}, defaultEnvironmentOptions);
-        _this.opts = Object.assign(_this.opts, opts);
-        _this.width = _this.opts.width;
-        _this.height = _this.opts.height;
-        return _this;
+function clamp(x, min, max) {
+    if (x < min)
+        return min;
+    if (x > max)
+        return max;
+    return x;
+}
+
+/**
+ * Given a mean and standard deviation,
+ * returns a value from a normal/Gaussian distribution.
+ *
+ * ```js
+ * // returns values mostly between 5 and 15 (but sometimes lower or higher)
+ * gaussian(10, 5);
+ *
+ * // no parameters defaults to mean = 0, std. dev. = 1
+ * gaussian(); // mostly values between -1 and 1
+ * ```
+ *
+ * @since 0.0.8
+ */
+function gaussian(mean, sd) {
+    if (mean === void 0) { mean = 0; }
+    if (sd === void 0) { sd = 1; }
+    var y, x1, x2, w;
+    do {
+        x1 = 2 * uniform() - 1;
+        x2 = 2 * uniform() - 1;
+        w = x1 * x1 + x2 * x2;
+    } while (w >= 1);
+    w = Math.sqrt((-2 * Math.log(w)) / w);
+    y = x1 * w;
+    return y * sd + mean;
+}
+
+/// <reference path="../types/Point.d.ts" />
+/**
+ * Finds the {@link https://en.wikipedia.org/wiki/Taxicab_geometry | Manhattan distance} between `p1` and `p2`.
+ *
+ * The inputs may be plain objects with `x`, `y`, and/or `z` keys, {@linkcode Vector}s,
+ * or {@linkcode Agent}s with `x`, `y`, and/or `z` data.
+ *
+ * ```js
+ * const a1 = new Agent();
+ * const a2 = new Agent({ x: 3, y: 4 });
+ * manhattanDistance(a1, a2); // returns 7 (defaults to x = 0 and y = 0 for a1)
+ *
+ * const p1 = { x: 3, y: 2 };
+ * const p2 = { x: 0, y: 4 };
+ * manhattanDistance(p1, p2); // returns 5
+ * ```
+ *
+ * @since 0.0.12
+ */
+function manhattanDistance(p1, p2) {
+    var x1 = (p1 instanceof Agent ? p1.get("x") : p1.x) || 0;
+    var y1 = (p1 instanceof Agent ? p1.get("y") : p1.y) || 0;
+    var z1 = (p1 instanceof Agent ? p1.get("z") : p1.z) || 0;
+    var x2 = (p2 instanceof Agent ? p2.get("x") : p2.x) || 0;
+    var y2 = (p2 instanceof Agent ? p2.get("y") : p2.y) || 0;
+    var z2 = (p2 instanceof Agent ? p2.get("z") : p2.z) || 0;
+    var dx = Math.abs(x2 - x1);
+    var dy = Math.abs(y2 - y1);
+    var dz = Math.abs(z2 - z1);
+    // distance for toroidal environments
+    if (p1 instanceof Agent &&
+        p2 instanceof Agent &&
+        p1.environment &&
+        p2.environment &&
+        p1.environment === p2.environment &&
+        p1.environment.width &&
+        p1.environment.height &&
+        p1.environment.opts.torus) {
+        var environment = p1.environment;
+        var width = environment.width, height = environment.height;
+        if (dx > width / 2)
+            dx = width - dx;
+        if (dy > height / 2)
+            dy = height - dy;
     }
+    return dx + dy + dz;
+}
+
+/**
+ * Maps a number x, from the given domain aMin --> aMax,
+ * onto the given range bMin --> bMax.
+ * Ex: remap(5, 0, 10, 0, 100) => 50.
+ * @param {number} x
+ * @param {number} aMin
+ * @param {number} aMax
+ * @param {number} bMin
+ * @param {number} bMax
+ * @returns {number} The remapped value.
+ * @since 0.0.5
+ */
+function remap(x, aMin, aMax, bMin, bMax) {
+    return bMin + ((bMax - bMin) * (x - aMin)) / (aMax - aMin);
+}
+
+/**
+ * Seed a pseudo-random number generator with a value.
+ * This can be used to produce predictable pseudo-random numbers.
+ * When calling `utils.random`, `utils.sample`, or other functions
+ * relying on randomness with the same initial seed, the values
+ * generated will always be the same.
+ *
+ * Predictable randomness can be turned off by calling `seed(null)`, or reset
+ * by calling `seed(value)` again with the initial value you used.
+ * @param value
+ * @since 0.5.0
+ */
+var seed = function (value) { return PRNG.seed(value); };
+
+/**
+ * Find the standard deviation of an Array of numbers.
+ * @param {Array<number>} arr
+ * @returns {number}
+ * @since 0.0.16
+ */
+function stdDev(arr) {
+    if (arr.length === 0)
+        return null;
+    var ave = mean(arr);
+    return Math.sqrt(mean(arr.map(function (x) { return (x - ave) * (x - ave); })));
+}
+
+/**
+ * @since 0.1.4
+ */
+function zfill(str, width) {
+    if (width === void 0) { width = 0; }
+    var output = str;
+    while (output.length < width)
+        output = "0" + output;
+    return output;
+}
+
+
+
+var utils = /*#__PURE__*/Object.freeze({
+    __proto__: null,
+    clamp: clamp,
+    distance: distance,
+    gaussian: gaussian,
+    gcd: gcd,
+    manhattanDistance: manhattanDistance,
+    lerp: lerp,
+    remap: remap,
+    random: random,
+    sample: sample$1,
+    sampler: sampler,
+    seed: seed,
+    series: series,
+    shuffle: shuffle,
+    sum: sum,
+    max: max,
+    mean: mean,
+    median: median,
+    min: min,
+    percentile: percentile,
+    stdDev: stdDev,
+    uniform: uniform,
+    uuid: uuid$1,
+    zfill: zfill
+});
+
+var defaultTickOptions = {
+    activation: "uniform",
+    activationCount: 1,
+    count: 1,
+    randomizeOrder: false
+};
+var defaultEnvironmentOptions = {
+    torus: true,
+    height: 0,
+    width: 0
+};
+var warnOnce = once(console.warn.bind(console));
+/**
+ * An environment provides the space and time in which Agents interact.
+ * Environments are themselves Agents, and can store data in key-value
+ * pairs that can be manipulated just like Agent data.
+ * @since 0.0.5
+ */
+var Environment = /** @class */ (function (_super) {
+    __extends(Environment, _super);
     /**
-     * Add an agent to the environment. Automatically sets the
-     * agent's environment to be this environment.
-     * @param {Agent} agent
-     * @param {boolean} rebalance - Whether to rebalance if there is a KDTree (defaults to true)
+     * Although `Environment`s inherit {@linkcode Agent} methods
+     * like {@linkcode Agent.set}, {@linkcode Agent.get}, etc. they have
+     * a different `constructor` signature.
+     *
+     * Pass in predefined `Environment` options for:
+     * - `torus` &mdash; Whether the `Environment` should wrap around in 2d space (with `Agent`s that move off the right reappearing on the left, off the top reappearing on the bottom, etc.)
+     * - `width` &mdash; The width of the `Environment` (used when `torus = true`)
+     * - `height` &mdash; The height of the `Environment` (used when `torus = true`)
+     * @override
+     */
+    function Environment(opts) {
+        if (opts === void 0) { opts = defaultEnvironmentOptions; }
+        var _this = _super.call(this) || this;
+        /** @hidden */
+        _this.agents = [];
+        /** @hidden */
+        _this.agentsById = new Map();
+        /** @hidden */
+        _this.environment = null;
+        /** @hidden */
+        _this.cache = new Map();
+        /** @hidden */
+        _this.helpers = {
+            kdtree: null,
+            network: null,
+            terrain: null
+        };
+        /**
+         * An array of the renderers associated with this `Environment`.
+         * An `Environment` can have multiple renderers, usually one to render
+         * the {@linkcode Agent}s spatially and others for data visualization,
+         * such as a {@linkcode LineChartRenderer}, {@linkcode Histogram}, etc.
+         */
+        _this.renderers = [];
+        /**
+         * This property will always equal the number of tick cycles that
+         * have passed since the `Environment` was created. If you call
+         * {@linkcode tick} so that it goes forward multiple time steps, it will
+         * increase the `time` by that value (not by just `1`, even though
+         * you only called `tick` once).
+         *
+         * ```js
+         * const environment = new Environment();
+         * environment.time; // returns 0
+         *
+         * environment.tick();
+         * environment.time; // returns 1
+         *
+         * environment.tick(3);
+         * environment.time; // returns 4
+         * ```
+         *
+         * @since 0.1.4
+         * */
+        _this.time = 0;
+        _this.opts = Object.assign({}, defaultEnvironmentOptions);
+        _this.opts = Object.assign(_this.opts, opts);
+        _this.width = _this.opts.width;
+        _this.height = _this.opts.height;
+        return _this;
+    }
+    /**
+     * Add an {@linkcode Agent} to this `Environment`. Once this is called,
+     * the `Agent`'s {@link Agent.environment | `environment`} property
+     * will automatically be set to this `Environment`.
+     * @param rebalance - Whether to rebalance if there is a `KDTree` (defaults to true)
      * @since 0.0.5
      */
     Environment.prototype.addAgent = function (agent, rebalance) {
@@ -2553,7 +3305,7 @@ var Environment = /** @class */ (function (_super) {
         return this.agentsById.get(id) || null;
     };
     /**
-     * Removes all agents from the environment.
+     * Remove all agents from the environment.
      * @since 0.1.3
      */
     Environment.prototype.clear = function () {
@@ -2563,64 +3315,132 @@ var Environment = /** @class */ (function (_super) {
         }
     };
     /**
-     * From the parameter passed to .tick, get a structured TickOptions object.
-     * @param {number | TickOptions} opts
+     * From the parameter passed to {@linkcode Environment.tick}, get a structured TickOptions object.
+     * @hidden
      */
     Environment.prototype._getTickOptions = function (opts) {
-        var count = defaultTickOptions.count, randomizeOrder = defaultTickOptions.randomizeOrder;
+        var baseOpts = Object.assign({}, defaultTickOptions);
         if (typeof opts === "number") {
-            count = opts;
+            baseOpts.count = opts;
         }
         else if (!!opts) {
-            count = opts.count || 1;
-        }
-        if (opts &&
-            typeof opts !== "number" &&
-            opts.hasOwnProperty("randomizeOrder")) {
-            randomizeOrder = opts.randomizeOrder;
+            Object.assign(baseOpts, opts);
         }
-        else if (opts === undefined ||
+        if (opts === undefined ||
             (typeof opts !== "number" && !opts.hasOwnProperty("randomizeOrder"))) {
             warnOnce("You called `environment.tick` without specifying a `randomizeOrder` option. Currently this defaults to `false` (i.e. each agent ticks in the order it was added to the environment). However, in **Flocc 0.6.0 this will default to `true`** — agent activation order will default to being randomized.");
         }
-        return { count: count, randomizeOrder: randomizeOrder };
+        return baseOpts;
     };
     /**
-     * Execute all agent rules.
-     * @param { boolean } randomizeOrder
+     * For all agents passed, execute agent rules
+     * @hidden
      */
-    Environment.prototype._executeAgentRules = function (randomizeOrder) {
-        (randomizeOrder ? shuffle(this.agents) : this.agents).forEach(function (agent) {
-            return agent.executeRules();
-        });
+    Environment.prototype._executeAgentRules = function (agents) {
+        agents.forEach(function (agent) { return agent === null || agent === void 0 ? void 0 : agent.executeRules(); });
     };
     /**
-     * Execute all enqueued agent rules.
-     * @param { boolean } randomizeOrder
+     * For all agents passed, execute enqueued agent rules
+     * @hidden
      */
-    Environment.prototype._executeEnqueuedAgentRules = function (randomizeOrder) {
-        (randomizeOrder ? shuffle(this.agents) : this.agents).forEach(function (agent) {
-            return agent.executeEnqueuedRules();
-        });
+    Environment.prototype._executeEnqueuedAgentRules = function (agents) {
+        agents.forEach(function (agent) { return agent === null || agent === void 0 ? void 0 : agent.executeEnqueuedRules(); });
     };
     /**
-     * Moves the environment forward in time,
-     * executing all agent's rules sequentially, followed by
-     * any enqueued rules (which are removed with every tick).
-     * Can take either a number or a configuration object as a parameter.
-     * If a number, the environment will tick forward that many times.
-     * @param {number | TickOptions} opts
+     * Runs the `Environment`s tick cycle. Depending on the parameters, one,
+     * some, or all of the {@linkcode Agent}s in the `Environment`
+     * might be activated, and all renderers associated with the
+     * `Environment` will update. After the tick cycle finishes, any rules that were enqueued will be run and the `Environment`'s {@linkcode time} property will have incremented.
+     *
+     * ```js
+     * environment.tick(); // ticks once
+     *
+     * // To run multiple tick cycles, you can pass a number
+     * environment.tick(5); // ticks 5 times
+     * ```
+     *
+     * Passing a configuration object (instead of a number) allows
+     * you to have finer control over the tick cycle. The object can
+     * have the following keys:
+     * - `activation`: Either `"uniform"` or `"random"` (defaults to `"uniform"`).
+     *   - `activation = "uniform"` &mdash; All `Agent`s in the `Environment` are activated with every tick cycle.
+     *   - `activation = "random"` &mdash; One or more `Agent`s are randomly selected to be activated every tick cycle (see `activationCount` below).
+     * - `activationCount`: For `"random"` activation, this many `Agent`s will be activated with each tick cycle. Defaults to `1`. If `activationCount` is greater than the number of `Agent`s in the `Environment`, then all the `Agent`s will be activated exactly once in random order.
+     * - `count`: The number of tick cycles to run.
+     * - `randomizeOrder`: When `activation = "uniform"`, if `randomizeOrder = true`, `Agent`s will be activated in random order, otherwise in the order they were added to the `Environment`. **This currently defaults to `false` but will default to `true` in v0.6.0.**
+     *
+     * ```js
+     * // Ticks three times, activating 10 random agents with each tick cycle.
+     * environment.tick({
+     *   activation: "random",
+     *   activationCount: 10,
+     *   count: 3
+     * });
+     * ```
+     *
      * @since 0.0.5
      */
     Environment.prototype.tick = function (opts) {
-        var _a = this._getTickOptions(opts), count = _a.count, randomizeOrder = _a.randomizeOrder;
-        this._executeAgentRules(randomizeOrder);
-        this._executeEnqueuedAgentRules(randomizeOrder);
+        var _a = this._getTickOptions(opts), activation = _a.activation, activationCount = _a.activationCount, count = _a.count, randomizeOrder = _a.randomizeOrder;
+        // for uniform activation, every agent is always activated
+        if (activation === "uniform") {
+            var agentsInOrder = randomizeOrder ? shuffle(this.agents) : this.agents;
+            this._executeAgentRules(agentsInOrder);
+            this._executeEnqueuedAgentRules(agentsInOrder);
+        }
+        // for random activation, the number of agents activated
+        // per tick is determined by the `activationCount` option
+        else if (activation === "random") {
+            if (activationCount === 1) {
+                var agent = sample$1(this.agents);
+                if (agent !== null) {
+                    agent.executeRules();
+                    agent.executeEnqueuedRules();
+                }
+            }
+            else if (activationCount > 1) {
+                var sampleCount = sampler(activationCount);
+                // this safety check should always return `true`
+                if (isMultipleSampleFunc(sampleCount)) {
+                    var agents = sampleCount(this.getAgents());
+                    this._executeAgentRules(agents);
+                    this._executeEnqueuedAgentRules(agents);
+                }
+            }
+            else {
+                warnOnce("You passed a zero or negative `activationCount` to the Environment's tick options. No agents will be activated.");
+            }
+        }
         if (this.helpers.kdtree)
             this.helpers.kdtree.rebalance();
         var terrain = this.helpers.terrain;
-        if (terrain && terrain.rule)
-            terrain._loop({ randomizeOrder: randomizeOrder });
+        if (terrain && terrain.rule) {
+            if (activation === "uniform") {
+                terrain._loop({ randomizeOrder: randomizeOrder });
+            }
+            else if (activation === "random") {
+                if (activationCount === 1) {
+                    var x = random(0, terrain.width);
+                    var y = random(0, terrain.height);
+                    terrain._execute(x, y);
+                }
+                else if (activationCount > 1) {
+                    var generator = series(terrain.width * terrain.height);
+                    var indices = [];
+                    while (indices.length < activationCount) {
+                        var index = generator.next().value;
+                        var x = index % terrain.width;
+                        var y = (index / terrain.width) | 0;
+                        terrain._execute(x, y);
+                        indices.push(index);
+                    }
+                }
+                // in synchronous mode, write the buffer to the data
+                if (!terrain.opts.async) {
+                    terrain.data = new Uint8ClampedArray(terrain.nextData);
+                }
+            }
+        }
         this.time++;
         if (count > 1) {
             this.tick(count - 1);
@@ -2629,26 +3449,41 @@ var Environment = /** @class */ (function (_super) {
         this.renderers.forEach(function (r) { return r.render(); });
     };
     /**
-     * Use a helper with this environment.
-     * @param {EnvironmentHelper} e
+     * Use a helper with this environment. A helper can be one of:
+     * - {@linkcode KDTree}
+     * - {@linkcode Network}
+     * - {@linkcode Terrain}
      * @since 0.1.3
      */
-    Environment.prototype.use = function (e) {
-        if (e instanceof KDTree)
-            this.helpers.kdtree = e;
-        if (e instanceof Network)
-            this.helpers.network = e;
-        if (e instanceof Terrain)
-            this.helpers.terrain = e;
+    Environment.prototype.use = function (helper) {
+        if (helper instanceof KDTree)
+            this.helpers.kdtree = helper;
+        if (helper instanceof Network)
+            this.helpers.network = helper;
+        if (helper instanceof Terrain)
+            this.helpers.terrain = helper;
     };
     /**
      * Get an array of data associated with agents in the environment by key.
-     * Equivalent to calling `environment.getAgents().map(agent => agent.get(key));`
-     * Defaults to calculating and storing the result within the same environment tick.
-     * If the 2nd parameter is set to `false`, will recalculate and return the result every time.
-     * @param {string} key - The key for which to retrieve data.
-     * @param {boolean} useCache - Whether or not to cache the result (defaults to true).
-     * @return {any[]} Array of data associated with `agent.get(key)` across all agents.
+     * Calling `environment.stat('name')` is equivalent to calling
+     * `environment.getAgents().map(agent => agent.get('name'));`
+     *
+     * By default, calling this will calculate the result at most once
+     * per time cycle, and return the cached value on subsequent calls (until
+     * the next time cycle, when it will recalculate).
+     *
+     * @param key - The key for which to retrieve data.
+     * @param useCache - Whether or not to cache the result.
+     * @returns Array of data associated with `agent.get(key)` across all agents.
+     *
+     * ```js
+     * environment.addAgent(new Agent({ name: "Alice" }));
+     * environment.addAgent(new Agent({ name: "Bob" }));
+     * environment.addAgent(new Agent({ name: "Chaz" }));
+     *
+     * environment.stat('name'); // returns ['Alice', 'Bob', 'Chaz']
+     * ```
+     *
      * @since 0.3.14
      */
     Environment.prototype.stat = function (key, useCache) {
@@ -2669,9 +3504,17 @@ var Environment = /** @class */ (function (_super) {
     };
     /**
      * Pass a function to cache and use the return value within the same environment tick.
-     * @param {Function} fn - The function to memoize.
-     * @return {any} The return value of the function that was passed.
+     * @param fn - The function to memoize.
+     * @return The return value of the function that was passed.
      * @since 0.3.14
+     *
+     * ```js
+     * // Within the same time cycle, this function will only be called once.
+     * // The cached value will be used on subsequent calls.
+     * const blueAgents = environment.memo(() => {
+     *   return environment.getAgents().filter(a => a.get('color') === 'blue');
+     * });
+     * ```
      */
     Environment.prototype.memo = function (fn, key) {
         var serialized = (key ? key + "-" : "") + fn.toString();
@@ -2712,10 +3555,21 @@ var unhash = function (str) {
 };
 var warnOnce$1 = once(console.warn.bind(console));
 /**
- * @since 0.0.5
+ * A `GridEnvironment` is the **deprecated** version of a cellular automata.
+ * It's now recommended that you use a standard {@linkcode Environment} with a
+ * {@linkcode Terrain}. This class will be removed entirely in v0.6.0.
+ *
+ * In a `GridEnvironment` with an {@linkcode ASCIIRenderer}, {@linkcode Agent}s are rendered
+ * using their `"value"` data (a single character).
+ *
+ * @deprecated since 0.4.0
+ * @since 0.0.10
  */
 var GridEnvironment = /** @class */ (function (_super) {
     __extends(GridEnvironment, _super);
+    /**
+     * Create a `GridEnvironment` with the given `width` and `height`.
+     */
     function GridEnvironment(width, height) {
         if (width === void 0) { width = 2; }
         if (height === void 0) { height = 2; }
@@ -2750,6 +3604,7 @@ var GridEnvironment = /** @class */ (function (_super) {
         }
     };
     /**
+     * @hidden
      * @since 0.1.0
      */
     GridEnvironment.prototype.normalize = function (x, y) {
@@ -2764,7 +3619,7 @@ var GridEnvironment = /** @class */ (function (_super) {
         return { x: x, y: y };
     };
     /**
-     * For GridEnvironments, `addAgent` takes `x` and `y` values
+     * For `GridEnvironment`s, `addAgent` takes `x` and `y` values
      * and automatically adds a Agent to that cell coordinate.
      * @param {number} x_
      * @param {number} y_
@@ -2793,8 +3648,8 @@ var GridEnvironment = /** @class */ (function (_super) {
         return agent;
     };
     /**
-     * For GridEnvironments, `removeAgent` takes `x` and `y` values
-     * and removes the Agent (if there is one) at that cell coordinate.
+     * For GridEnvironments, `removeAgentAt` takes `x` and `y` values
+     * and removes the `Agent` (if there is one) at that cell coordinate.
      * @param {number} x_
      * @param {number} y_
      * @since 0.1.0
@@ -2957,6 +3812,7 @@ var GridEnvironment = /** @class */ (function (_super) {
     };
     /**
      * Execute all cell rules.
+     * @hidden
      * @param { boolean } randomizeOrder
      */
     GridEnvironment.prototype._executeCellRules = function (randomizeOrder) {
@@ -2983,6 +3839,7 @@ var GridEnvironment = /** @class */ (function (_super) {
     };
     /**
      * Execute all enqueued cell rules.
+     * @hidden
      * @param { boolean } randomizeOrder
      */
     GridEnvironment.prototype._executeEnqueuedCellRules = function (randomizeOrder) {
@@ -3008,8 +3865,8 @@ var GridEnvironment = /** @class */ (function (_super) {
         }
     };
     /**
-     * Override/extend Environment.tick to include the
-     * GridEnvironment's cells.
+     * Override/extend {@linkcode Environment.tick} to include the
+     * `GridEnvironment`'s cells.
      * @override
      * @param {number} opts
      */
@@ -3018,11 +3875,11 @@ var GridEnvironment = /** @class */ (function (_super) {
         // execute all cell rules
         this._executeCellRules(randomizeOrder);
         // execute all agent rules
-        this._executeAgentRules(randomizeOrder);
+        this._executeAgentRules(randomizeOrder ? shuffle(this.agents) : this.agents);
         // execute all enqueued cell rules
         this._executeEnqueuedCellRules(randomizeOrder);
         // execute all enqueued agent rules
-        this._executeEnqueuedAgentRules(randomizeOrder);
+        this._executeEnqueuedAgentRules(randomizeOrder ? shuffle(this.agents) : this.agents);
         this.time++;
         if (count > 1) {
             this.tick(count - 1);
@@ -3035,13 +3892,24 @@ var GridEnvironment = /** @class */ (function (_super) {
 
 var AbstractRenderer = /** @class */ (function () {
     function AbstractRenderer() {
+        /** @hidden */
         this.canvas = document.createElement("canvas");
+        /** @hidden */
         this.context = this.canvas.getContext("2d");
     }
     AbstractRenderer.prototype.render = function () { };
     /**
      * Mount this renderer to a DOM element. Pass either a string representing a
-     * CSS selector matching the element (i.e. `"#element-id") or the element itself.
+     * CSS selector matching the element or the element itself.
+     *
+     * ```js
+     * // mounts the renderer to the element with the ID `container`
+     * renderer.mount('#container');
+     *
+     * // mounts the renderer to the element itself
+     * const container = document.getElementById('container');
+     * renderer.mount(container);
+     * ```
      * @param {string | HTMLElement} el
      */
     AbstractRenderer.prototype.mount = function (el) {
@@ -3056,11 +3924,25 @@ var AbstractRenderer = /** @class */ (function () {
 
 var warnOnce$2 = once(console.warn.bind(console));
 /**
+ * An `ASCIIRenderer` renders the {@link Agent | `Agent`}s in
+ * a {@linkcode GridEnvironment}. `Agent`s are rendered
+ * using their `"value"` data (a single character).
+ * Since v0.4.0, this class has been **deprecated**, and it will be removed
+ * entirely in v0.6.0.
+ * ```js
+ * const renderer = new ASCIIRenderer(grid);
+ * renderer.mount("#container-id");
+ * ```
+ * @deprecated since 0.4.0
  * @since 0.0.10
  */
 var ASCIIRenderer = /** @class */ (function (_super) {
     __extends(ASCIIRenderer, _super);
-    function ASCIIRenderer(environment, opts) {
+    /**
+     * Create a new `ASCIIRenderer` by passing in the
+     * {@linkcode GridEnvironment} you want to be rendered.
+     */
+    function ASCIIRenderer(environment) {
         var _this = _super.call(this) || this;
         warnOnce$2("As of Flocc v0.5.0, ASCIIEnvironment is **DEPRECATED**. It will be **REMOVED** in v0.6.0. The Terrain helper should be used for 2-dimensional grid-like data, with CanvasRenderer to visualize. Read more about Terrains here: https://flocc.network/docs/terrain");
         _this.environment = environment;
@@ -3069,6 +3951,7 @@ var ASCIIRenderer = /** @class */ (function (_super) {
         return _this;
     }
     /**
+     * Renders the contents of the `ASCIIRenderer`'s {@linkcode GridEnvironment}.
      * @since 0.0.10
      */
     ASCIIRenderer.prototype.render = function () {
@@ -3104,12 +3987,46 @@ var defaultOptions = {
     trace: false
 };
 /**
+ * A `CanvasRenderer` renders an {@linkcode Environment} spatially in two dimensions.
+ * Importantly, it expects that all {@linkcode Agent}s in the `Environment`
+ * have numeric `"x"` and `"y"` values associated with them.
+ *
+ * `CanvasRenderer`s will render all `Agent`s that are visible in the rendered `Environment` space,
+ * with the color of their `"color"` value (defaulting to black).
+ * Depending on the `"shape"` of the `Agent`, additional data might be needed. `Agent` `"shape"`s can be:
+ * - `"circle"` (default) &mdash; Draws a circle centered at the `Agent`'s `"x"` / `"y"` values.
+ *   - If the `Agent` has a `"size"` value, uses that for the circle radius (defaults to 1px).
+ * - `"arrow"` &mdash; Draws an arrow centered at the `Agent`'s `"x"` / `"y"` values.
+ *   - The arrow will point in the direction of the `Agent`s `"vx"` / `"vy"` values. For example, an `Agent` with `"vx" = 1` and `"vy" = 0` will be rendered as an arrow pointing to the right.
+ *   - Also uses the `"size" value.
+ * - `"rect"` &mdash; Draws a rectangle with the upper-left corner at `"x"` / `"y"`.
+ *   - Uses the `Agent`'s `"width"` and `"height"` values for the dimensions of the rectangle.
+ * - `"triangle"` &mdash; Draws a triangle centered at the `Agent`'s `"x"` / `"y"` values.
+ *   - Also uses the `"size"` value.
+ *
  * @since 0.0.11
  */
 var CanvasRenderer = /** @class */ (function (_super) {
     __extends(CanvasRenderer, _super);
+    /**
+     * The first parameter must be the {@linkcode Environment} that this
+     * `CanvasRenderer` will render.
+     *
+     * The second parameter specifies options, which can include:
+     * - `autoPosition` (*boolean* = `false`) &mdash; For `Environment`s using a {@linkcode Network}, whether to automatically position the `Agent`s.
+     * - `background` (*string* = `"transparent"`) &mdash; The background color to draw before rendering any `Agent`s.
+     * - `connectionColor` (*string* = `"black"`) &mdash; For `Environment`s using a `Network`, the color of lines
+     * - `connectionOpacity` (*number* = `1`) &mdash; For `Environment`s using a `Network`, the opacity of lines
+     * - `connectionWidth` (*number* = `1`) &mdash; For `Environment`s using a `Network`, the width of lines
+     * - `height` (*number* = `500`) &mdash; The height, in pixels, of the canvas on which to render
+     * - `origin` (*{ x: number; y: number }* = `{ x: 0, y: 0 }`) &mdash; The coordinate of the upper-left point of the space to be rendered
+     * - `scale` (*number* = `1`) &mdash; The scale at which to render (the larger the scale, the smaller the size of the space that is actually rendered)
+     * - `trace` (*boolean* = `false`) &mdash; If `true`, the renderer will not clear old drawings, causing the `Agent`s to appear to *trace* their paths across space
+     * - `width` (*number* = `500`) &mdash; The width, in pixels, of the canvas on which to render
+     */
     function CanvasRenderer(environment, opts) {
         var _this = _super.call(this) || this;
+        /** @hidden */
         _this.terrainBuffer = document.createElement("canvas");
         _this.environment = environment;
         environment.renderers.push(_this);
@@ -3130,14 +4047,17 @@ var CanvasRenderer = /** @class */ (function (_super) {
         _this.context.fillRect(0, 0, width, height);
         return _this;
     }
+    /** @hidden */
     CanvasRenderer.prototype.x = function (v) {
         var _a = this.opts, origin = _a.origin, scale = _a.scale;
         return window.devicePixelRatio * scale * (v - origin.x);
     };
+    /** @hidden */
     CanvasRenderer.prototype.y = function (v) {
         var _a = this.opts, origin = _a.origin, scale = _a.scale;
         return window.devicePixelRatio * scale * (v - origin.y);
     };
+    /** @hidden */
     CanvasRenderer.prototype.createCanvas = function () {
         var dpr = window.devicePixelRatio;
         var _a = this.opts, width = _a.width, height = _a.height;
@@ -3146,6 +4066,117 @@ var CanvasRenderer = /** @class */ (function (_super) {
         canvas.height = height * dpr;
         return canvas;
     };
+    /** @hidden */
+    CanvasRenderer.prototype.drawPath = function (points, dx, dy) {
+        if (dx === void 0) { dx = 0; }
+        if (dy === void 0) { dy = 0; }
+        var bufferContext = this.buffer.getContext("2d");
+        points.forEach(function (_a, i) {
+            var px = _a[0], py = _a[1];
+            if (i === 0) {
+                bufferContext.moveTo(px + dx, py + dy);
+            }
+            else {
+                bufferContext.lineTo(px + dx, py + dy);
+            }
+        });
+    };
+    /** @hidden */
+    CanvasRenderer.prototype.drawPathWrap = function (points) {
+        var _this = this;
+        var _a = this, width = _a.width, height = _a.height;
+        var right = false;
+        var left = false;
+        var lower = false;
+        var upper = false;
+        points.forEach(function (_a) {
+            var px = _a[0], py = _a[1];
+            if (_this.x(px) >= width)
+                right = true;
+            if (_this.x(px) < 0)
+                left = true;
+            if (_this.y(py) >= height)
+                lower = true;
+            if (_this.y(py) < 0)
+                upper = true;
+        });
+        if (right)
+            this.drawPath(points, -width, 0);
+        if (left)
+            this.drawPath(points, width, 0);
+        if (lower && right)
+            this.drawPath(points, -width, -height);
+        if (upper && right)
+            this.drawPath(points, -width, height);
+        if (lower && left)
+            this.drawPath(points, width, -height);
+        if (upper && left)
+            this.drawPath(points, width, height);
+        if (lower)
+            this.drawPath(points, 0, -height);
+        if (upper)
+            this.drawPath(points, 0, height);
+    };
+    /** @hidden */
+    CanvasRenderer.prototype.drawCircle = function (x, y, r) {
+        var bufferContext = this.buffer.getContext("2d");
+        bufferContext.moveTo(this.x(x), this.y(y));
+        bufferContext.arc(this.x(x), this.y(y), r, 0, 2 * Math.PI);
+    };
+    /** @hidden */
+    CanvasRenderer.prototype.drawCircleWrap = function (x, y, size) {
+        var _a = this, width = _a.width, height = _a.height;
+        if (this.x(x + size) >= width) {
+            this.drawCircle(x - width, y, size);
+            if (this.y(y + size) >= height)
+                this.drawCircle(x - width, y - height, size);
+            if (this.y(y - size) < 0)
+                this.drawCircle(x - width, y + height, size);
+        }
+        if (this.x(x - size) < 0) {
+            this.drawCircle(x + width, y, size);
+            if (this.y(y + size) >= height)
+                this.drawCircle(x + width, y - height, size);
+            if (this.y(y - size) < 0)
+                this.drawCircle(x + width, y + height, size);
+        }
+        if (this.y(y + size) > height)
+            this.drawCircle(x, y - height, size);
+        if (this.y(y - size) < 0)
+            this.drawCircle(x, y + height, size);
+    };
+    /**
+     * Draw a rectangle centered at (x, y). Automatically calculates the offset
+     * for both width and height.
+     * @hidden
+     */
+    CanvasRenderer.prototype.drawRect = function (x, y, width, height) {
+        var bufferContext = this.buffer.getContext("2d");
+        var dpr = window.devicePixelRatio;
+        bufferContext.fillRect(this.x(x) - (width * dpr) / 2, this.y(y) - (height * dpr) / 2, width * dpr, height * dpr);
+    };
+    /** @hidden */
+    CanvasRenderer.prototype.drawRectWrap = function (x, y, w, h) {
+        var _a = this.opts, width = _a.width, height = _a.height;
+        if (this.x(x + w / 2) >= width) {
+            this.drawRect(x - width, y, w, h);
+            if (this.y(y + h / 2) >= height)
+                this.drawRect(x - width, y - height, w, h);
+            if (this.y(y - height / 2) < 0)
+                this.drawRect(x - width, y + height, w, h);
+        }
+        if (this.x(x - w / 2) < 0) {
+            this.drawRect(x + width, y, w, h);
+            if (this.y(y + h / 2) >= height)
+                this.drawRect(x + width, y - height, w, h);
+            if (this.y(y - height / 2) < 0)
+                this.drawRect(x + width, y + height, w, h);
+        }
+        if (this.y(y + h / 2) > height)
+            this.drawRect(x, y - height, w, h);
+        if (this.y(y - height / 2) < 0)
+            this.drawRect(x, y + height, w, h);
+    };
     CanvasRenderer.prototype.render = function () {
         var _this = this;
         var _a = this, buffer = _a.buffer, context = _a.context, environment = _a.environment, width = _a.width, height = _a.height, opts = _a.opts, terrainBuffer = _a.terrainBuffer;
@@ -3233,28 +4264,36 @@ var CanvasRenderer = /** @class */ (function (_super) {
                 var _vx = 3 * size * (vx / norm) * dpr;
                 var _vy = 3 * size * (vy / norm) * dpr;
                 bufferContext.beginPath();
-                bufferContext.save();
-                bufferContext.translate(_this.x(x), _this.y(y));
-                bufferContext.moveTo(1.5 * _vx, 1.5 * _vy);
-                bufferContext.lineTo(_vy / 2, -_vx / 2);
-                bufferContext.lineTo(-_vy / 2, _vx / 2);
-                bufferContext.restore();
+                var points = [
+                    [_this.x(x) + 1.5 * _vx, _this.y(y) + 1.5 * _vy],
+                    [_this.x(x) + _vy / 2, _this.y(y) - _vx / 2],
+                    [_this.x(x) - _vy / 2, _this.y(y) + _vx / 2]
+                ];
+                _this.drawPath(points);
+                if (environment.opts.torus)
+                    _this.drawPathWrap(points);
             }
             else if (shape === "rect") {
                 var _h = agent.getData(), _j = _h.width, width_1 = _j === void 0 ? 1 : _j, _k = _h.height, height_1 = _k === void 0 ? 1 : _k;
-                bufferContext.fillRect(_this.x(x) - (width_1 * dpr) / 2, _this.y(y) - (height_1 * dpr) / 2, width_1 * dpr, height_1 * dpr);
+                _this.drawRect(x, y, width_1, height_1);
+                if (environment.opts.torus)
+                    _this.drawRectWrap(x, y, width_1, height_1);
             }
             else if (shape === "triangle") {
                 bufferContext.beginPath();
-                bufferContext.save();
-                bufferContext.translate(_this.x(x), _this.y(y));
-                bufferContext.moveTo(0, -size / 2);
-                bufferContext.lineTo(size / 2, size / 2);
-                bufferContext.lineTo(-size / 2, size / 2);
-                bufferContext.restore();
+                var points = [
+                    [_this.x(x), _this.y(y) - size / 2],
+                    [_this.x(x) + size / 2, _this.y(y) + size / 2],
+                    [_this.x(x) - size / 2, _this.y(y) + size / 2]
+                ];
+                _this.drawPath(points);
+                if (environment.opts.torus)
+                    _this.drawPathWrap(points);
             }
             else if (shape === "circle" || shape === undefined) {
-                bufferContext.arc(_this.x(x), _this.y(y), size * dpr, 0, 2 * Math.PI);
+                _this.drawCircle(x, y, size * dpr);
+                if (environment.opts.torus)
+                    _this.drawCircleWrap(x, y, size);
             }
             bufferContext.fill();
             if (text) {
@@ -3276,22 +4315,6 @@ var CanvasRenderer = /** @class */ (function (_super) {
     return CanvasRenderer;
 }(AbstractRenderer));
 
-/**
- * Maps a number x, from the given domain aMin --> aMax,
- * onto the given range bMin --> bMax.
- * Ex: remap(5, 0, 10, 0, 100) => 50.
- * @param {number} x
- * @param {number} aMin
- * @param {number} aMax
- * @param {number} bMin
- * @param {number} bMax
- * @returns {number} The remapped value.
- * @since 0.0.5
- */
-function remap(x, aMin, aMax, bMin, bMax) {
-    return bMin + ((bMax - bMin) * (x - aMin)) / (aMax - aMin);
-}
-
 /// <reference path="../types/NRange.d.ts" />
 function extractRoundNumbers(range) {
     var min = range.min, max = range.max;
@@ -3603,7 +4626,7 @@ var LineChartRenderer = /** @class */ (function (_super) {
         if (opts.autoScroll && t >= width) {
             x -= t - width;
         }
-        else if (opts.autoScale && t >= width) {
+        else if (opts.autoScale) {
             x *= width / t;
         }
         return x | 0;
@@ -3651,7 +4674,7 @@ var LineChartRenderer = /** @class */ (function (_super) {
         context.restore();
         // draw time values for horizontal axis
         var min = opts.autoScroll && t >= width ? t - width : 0;
-        var max = opts.autoScale && t >= width ? t : width;
+        var max = opts.autoScale ? Math.max(t, 5) : width;
         var timeRange = { min: min, max: max };
         var timeMarkers = extractRoundNumbers(timeRange);
         context.save();
@@ -3731,14 +4754,61 @@ var precision = function (n, d) {
 };
 var escapeStringQuotes = function (s) { return "\"" + s.replace(/"/g, '\\"') + "\""; };
 /**
+ * A `TableRenderer` renders an HTML table (for browsers only) or CSV (comma-separated value)
+ * representation of {@linkcode Agent} data.
+ *
+ * ```js
+ * for (let i = 0; i < 3; i++) {
+ *   environment.addAgent(new Agent({
+ *     x: i * 10,
+ *     y: i - 2
+ *   }));
+ * }
+ *
+ * const renderer = new TableRenderer(environment);
+ * renderer.columns = ['x', 'y'];
+ * renderer.mount('#container');
+ * environment.tick();
+ * ```
+ *
+ * The `TableRenderer` renders:
+ *
+ * |x   |y   |
+ * |----|----|
+ * |0   |-2  |
+ * |10  |-1  |
+ * |20  |0   |
+ *
  * @since 0.5.0
  */
 var TableRenderer = /** @class */ (function (_super) {
     __extends(TableRenderer, _super);
+    /**
+     * The first parameter must be the {@linkcode Environment} that this
+     * `TableRenderer` will render.
+     *
+     * The second parameter specifies options, which can include:
+     * - `"type"` (`"csv"` | `"table"` = `"table"`) &mdash; Whether to render output in CSV or HTML `<table>` format
+     * - `"filter"` &mdash; Include a function (`Agent` => `boolean`) to specify which rows to include in the output. For example, if you only want to include `Agent`s with an x value greater than 100:
+     *   ```js
+     *   const renderer = new TableRenderer(environment, {
+     *     filter: agent => {
+     *       return agent.get('x') > 100;
+     *     }
+     *   });
+     *   ```
+     * - `"limit"` (*number* = `Infinity`) &mdash; The maximum number of rows (`Agent`s) to render. If using a `filter` function, applies the `limit` *after* filtering.
+     * - `"sortKey"` (*string* = `null`) &mdash; Sort the `Agent` data by this key of data
+     * - `"order"` (`"asc"` | `"desc"` = `"desc"`) &mdash; When using a `"sortKey"`, specify whether `Agent`s should be listed in *asc*ending or *desc*ending order
+     * - `"precision"` (*number* = `3`) &mdash; For floating point values, the number of decimal places to display
+     * - `"refresh"` (*number* = `500`) &mdash; The number of milliseconds that should elapse between re-rendering (if this happens too quickly the effect can be visually jarring)
+     */
     function TableRenderer(environment, options) {
         if (options === void 0) { options = {}; }
         var _this = _super.call(this) || this;
+        /** @hidden */
         _this.lastRendered = +new Date();
+        /** @hidden */
         _this.opts = Object.assign({}, defaultTableRendererOptions);
         _this.environment = environment;
         environment.renderers.push(_this);
@@ -3748,7 +4818,16 @@ var TableRenderer = /** @class */ (function (_super) {
     }
     /**
      * Mount this renderer to a DOM element. Pass either a string representing a
-     * CSS selector matching the element (i.e. `"#element-id") or the element itself.
+     * CSS selector matching the element or the element itself.
+     *
+     * ```js
+     * // mounts the renderer to the element with the ID `container`
+     * renderer.mount('#container');
+     *
+     * // mounts the renderer to the element itself
+     * const container = document.getElementById('container');
+     * renderer.mount(container);
+     * ```
      * @override
      * @param {string | HTMLElement} el
      */
@@ -3761,6 +4840,7 @@ var TableRenderer = /** @class */ (function (_super) {
         }
         this.table = container;
     };
+    /** @hidden */
     TableRenderer.prototype.serializeColumns = function (joiner, start, end, escape) {
         if (start === void 0) { start = ""; }
         if (end === void 0) { end = ""; }
@@ -3772,6 +4852,7 @@ var TableRenderer = /** @class */ (function (_super) {
             return "";
         return start + columns.join(joiner) + end;
     };
+    /** @hidden */
     TableRenderer.prototype.serializeRows = function (cellJoiner, rowJoiner, start, end, rowStart, rowEnd, escape) {
         var _this = this;
         if (start === void 0) { start = ""; }
@@ -3820,6 +4901,7 @@ var TableRenderer = /** @class */ (function (_super) {
                 .join(rowJoiner) +
             end);
     };
+    /** @hidden */
     TableRenderer.prototype.renderCSV = function () {
         var columns = this.serializeColumns(",", "", "", true);
         if (columns === "")
@@ -3829,12 +4911,28 @@ var TableRenderer = /** @class */ (function (_super) {
             return columns;
         return columns + "\n" + rows;
     };
+    /** @hidden */
     TableRenderer.prototype.renderHTMLTable = function () {
         var thead = this.serializeColumns("</td><td>", "<thead><tr><td>", "</td></tr></thead>");
         var tbody = this.serializeRows("</td><td>", "", "<tbody>", "</tbody>", "<tr><td>", "</td></tr>");
         return "<table>" + thead + tbody + "</table>";
     };
     /**
+     * Returns the outer HTML of the table or the CSV data as a string. This can be useful for exporting data, particularly in a Node.js environment as opposed to in a browser. For instance, in a Node.js script, you could write the CSV data to a file as follows:
+     *
+     * ```js
+     * const fs = require('fs'); // import the file system module
+     *
+     * const environment = new Environment();
+     * for (let i = 0; i < 3; i++) environment.addAgent(new Agent({ i }));
+     *
+     * const renderer = new TableRenderer(environment, { type: 'csv' });
+     * renderer.columns = ['i'];
+     *
+     * // write the TableRenderer's output to a CSV file named data.csv
+     * fs.writeFileSync('./data.csv', renderer.output());
+     * ```
+     *
      * @since 0.5.0
      */
     TableRenderer.prototype.output = function () {
@@ -3860,22 +4958,6 @@ var TableRenderer = /** @class */ (function (_super) {
     return TableRenderer;
 }(AbstractRenderer));
 
-/**
- * Restricts a number x to the range min --> max.
- * @param {number} x
- * @param {number} min
- * @param {number} max
- * @return {number} The clamped value.
- * @since 0.0.5
- */
-function clamp(x, min, max) {
-    if (x < min)
-        return min;
-    if (x > max)
-        return max;
-    return x;
-}
-
 var PADDING_AT_BOTTOM$1 = 60;
 var PADDING_AT_LEFT$1 = 60;
 var isAxisObject = function (obj) {
@@ -3892,12 +4974,48 @@ var defaultHeatmapOptions = {
 };
 var warnOnce$3 = once(console.warn.bind(console));
 /**
+ * A `Heatmap` can be used to visualize the distribution of {@linkcode Agent}s across two metrics.
+ * While {@linkcode Histogram}s are useful for showing the distribution of `Agent`s along a single metric
+ * (or on multiple metrics using the same scale), a `Heatmap` can show how two metrics relate to one another &mdash;
+ * correlation, inverse correlation, in a nonlinear manner, randomly (no correlation), etc.
+ *
+ * <img src="https://cms.flocc.network/wp-content/uploads/2020/11/heatmap-basic.png" />
+ *
+ * Note above that, although the output appears similar to what a {@linkcode CanvasRenderer} might output, the `y` axis is reversed here &mdash; low values are at the bottom and high at the top, whereas on a `CanvasRenderer` high values are at the bottom and low at the top.
+ *
  * @since 0.5.8
  */
 var Heatmap = /** @class */ (function (_super) {
     __extends(Heatmap, _super);
+    /**
+     * The first parameter must be the {@linkcode Environment} that this
+     * `Heatmap` will render.
+     *
+     * The second parameter specifies options, which can include:
+     * - `from` (*string* = `"white"`) &mdash; The color (name, hex value, or RGB) to draw when a cell contains `0` {@linkcode Agent}s
+     * - `to` (*string* = `"black"`) &mdash; The color (name, hex value, or RGB) to draw when a cell contains the highest number of `Agent`s
+     * - `x` and `y` can be either:
+     *   - *string* = `"x"`/`"y"` respectively &mdash; The name of `Agent` data to measure along the `x`/`y` axis
+     *   - *{ buckets: number; key: string; min: number; max: number }* = `{ buckets: 10, key: 'x' | 'y', min: 0, max: 1 }` &mdash; Include the number of buckets to divide the range `min → max` into, along with the name of `Agent` data
+     * - `width` (*number* = `500`) &mdash; The width, in pixels, of the canvas on which to render
+     * - `height` (*number* = `500`) &mdash; The height, in pixels, of the canvas on which to render
+     * - `scale` (either `"relative"` or `"fixed"`, defaults to `"relative"`)
+     *   - `"relative"` &mdash; The maximum number of `Agent`s in any single cell is automatically used as the highest value in the scale. This updates over time based on `Agent` distribution.
+     *   - `"fixed"` &mdash; You supply the number to use as the maximum value (see `max` below).
+     * - `max` (optional, *number*) &mdash; If you use `scale = "fixed"`, then setting a `max` will cause cells with that number (or higher) of `Agent`s to be drawn using the `to` color.
+     *
+     * ```js
+     * // plots the correlation between age of agents (on the x-axis)
+     * // vs. their wealth (on the y-axis)
+     * const heatmap = new Heatmap(environment, {
+     *   x: 'age',
+     *   y: 'wealth'
+     * });
+     * ```
+     */
     function Heatmap(environment, opts) {
         var _this = _super.call(this) || this;
+        /** @hidden */
         _this.opts = defaultHeatmapOptions;
         _this.environment = environment;
         _this.opts = Object.assign({}, _this.opts, opts);
@@ -3916,7 +5034,7 @@ var Heatmap = /** @class */ (function (_super) {
     }
     /**
      * Map a value (on the range x-min to x-max) onto canvas space to draw it along the x-axis.
-     * @param value
+     * @hidden
      */
     Heatmap.prototype.x = function (value) {
         var width = this.width;
@@ -3924,12 +5042,13 @@ var Heatmap = /** @class */ (function (_super) {
     };
     /**
      * Map a value (on the range y-min to y-max) onto canvas space to draw it along the y-axis.
-     * @param value
+     * @hidden
      */
     Heatmap.prototype.y = function (value) {
         var height = this.height;
         return remap(value, this.getMin("y"), this.getMax("y"), height - PADDING_AT_BOTTOM$1, 0);
     };
+    /** @hidden */
     Heatmap.prototype.getKey = function (axis) {
         var a = this.opts[axis];
         if (isAxisObject(a)) {
@@ -3939,12 +5058,14 @@ var Heatmap = /** @class */ (function (_super) {
             return a;
         }
     };
+    /** @hidden */
     Heatmap.prototype.getBuckets = function (axis) {
         var a = this.opts[axis];
         if (isAxisObject(a) && a.hasOwnProperty("buckets"))
             return a.buckets;
         return 10;
     };
+    /** @hidden */
     Heatmap.prototype.getMin = function (axis) {
         var a = this.opts[axis];
         if (isAxisObject(a) && a.hasOwnProperty("min")) {
@@ -3954,6 +5075,7 @@ var Heatmap = /** @class */ (function (_super) {
             return 0;
         }
     };
+    /** @hidden */
     Heatmap.prototype.getMax = function (axis) {
         var a = this.opts[axis];
         if (isAxisObject(a) && a.hasOwnProperty("max")) {
@@ -3963,6 +5085,7 @@ var Heatmap = /** @class */ (function (_super) {
             return 1;
         }
     };
+    /** @hidden */
     Heatmap.prototype.drawMarkers = function () {
         var _a = this, context = _a.context, width = _a.width, height = _a.height;
         var _b = this.opts, from = _b.from, to = _b.to;
@@ -4015,6 +5138,7 @@ var Heatmap = /** @class */ (function (_super) {
             }
         }
     };
+    /** @hidden */
     Heatmap.prototype.updateScale = function () {
         var _a = this, context = _a.context, environment = _a.environment, height = _a.height;
         var scale = this.opts.scale;
@@ -4036,6 +5160,7 @@ var Heatmap = /** @class */ (function (_super) {
             this.lastUpdatedScale = new Date();
         }
     };
+    /** @hidden */
     Heatmap.prototype.drawRectangles = function () {
         var _a = this, canvas = _a.canvas, environment = _a.environment, width = _a.width, height = _a.height;
         var _b = this.opts, scale = _b.scale, from = _b.from, to = _b.to;
@@ -4062,11 +5187,13 @@ var Heatmap = /** @class */ (function (_super) {
         }
         context.globalAlpha = 1;
     };
+    /** @hidden */
     Heatmap.prototype.resetBuckets = function () {
         for (var i = 0; i < this.getBuckets("x") * this.getBuckets("y"); i++) {
             this.buckets[i] = 0;
         }
     };
+    /** @hidden */
     Heatmap.prototype.updateBuckets = function () {
         var _this = this;
         var environment = this.environment;
@@ -4109,134 +5236,8 @@ var Heatmap = /** @class */ (function (_super) {
 }(AbstractRenderer));
 
 /**
- * Given a mean and standard deviation,
- * returns a value from a normal/Gaussian distribution.
- * @param {number} mean
- * @param {number} sd
- * @returns {number}
- * @since 0.0.8
- */
-function gaussian(mean, sd) {
-    if (mean === void 0) { mean = 0; }
-    if (sd === void 0) { sd = 1; }
-    var y, x1, x2, w;
-    do {
-        x1 = 2 * uniform() - 1;
-        x2 = 2 * uniform() - 1;
-        w = x1 * x1 + x2 * x2;
-    } while (w >= 1);
-    w = Math.sqrt((-2 * Math.log(w)) / w);
-    y = x1 * w;
-    return y * sd + mean;
-}
-
-/// <reference path="../types/Point.d.ts" />
-/**
- * Finds the Manhattan distance between `p1` and `p2`.
- * The inputs may be plain objects
- * with `x`, `y`, and/or `z` keys, or Agent-like objects who have
- * `x`, `y`, and/or `z` data.
- * @param {Point|Agent} p1
- * @param {Point|Agent} p2
- * @return {number} The Manhattan distance between p1 and p2.
- * @since 0.0.12
- */
-function manhattanDistance(p1, p2) {
-    var x1 = (p1 instanceof Agent ? p1.get("x") : p1.x) || 0;
-    var y1 = (p1 instanceof Agent ? p1.get("y") : p1.y) || 0;
-    var z1 = (p1 instanceof Agent ? p1.get("z") : p1.z) || 0;
-    var x2 = (p2 instanceof Agent ? p2.get("x") : p2.x) || 0;
-    var y2 = (p2 instanceof Agent ? p2.get("y") : p2.y) || 0;
-    var z2 = (p2 instanceof Agent ? p2.get("z") : p2.z) || 0;
-    var dx = Math.abs(x2 - x1);
-    var dy = Math.abs(y2 - y1);
-    var dz = Math.abs(z2 - z1);
-    // distance for toroidal environments
-    if (p1 instanceof Agent &&
-        p2 instanceof Agent &&
-        p1.environment &&
-        p2.environment &&
-        p1.environment === p2.environment &&
-        p1.environment.width &&
-        p1.environment.height &&
-        p1.environment.opts.torus) {
-        var environment = p1.environment;
-        var width = environment.width, height = environment.height;
-        if (dx > width / 2)
-            dx = width - dx;
-        if (dy > height / 2)
-            dy = height - dy;
-    }
-    return dx + dy + dz;
-}
-
-/**
- * Seed a pseudo-random number generator with a value.
- * This can be used to produce predictable pseudo-random numbers.
- * When calling `utils.random`, `utils.sample`, or other functions
- * relying on randomness with the same initial seed, the values
- * generated will always be the same.
- *
- * Predictable randomness can be turned off by calling `seed(null)`, or reset
- * by calling `seed(value)` again with the initial value you used.
- * @param value
- * @since 0.5.0
- */
-var seed = function (value) { return PRNG.seed(value); };
-
-/**
- * Find the standard deviation of an Array of numbers.
- * @param {Array<number>} arr
- * @returns {number}
- * @since 0.0.16
- */
-function stdDev(arr) {
-    if (arr.length === 0)
-        return null;
-    var ave = mean(arr);
-    return Math.sqrt(mean(arr.map(function (x) { return (x - ave) * (x - ave); })));
-}
-
-/**
- * @since 0.1.4
+ * The current version of the Flocc library.
  */
-function zfill(str, width) {
-    if (width === void 0) { width = 0; }
-    var output = str;
-    while (output.length < width)
-        output = "0" + output;
-    return output;
-}
-
-
-
-var utils = /*#__PURE__*/Object.freeze({
-    __proto__: null,
-    clamp: clamp,
-    distance: distance,
-    gaussian: gaussian,
-    gcd: gcd,
-    manhattanDistance: manhattanDistance,
-    lerp: lerp,
-    remap: remap,
-    random: random,
-    sample: sample$1,
-    sampler: sampler,
-    seed: seed,
-    series: series,
-    shuffle: shuffle,
-    sum: sum,
-    max: max,
-    mean: mean,
-    median: median,
-    min: min,
-    percentile: percentile,
-    stdDev: stdDev,
-    uniform: uniform,
-    uuid: uuid$1,
-    zfill: zfill
-});
-
-var version = "0.5.18";
+var version = "0.5.21";
 
 export { ASCIIRenderer, Agent, CanvasRenderer, Colors, Environment, GridEnvironment, Heatmap, Histogram, KDTree, LineChartRenderer, Network, NumArray, Rule, TableRenderer, Terrain, version as VERSION, Vector, utils };