Class Agent

constructor

• new Agent(data?: Data): Agent

  Agents can be instantiated with or without data. Instantiating with data is equivalent to creating an Agent and immediately calling Agent.set to add data.

  // instantiates an Agent without data
  const a = new Agent();
  
  // instantiates an Agent with data
  const b = new Agent({
    x: 50,
    y: 100
  });
  Copy

  Parameters

  • data: Data = {}

  Returns Agent

environment

const environment = new Environment();
const agent = new Agent();
agent.environment; // returns `null`

environment.addAgent(agent);
agent.environment === environment; 
Copy

id

const agent = new Agent();
const id = agent.id; // returns "59B4F928-46C8-..." (for example)
Copy

decrement

• decrement(name: string, n?: number): void

  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.

  agent.set('x', 50);
  agent.decrement('x');
  agent.get('x'); // returns 49
  Copy

  If the second parameter n is included, decrements by that amount.

  agent.set('x', 50);
  agent.decrement('x', 10);
  agent.get('x'); // returns 40
  Copy

  If the value has not yet been set, calling this method sets it to -1 (or to -n).

  Parameters

  • name: string
  • n: number = 1

  Returns void

  Since

  0.0.8

emit

• emit<T = any>(type: string, data: T): void

  Emit an event to the environment's event bus.

  Type Parameters

  • T = any

  Parameters

  • type: string

    Event type

  • data: T

    Event payload

  Returns void

  Example

  // In tick function
  agent.set('tick', (a) => {
    if (a.get('health') < 10) {
      a.emit('agent:lowHealth', { health: a.get('health') });
    }
  });
  Copy

  Since

  0.6.0

get

• get(name: string): any

  Retrieve an arbitrary piece of data associated by name. If the data has not been set, returns null.

  Parameters

  • name: string

  Returns any

  Since

  0.0.5

getData

• getData(): Data

  Retrieve all the data associated with this Agent at once.

  agent.set('x', 3);
  agent.set('color', 'blue');
  agent.set('active', false);
  
  agent.getData();
  // returns {
  //   x: 3,
  //   color: 'blue',
  //   active: false
  // }
  Copy

  Returns Data

  Since

  0.1.0

increment

• increment(name: string, n?: number): void

  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.

  agent.set('x', 50);
  agent.increment('x');
  agent.get('x'); // returns 51
  Copy

  If the second parameter n is included, decrements by that amount.

  agent.set('x', 50);
  agent.increment('x', 10);
  agent.get('x'); // returns 60
  Copy

  If the value has not yet been set, calling this method sets it to 1 (or to n).

  Parameters

  • name: string
  • n: number = 1

  Returns void

  Since

  0.0.8

on

• on<T = any>(
      type: string,
      handler: (agent: Agent, event: FloccEvent<T>) => void,
  ): () => void

  Subscribe to an event type. The handler receives the agent as the first argument and the event object as the second.

  Type Parameters

  • T = any

  Parameters

  • type: string

    Event type to listen for

  • handler: (agent: Agent, event: FloccEvent<T>) => void

    Function to call when event is emitted

  Returns () => void

  Unsubscribe function

  Example

  agent.on('food:nearby', (agent, event) => {
    agent.set('target', event.data.location);
    agent.set('state', 'foraging');
  });
  Copy

  Since

  0.6.0

scheduleAt

• scheduleAt(time: number): void

  Schedule this agent to tick at a specific environment time. Only has an effect if the environment uses a scheduler that supports explicit scheduling (e.g., PriorityScheduler).

  Parameters

  • time: number

    The environment time at which to tick

  Returns void

  Example

  agent.set('tick', (a) => {
    // Do something...
    
    // Schedule next tick at time 150
    a.scheduleAt(150);
  });
  Copy

  Since

  0.6.0

scheduleIn

• scheduleIn(delay: number): void

  Schedule this agent to tick after a delay (relative to current time). Shorthand for agent.scheduleAt(environment.time + delay).

  Parameters

  • delay: number

    Number of ticks to wait before next activation

  Returns void

  Example

  agent.set('tick', (a) => {
    const energy = a.get('energy');
    a.set('energy', energy - 10);
    
    // Lower energy = longer wait until next action
    const delay = Math.ceil(100 / energy);
    a.scheduleIn(delay);
  });
  Copy

  Since

  0.6.0

set

• set(name: string | Data, value?: any): void

  Set a piece of data associated with this agent. Name should be a string while value can be any valid type. Alternatively, the first parameter can be an object, which merges the current data with the new data (adding new values and overwriting existing). Ex. agent.set('x', 5); agent.set('color', 'red');

  Parameters

  • name: string | Data
  • Optionalvalue: any

  Returns void

  Since

  0.0.5