flocc 0.5.18 → 0.5.21

package/dist/helpers/KDTree.d.ts

@@ -17,8 +17,8 @@ declare class KDTree {
     axis(): "x" | "y" | "z" | null;
     locateSubtree(pt: Agent | Point): KDTree;
     subtreesWithinDistance(pt: Point | Agent, d: number, trees?: KDTree[]): KDTree[];
-    intersectsAlongDimension: (pt: Agent | Point, d: number, coord: "x" | "y" | "z") => boolean;
-    sphereIntersectsBBox: (pt: Agent | Point, d: number) => boolean;
+    intersectsAlongDimension: (pt: Point | Agent, d: number, coord: "x" | "y" | "z") => boolean;
+    sphereIntersectsBBox: (pt: Point | Agent, d: number) => boolean;
     /**
      * Return all the Agents in this KDTree that are within `d` distance
      * of the given Point or Agent `pt`.

package/dist/helpers/Network.d.ts

@@ -2,157 +2,233 @@
 import { Agent } from "../agents/Agent";
 import { Environment } from "../environments/Environment";
 import { Array2D } from "./Array2D";
-interface AgentCallback {
-    (agent: Agent, index: number): any;
-}
 /**
+ * A `Network` allows {@linkcode Agent}s to be connected to each other.
  * @since 0.1.3
  */
 declare class Network implements EnvironmentHelper {
+    /** @hidden */
     adjacencyList: Map<Agent, Agent[]>;
+    /**
+     * instantiated and updated in _resetAdjacencyMatrix
+     * @hidden
+     */
     adjacencyMatrix: Array2D;
     /**
-     * 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).
      */
     agents: Agent[];
     /**
      * 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
      */
     addAgent(agent: Agent): boolean;
     /**
-     * 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
      */
     addFromEnvironment(environment: Environment): void;
     /**
-     * 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
      */
     removeAgent(agent: Agent): boolean;
     /**
-     * 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
      */
     clear(): void;
     /**
-     * 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
      */
-    connect(a1: Agent, a2: Agent): boolean;
-    /**
-     * Returns `true` if the given agents are connected in the network.
-     * @param {Agent} a1
-     * @param {Agent} a2
+    connect(a: Agent, b: Agent): boolean;
+    /**
+     * @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
      */
-    areConnected(a1: Agent, a2: Agent): boolean;
-    /**
-     * 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
+    areConnected(a: Agent, b: Agent): boolean;
+    /**
+     * 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
      */
     disconnect(a1: Agent, a2: Agent): boolean;
     /**
-     * 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
      */
     size(): number;
     /**
-     * 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
      */
-    forEach(cb: AgentCallback): void;
+    forEach(callback: (agent: Agent, index: number) => any): void;
     /**
-     * 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
      */
-    forEachRand(cb: AgentCallback): void;
+    forEachRand(callback: (agent: Agent, index: number) => any): void;
     /**
-     * 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
      */
     isInNetwork(agent: Agent): boolean;
     /**
-     * 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
      */
     get(i: number): Agent;
     /**
-     * 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
      */
     indexOf(agent: Agent): number;
     /**
-     * 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
      */
     neighbors(agent: Agent): Agent[] | null;
     /**
-     * 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
      */
     complete(): void;
     /**
      * Internal helper function to reset the adjacencyMatrix.
      * This gets called when agents are added to or removed from the network.
+     * @hidden
      */
     _resetAdjacencyMatrix(): void;
     /**
-     * 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
      */
     isTriplet(a: Agent, b: Agent, c: Agent): boolean;
     /**
-     * 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
      */
     isClosedTriplet(a: Agent, b: Agent, c: Agent): boolean;
+    /** @hidden */
     _globalClusteringCoefficient(): number;
     /**
-     * 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
      */
     clusteringCoefficient(agent?: Agent): number;
     /**
-     * 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
      */
     averageClusteringCoefficient(): number;

package/dist/helpers/NumArray.d.ts

@@ -1,4 +1,5 @@
 /**
+ * @hidden
  * @since 0.3.11
  */
 declare class NumArray {

package/dist/helpers/Rule.d.ts

@@ -4,22 +4,80 @@ declare type StepToken = number | string | Step;
 interface Step extends Array<StepToken> {
 }
 /**
+ * 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
  */
 declare class Rule {
+    /**
+     * Points to the {@linkcode Environment} that is passed in the `Rule`'s constructor function (should be the same `Environment` of the {@linkcode Agent} invoking this `Rule`)
+     */
     environment: Environment;
+    /** @hidden */
     steps: Step[];
+    /** @hidden */
     locals: {
         [key: string]: any;
     };
+    /**
+     * 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|
+     */
     constructor(environment: Environment, steps: Step[]);
     /**
      * interpret single array step
      * @since 0.3.0
+     * @hidden
      */
     evaluate: (agent: Agent, step: any[]) => any;
     /**
      * @since 0.3.0
+     * @hidden
      */
     call(agent: Agent): any;
 }

package/dist/helpers/Terrain.d.ts

@@ -11,53 +11,151 @@ interface Pixel {
 }
 declare type TerrainRule = (x: number, y: number) => Pixel | number | void;
 /**
+ * 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
  */
-export declare const Colors: {
-    [name: string]: Pixel;
-};
+export declare class Colors {
+    /** <div style="width: 100%; height: 20px; background-color: rgb(0, 0, 0);"></div> */
+    static BLACK: Pixel;
+    /** <div style="width: 100%; height: 20px; background-color: rgb(255, 255, 255); border: 1px solid #eee;"></div> */
+    static WHITE: Pixel;
+    /** <div style="width: 100%; height: 20px; background-color: rgb(255, 0, 0);"></div> */
+    static RED: Pixel;
+    /** <div style="width: 100%; height: 20px; background-color: rgb(127, 0, 0);"></div> */
+    static MAROON: Pixel;
+    /** <div style="width: 100%; height: 20px; background-color: rgb(255,255, 0);"></div> */
+    static YELLOW: Pixel;
+    /** <div style="width: 100%; height: 20px; background-color: rgb(0, 0, 255);"></div> */
+    static BLUE: Pixel;
+    /** <div style="width: 100%; height: 20px; background-color: rgb(0, 127, 0);"></div> */
+    static GREEN: Pixel;
+    /** <div style="width: 100%; height: 20px; background-color: rgb(0, 255, 0);"></div> */
+    static LIME: Pixel;
+    /** <div style="width: 100%; height: 20px; background-color: rgb(0, 255, 255);"></div> */
+    static AQUA: Pixel;
+    /** <div style="width: 100%; height: 20px; background-color: rgb(255, 165, 0);"></div> */
+    static ORANGE: Pixel;
+    /** <div style="width: 100%; height: 20px; background-color: rgb(255, 0, 255);"></div> */
+    static FUCHSIA: Pixel;
+    /** <div style="width: 100%; height: 20px; background-color: rgb(127, 0, 127);"></div> */
+    static PURPLE: Pixel;
+}
 /**
+ * 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
  */
 declare class Terrain implements EnvironmentHelper {
+    /** @hidden */
     data: Uint8ClampedArray;
+    /** @hidden */
     nextData: Uint8ClampedArray;
+    /** @hidden */
     opts: TerrainOptions;
+    /**
+     * The number of cells across in a `Terrain`. If you use a `scale` larger than `1`, the `Terrain` will be rendered at `width * scale` pixels wide on the screen.
+     */
     width: number;
+    /**
+     * The number of cells from top to bottom in a `Terrain`. If you use a `scale` larger than `1`, the `Terrain` will be rendered at `height * scale` pixels high on the screen.
+     */
     height: number;
+    /** @hidden */
     rule: TerrainRule;
     /**
+     * Instantiate a new `Terrain` by passing its `width` and `height` as the first two parameters, and an optional configuration object as the third.
+     *
+     * ### Options
      *
-     * @param {number} width - The width of the terrain
-     * @param {number} height - The height of the terrain
-     * @param 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`:
+     *
+     * <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}.
      */
     constructor(width: number, height: number, options?: TerrainOptions);
     /**
-     * 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
      */
     init(rule: TerrainRule): void;
     /**
-     * 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
      */
     addRule(rule: TerrainRule): void;
     /**
      * 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
      */
-    load(path: string, cb?: Function): void;
+    load(path: string, callback?: Function): void;
     /**
      * Get the pixel value at the coordinate (x, y). If in grayscale mode, this
      * returns a single number. Otherwise, it returns a pixel-like object { r: number,
@@ -68,19 +166,25 @@ declare class Terrain implements EnvironmentHelper {
      */
     sample(x: number, y: number): Pixel | number;
     /**
-     * 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
      */
     neighbors(x: number, y: number, radius?: number, moore?: boolean): (Pixel | number)[];
+    /** @hidden */
     _setAbstract(data: Uint8ClampedArray, x: number, y: number, r: number | Pixel, g?: number, b?: number, a?: number): void;
     /**
      * Set new pixel data at a coordinate on the terrain. Only call this directly if
@@ -95,8 +199,11 @@ declare class Terrain implements EnvironmentHelper {
      * @since 0.4.0
      */
     set(x: number, y: number, r: number | Pixel, g?: number, b?: number, a?: number): void;
+    /** @hidden */
     _setNext(x: number, y: number, r: number | Pixel, g?: number, b?: number, a?: number): void;
+    /** @hidden */
     _execute(x: number, y: number): void;
+    /** @hidden */
     _loop({ randomizeOrder }: {
         randomizeOrder?: boolean;
     }): void;