Fennecs

🦊 A lazy ECS library

Setup

yarn add fennecs

Basic usage

import { createWorld, Entity } from fennecs
import { LazinessComponent, napSystem } from './below'

const world = createWorld()

world
  .createEntity()
  .addComponent(new LazinessComponent(3))

world.addSystem([LazinessComponent], napSystem);

// game loop...
world.update(1)
world.update(1)
world.update(1)

Components are basic constructors:

class LazinessComponent {
  time
  constructor(n: number) {
    this.time = n
  }
}

Systems are functions that take an array of Entities and the time since the last update:

function napSystem(entities: Entity[], dt: number) {
  entities.forEach((ent: Entity) => {
    const laziness = ent.getComponent(LazinessComponent)
    laziness.time -= dt
    if (laziness.time <= 0) {
      ent.removeComponent(LazinessComponent)
      console.log('Woke up!')
    }
  })
}

API

Fennecs exports a single named export createWorld() that creates a new World to place your entities and systems in.

World

world.createEntity(fn?)

Creates and adds a new Entity to the world. If a initialiser is passed, it will be called with the new entity to allow for very basic assemblage creation.

world.createFamily(filter[])

Creates and adds (or retrieves a cached version of) an Entity Family to the world. Takes an array of Component constructors to use as a filter, and returns a Family object that automatically keeps track of matching entities.

world.addSystem(filter[], fn)

Adds a System to the world. Takes an array of Component constructors to use as a filter, and a callback function that receives the array of matching entities and the time since the last update.

world.addGlobalSystem(fn)

Adds a global System to the world. This runs every world update like regular systems, but does not receive any entities to operate on.

world.getSystems(name?)

Returns all registered systems. Optionally takes a tag name to filter by.

world.update(dt)

Update the world for one step. This triggers all Systems to update. The first argument is the time since that last update.

world.on(name, fn)

Listens for events.

world.emit(name, ...data)

Emits a new event.

Entity

entity.addComponent(componentInstance)

Adds a component to the entity.

entity.addTag(name)

Adds a tag to the entity. Basically a component without any data.

entity.removeComponent(component)

Removes the component from the entity.

entity.removeTag(name)

Removes the tag from the entity.

entity.hasComponent(component)

Returns whether the entity has the component.

entity.getComponent(component)

Returns the component attached to the entity.

entity.hasTag(name)

Returns whether the entity has the tag.

entity.on(name, fn)

Listens for events. Alias for world.on.

entity.emit(name, ...data)

Emits a new event. Alias for world.emit.

entity.destroy()

Destroys the entity from the world.

Family

family.getSize()

Returns the number of matching entities in the Family.

family.getEntities()

Returns all matching entities (updates automatically when Entities or Components are added or removed).

family.destroy()

Destroys the Family so Entities are no longer being tracked and matched against it.

System

system.tag(name)

Adds a tag to the system.

system.destroy()

Permanently removes the system from the world.

system.pause()

Pause execution of the system.

system.resume()

Resume execution of the system.