Flocc

Agent-based modeling in JavaScript in the browser or on the server. [v0.4.8]

GridEnvironment

Overview

The class flocc.GridEnvironment (from here on, just GridEnvironment) is a special case of the Environment classNote: GridEnvironments use different methods in order to add, retrieve, and remove agents than standard Environments (.getAgentAt instead of .getAgent, for example).

A new GridEnvironment of size x/y can be instantiated by calling: const environment = new GridEnvironment(x, y).

It is automatically populated with x * y cells (which are just Agents set with x and y data).

Methods

Unless indicated otherwise, GridEnvironment inherits all the methods from Environment.

.getCell(x, y)

Returns the Cell (an Agent) at (xy).

.addAgentAt(x, y, agent = new Agent())

The x and y parameters are required. If the third parameter is left empty, it defaults to an empty agent, on which .set(‘x’, x) and .set(‘y’, y) are called.

environment.addAgentAt(0, 0);
// implicitly adds a new agent to the cell at 0, 0

const agent = new Agent();
environment.addAgentAt(3, 2, agent);
// explicitly adds `agent` to the cell at 3, 2

.getAgentAt(x, y)

Returns the agent at the cell x, y, or undefined if the cell is empty.

.removeAgentAt(x, y)

This methods overrides Environment‘s .removeAgent method. Instead of removing agents by reference (as in Environment), the agent at the cell x, y is removed from the environment.

.fill()

Fills every cell of the environment with a new, empty agent.

environment.fill();

// this is equivalent to...
for (let x = 0; x < environment.width; x++) {
    for (let y = 0; y < environment.height; y++) {
        environment.addAgent(x, y);
    }
}

.loop(callback)

Loops over every cell in the environment, running the callback function at each cell. This is handy if not every cell contains an agent, but you still want to run some code on a cell-by-cell basis.

callback is invoked with three parameters: xy, and agent (if there is one at that cell).

// Loop over every cell. For cells with an x-value greater than 5,
// if there is an agent at that cell, set its color to yellow. If there
// is no agent at that cell, create a new, yellow agent, and add it.
environment.loop((x, y, agent) => {
    if (x > 5) {
        if (agent) {
            agent.set('color', 'yellow');
        } else {
            const agt = new Agent();
            agt.set('color', 'yellow');
            environment.addAgent(x, y, agt);
        }
    }
});

.neighbors(agent, radius = 1, moore = false)

Given an agent in the environment, returns an array containing the neighboring agents. By default, this method will only look within a radius of 1 (neighboring agents immediately to the north, south, east, and west). By increasing the radius parameter, more neighboring agents will be included.

This method also defaults to using the von Neumann neighborhood, which looks for all agents within radius by Manhattan distance. If the third parameter is set to true, it will use the Moore neighborhood instead, which looks for all agents within a square of width/length 2 * radius + 1 of the given agent.

von Neumann neighborhood Moore neighborhood

Images from Wolfram MathWorld

.swap(x1, y1, x2, y2)

Swap the agents at the cells with coordinates x1, y1, and x2, y2, respectively. If both cells are empty, nothing happens. If only one cell is empty, this just moves the agent to the previously empty cell.

const A = environment.get(0, 0);
const B = environment.get(3, 4);

environment.swap(0, 0, 3, 4);
// now B will be the result of calling environment.get(0, 0)
// and A of calling environment.get(3, 4)

.getRandomOpenCell()

If there is at least one open cell, returns an object like { x: number, y: number } corresponding to that cell. Internally, cells are shuffled so that the returned cell should be randomized.

If every cell already contains an agent, returns null.

Next, read how to render a GridEnvironment onto a web page using the ASCIIRenderer.