Options
All
  • Public
  • Public/Protected
  • All
Menu

Class Terrain

The Terrain class lets Environments function as lattices upon which cellular automata can grow. With a Terrain, Agents may not be necessary, since all the cells of a Terrain can follow update rules (similar to but simplified from Agents).

Usage

 
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

Hierarchy

  • Terrain

Implements

  • EnvironmentHelper

Index

Constructors

Properties

Methods

Constructors

constructor

  • new Terrain(width: number, height: number, options?: TerrainOptions): Terrain

  • 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) — Whether to run the Terrain in synchronous (true) or asynchronous (mode). Defaults to synchronous. Depending on the timing mode, Terrain update rules should be written differently.
    • grayscale (boolean = false)
      • In color mode (the default), each cell of a Terrain is represented by a 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) — The size, in pixels, of each cell's width and height when the Terrain is rendered using a 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:
    Terrain with scale = 1 Terrain with scale = 5

    In addition to the above setup, you will need to initialize the Terrain and add an update rule.

    Parameters

    • width: number
    • height: number
    • options: TerrainOptions = ...

    Returns Terrain

Properties

height

height: 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.

width

width: number

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.

Methods

addRule

  • addRule(rule: TerrainRule): void

  • Similar to adding behavior to Agents, 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.

    // 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 pixel-like object.

    In asynchronous mode, functions should use the set method to update either this cell or a different cell.

    // 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

    Parameters

    • rule: TerrainRule

    Returns void

init

  • init(rule: TerrainRule): void

  • Initialize (or overwrite) all cell values. The rule you pass has the same signature as addRule, but should always return a value (either a number or pixel-like object).

    // 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

    Parameters

    • rule: TerrainRule

    Returns void

load

  • load(path: string, callback?: Function): void

  • Given a local path or remote URL to an image, load that image and set 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.

    const terrain = new Terrain(400, 400);
terrain.load("/path/to/local/image.jpg", function() {
  console.log("Image loaded successfully!");
});
    since

    0.4.0

    Parameters

    • path: string

      The path to or URL of the image

    • Optional callback: Function

    Returns void

neighbors

  • neighbors(x: number, y: number, radius?: number, moore?: boolean): (number | Pixel)[]

  • Get the values of the neighbors of a cell within a certain radius. Depending on the fourth parameter, retrieves either the von Neumann neighborhood or the Moore neighborhood.

    // 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)
    since

    0.4.0

    Parameters

    • x: number
    • y: number
    • radius: number = 1
    • moore: boolean = false

      Defaults to using the von Neumann neighborhood.

    Returns (number | Pixel)[]

    Either an array of numbers (grayscale mode) or pixel-like objects (color mode).

sample

  • sample(x: number, y: number): number | Pixel

  • 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, g: number, b: number, a: number } representing the value of that coordinate.

    since

    0.4.0

    Parameters

    • x: number

      The x coordinate

    • y: number

      The y coordinate

    Returns number | Pixel

set

  • set(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 in async mode — otherwise you should return the new value from the update rule (see Terrain.addRule).

    since

    0.4.0

    Parameters

    • x: number

      The x coordinate

    • y: number

      The y coordinate

    • r: number | Pixel

      A number 0-255 (if in grayscale mode or setting a single value for r/g/b), or a pixel-like object

    • Optional g: number

      The green value 0-255

    • Optional b: number

      The blue value 0-255

    • Optional a: number

      The alpha/transparency value 0-255

    Returns void

Generated using TypeDoc