geotic

geotic

adjective physically concerning land or its inhabitants.

Geotic is an ECS library focused on performance, features, and non-intrusive design. View benchmarks.

• entity a unique id and a collection of components
• component a data container
• query a way to gather collections of entities that match some criteria, for use in systems
• world a container for entities and queries
• prefab a template of components to define entities as JSON
• event a message to an entity and it's components

This library is heavily inspired by ECS in Caves of Qud. Watch these talks to get inspired!

• Thomas Biskup - There be dragons: Entity Component Systems for Roguelikes
• Brian Bucklew - AI in Qud and Sproggiwood
• Brian Bucklew - Data-Driven Engines of Qud and Sproggiwood

Python user? Check out the Python port of this library, ecstremity!

usage and examples

npm install geotic

• Sleepy Crawler a full fledged roguelike that makes heavy use of geotic by @ddmills
• snail6 a bloody roguelike by @luetkemj
• Gobs O' Goblins by @luetkemj
• Javascript Roguelike Tutorial by @luetkemj
• basic example using pixijs

Below is a contrived example which shows the basics of geotic:

…

Engine

The Engine class is used to register all components and prefabs, and create new Worlds.

import { Engine } from 'geotic';

const engine = new Engine();

engine.registerComponent(clazz);
engine.registerPrefab({ ... });
engine.destroyWorld(world);

Engine properties and methods:

• registerComponent(clazz): register a Component so it can be used by entities
• regsterPrefab(data): register a Prefab to create pre-defined entities
• destroyWorld(world): destroy a world instance

World

The World class is a container for entities. Usually only one instance is needed, but it can be useful to spin up more for offscreen work.

…

World properties and methods:

• createEntity(id = null): create an Entity. optionally provide an ID
• getEntity(id): get an Entity by ID
• getEntities(): get all entities in this world
• createPrefab(name, properties = {}): create an entity from the registered prefab
• destroyEntity(entity): destroys an entity. functionally equivilant to entity.destroy()
• destroyEntities(): destroys all entities in this world instance
• serialize(entities = null): serialize and return all entity data into an object. optionally specify a list of entities to serialize
• deserialize(data): deserialize an object
• cloneEntity(entity): clone an entity
• createId(): Generates a unique ID
• destroy(): destroy all entities and queries in the world

Entity

A unique id and a collection of components.

…

Component properties and methods:

• static properties = {} object that defines the properties of the component. Properties must be json serializable and de-serializable!
• static allowMultiple = false are multiple of this component type allowed? If true, components will either be stored as an object or array on the entity, depending on keyProperty.
• static keyProperty = null what property should be used as the key for accessing this component. if allowMultiple is false, this has no effect. If this property is omitted, it will be stored as an array on the component.
• entity returns the Entity this component is attached to
• world returns the World this component is in
• isDestroyed returns true if this component is destroyed
• serialize() serialize the component properties
• destroy() remove this and destroy this component
• onAttached() override this method to add behavior when this component is attached (added) to an entity
• onDestroyed() override this method to add behavior when this component is removed & destroyed
• onEvent(evt) override this method to capture all events coming to this component
• on[EventName](evt) add these methods to capture the specific event

This example shows how allowMultiple and keyProperty work:

…

Query

Queries keep track of sets of entities defined by component types. They are limited to the world they're created in.

…

• query.get() get the result array of the query. This array should not be modified in place. For performance reasons, the result array that is exposed is the working internal query array.
• onEntityAdded(fn) add a callback for when an entity is created or updated to match the query
• onEntityRemoved(fn) add a callback for when an entity is removed or updated to no longer match the query
• has(entity) returns true if the given entity is being tracked by the query. Mostly used internally
• refresh() re-check all entities to see if they match. Very expensive, and only used internally

Performance enhancement

Set the immutableResults option to false if you are not modifying the result set. This option defaults to true. WARNING: When this option is set to false, strange behaviour can occur if you modify the results. See issue #55.

const query = world.createQuery({
    all: [A, B],
    immutableResult: false, // defaults to TRUE
});

const results = query.get();

results.splice(0, 1); // DANGER! do not modify results if immutableResult is false!

serialization

example Save game state by serializing all entities and components

const saveGame = () => {
    const data = world.serialize();
    localStorage.setItem('savegame', data);
};

...

const loadGame = () => {
    const data = localStorage.getItem('savegame');
    world.deserialize(data);
};

Event

Events are used to send a message to all components on an entity. Components can attach data to the event and prevent it from continuing to other entities.

The geotic event system is modelled aver this talk by Brian Bucklew - AI in Qud and Sproggiwood.

…

Prefab

Prefabs are a pre-defined template of components.

The prefab system is modelled after this talk by Thomas Biskup - There be dragons: Entity Component Systems for Roguelikes.

…