flocc 0.5.18 → 0.5.21

package/dist/flocc.js

@@ -378,10 +378,19 @@
     }
 
     /**
-     * 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) {
@@ -392,7 +401,7 @@
      * 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}
@@ -409,6 +418,8 @@
     }
 
     /**
+     * A `Vector` contains multi-dimensional numeric data.
+     *
      * @since 0.1.0
      */
     var Vector = /** @class */ (function () {
@@ -421,20 +432,40 @@
             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) {
@@ -462,128 +493,175 @@
             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) {
@@ -598,6 +676,17 @@
             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) {
@@ -605,6 +694,7 @@
             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) {
@@ -619,8 +709,14 @@
             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 () {
@@ -631,6 +727,7 @@
             return this;
         };
         /**
+         * Create a copy of this `Vector`.
          * @since 0.1.0
          */
         Vector.prototype.clone = function () {
@@ -638,8 +735,15 @@
             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) {
@@ -652,8 +756,8 @@
             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);
@@ -663,11 +767,23 @@
             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;
@@ -732,16 +848,70 @@
         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;
@@ -866,6 +1036,7 @@
         }
         /**
          * @since 0.3.0
+         * @hidden
          */
         Rule.prototype.call = function (agent) {
             return this.evaluate(agent, this.steps);
@@ -921,40 +1092,85 @@
     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;
@@ -970,9 +1186,8 @@
             }
         };
         /**
-         * 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) {
@@ -990,8 +1205,20 @@
             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 () {
@@ -1025,6 +1252,7 @@
         /**
          * 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") {
@@ -1063,25 +1291,57 @@
             }
         };
         /**
-         * 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) {
@@ -1089,9 +1349,29 @@
             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
          */
@@ -1107,16 +1387,34 @@
             });
         };
         /**
-         * 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
          */
@@ -1133,7 +1431,7 @@
         };
         /**
          * 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;
@@ -1148,6 +1446,7 @@
         };
         /**
          * Execute all rules.
+         * @hidden
          */
         Agent.prototype.executeRules = function () {
             var _this = this;
@@ -1164,6 +1463,7 @@
         };
         /**
          * Execute all enqueued rules.
+         * @hidden
          */
         Agent.prototype.executeEnqueuedRules = function () {
             // if new data from the rules
@@ -1193,9 +1493,15 @@
     }());
 
     /**
-     * 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) {
@@ -1230,6 +1536,7 @@
     }
 
     /**
+     * @hidden
      * @since 0.3.11
      */
     var NumArray = /** @class */ (function () {
@@ -1241,7 +1548,7 @@
             get: function () {
                 return this._index;
             },
-            enumerable: true,
+            enumerable: false,
             configurable: true
         });
         NumArray.prototype.set = function (i, n) {
@@ -1292,24 +1599,33 @@
     }());
 
     /**
+     * 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) {
@@ -1322,8 +1638,8 @@
             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) {
@@ -1331,10 +1647,20 @@
             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) {
@@ -1354,7 +1680,17 @@
             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 () {
@@ -1364,23 +1700,36 @@
             }
         };
         /**
-         * 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;
@@ -1388,24 +1737,42 @@
             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) {
@@ -1425,40 +1792,50 @@
             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) {
@@ -1469,17 +1846,26 @@
             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) {
@@ -1488,7 +1874,7 @@
             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 () {
@@ -1501,6 +1887,7 @@
         /**
          * 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();
@@ -1517,11 +1904,7 @@
             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) {
@@ -1535,11 +1918,7 @@
             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) {
@@ -1552,6 +1931,7 @@
             ].filter(function (v) { return v; }).length;
             return connections === 3;
         };
+        /** @hidden */
         Network.prototype._globalClusteringCoefficient = function () {
             var _this = this;
             var triplets = 0;
@@ -1573,12 +1953,15 @@
             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) {
@@ -1602,9 +1985,11 @@
             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 () {
@@ -1660,6 +2045,14 @@
     }());
 
     /**
+     * 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) {
@@ -1669,6 +2062,15 @@
     }
 
     /**
+     * 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) {
@@ -1710,8 +2112,16 @@
     }
 
     /**
-     * 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
      */
@@ -1719,6 +2129,9 @@
         return percentile(arr, 0.5);
     }
 
+    function isMultipleSampleFunc(f) {
+        return f([1]).length > 0;
+    }
     var sample;
     /**
      * Gets a random element from `array`.
@@ -1808,12 +2221,21 @@
 
     /// <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) {
@@ -2111,6 +2533,14 @@
     }());
 
     /**
+     * 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) {
@@ -2179,32 +2609,80 @@
         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; }
@@ -2224,9 +2702,16 @@
             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) {
@@ -2249,12 +2734,41 @@
                     }
                 }
             }
+            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) {
@@ -2262,14 +2776,23 @@
         };
         /**
          * 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;
@@ -2283,8 +2806,8 @@
                     .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");
@@ -2325,16 +2848,21 @@
             }
         };
         /**
-         * 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) {
@@ -2356,6 +2884,7 @@
             }
             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;
@@ -2408,9 +2937,11 @@
         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;
@@ -2423,6 +2954,7 @@
             // 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;
@@ -2452,52 +2984,272 @@
         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) {
@@ -2559,7 +3311,7 @@
             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 () {
@@ -2569,64 +3321,132 @@
             }
         };
         /**
-         * 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);
@@ -2635,26 +3455,41 @@
             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) {
@@ -2675,9 +3510,17 @@
         };
         /**
          * 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();
@@ -2718,10 +3561,21 @@
     };
     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; }
@@ -2756,6 +3610,7 @@
             }
         };
         /**
+         * @hidden
          * @since 0.1.0
          */
         GridEnvironment.prototype.normalize = function (x, y) {
@@ -2770,7 +3625,7 @@
             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_
@@ -2799,8 +3654,8 @@
             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
@@ -2963,6 +3818,7 @@
         };
         /**
          * Execute all cell rules.
+         * @hidden
          * @param { boolean } randomizeOrder
          */
         GridEnvironment.prototype._executeCellRules = function (randomizeOrder) {
@@ -2989,6 +3845,7 @@
         };
         /**
          * Execute all enqueued cell rules.
+         * @hidden
          * @param { boolean } randomizeOrder
          */
         GridEnvironment.prototype._executeEnqueuedCellRules = function (randomizeOrder) {
@@ -3014,8 +3871,8 @@
             }
         };
         /**
-         * 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
          */
@@ -3024,11 +3881,11 @@
             // 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);
@@ -3041,13 +3898,24 @@
 
     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) {
@@ -3062,11 +3930,25 @@
 
     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;
@@ -3075,6 +3957,7 @@
             return _this;
         }
         /**
+         * Renders the contents of the `ASCIIRenderer`'s {@linkcode GridEnvironment}.
          * @since 0.0.10
          */
         ASCIIRenderer.prototype.render = function () {
@@ -3110,12 +3993,46 @@
         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);
@@ -3136,14 +4053,17 @@
             _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;
@@ -3152,6 +4072,117 @@
             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;
@@ -3239,28 +4270,36 @@
                     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) {
@@ -3282,22 +4321,6 @@
         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;
@@ -3609,7 +4632,7 @@
             if (opts.autoScroll && t >= width) {
                 x -= t - width;
             }
-            else if (opts.autoScale && t >= width) {
+            else if (opts.autoScale) {
                 x *= width / t;
             }
             return x | 0;
@@ -3657,7 +4680,7 @@
             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();
@@ -3737,14 +4760,61 @@
     };
     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);
@@ -3754,7 +4824,16 @@
         }
         /**
          * 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
          */
@@ -3767,6 +4846,7 @@
             }
             this.table = container;
         };
+        /** @hidden */
         TableRenderer.prototype.serializeColumns = function (joiner, start, end, escape) {
             if (start === void 0) { start = ""; }
             if (end === void 0) { end = ""; }
@@ -3778,6 +4858,7 @@
                 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 = ""; }
@@ -3826,6 +4907,7 @@
                     .join(rowJoiner) +
                 end);
         };
+        /** @hidden */
         TableRenderer.prototype.renderCSV = function () {
             var columns = this.serializeColumns(",", "", "", true);
             if (columns === "")
@@ -3835,12 +4917,28 @@
                 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 () {
@@ -3866,22 +4964,6 @@
         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) {
@@ -3898,12 +4980,48 @@
     };
     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);
@@ -3922,7 +5040,7 @@
         }
         /**
          * 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;
@@ -3930,12 +5048,13 @@
         };
         /**
          * 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)) {
@@ -3945,12 +5064,14 @@
                 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")) {
@@ -3960,6 +5081,7 @@
                 return 0;
             }
         };
+        /** @hidden */
         Heatmap.prototype.getMax = function (axis) {
             var a = this.opts[axis];
             if (isAxisObject(a) && a.hasOwnProperty("max")) {
@@ -3969,6 +5091,7 @@
                 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;
@@ -4021,6 +5144,7 @@
                 }
             }
         };
+        /** @hidden */
         Heatmap.prototype.updateScale = function () {
             var _a = this, context = _a.context, environment = _a.environment, height = _a.height;
             var scale = this.opts.scale;
@@ -4042,6 +5166,7 @@
                 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;
@@ -4068,11 +5193,13 @@
             }
             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;
@@ -4115,135 +5242,9 @@
     }(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";
 
     exports.ASCIIRenderer = ASCIIRenderer;
     exports.Agent = Agent;