@mesa-engine/core v1.0.4

Mesa Engine - Core

An entity-component-system engine built with typescript.

CLI

The Mesa CLI includes helpful commands to generate new projects as well as scaffold out new systems, components, and blueprints. Check it out here.

Installing

New project using CLI (recommended)

$ npm install -g @mesa-engine/cli
$ mesa new my-app
$ cd my-app
$ npm install
$ mesa run

Add into existing project

$ npm install @mesa-engine/core

Basic Usage

To use the entity component system, you first must create your Engine to store your systems and entities.

You can create as many as you wish, but usually it's only one per application.

import { Engine } from "@mesa-engine/core";
const engine = new Engine();

Defining your components:

import { Component } from "@mesa-engine/core";

// Components can have custom constructors, but they must be able to be initialized
// with no arguments, because entities create the instances for you.
// Try not to save complex data types in your components
class PositionComponent implements Component {
  x = 0;
  y = 0;
}

class VelocityComponent implements Component {
  x = 0;
  y = 0;
}

// If you are making a component library, and want to avoid collisions
// You can add a tag to your component implementations
class MyLibraryComponent implements Component {
  // This will ensure your component won't collide with other "MyLibraryComponent"
  static readonly tag = "my-library/MyLibraryComponent";
}

Defining your systems:

import { Component, Family, System, FamilyBuilder } from "@mesa-engine/core";
class GravitySystem extends System {
  static readonly DEFAULT_ACCELERATION = 0.98;
  family?: Family;
  acceleration: number;

  // Constructors are free for your own implementation
  constructor(acceleration = GravitySystem.DEFAULT_ACCELERATION) {
    super();
    this.acceleration = acceleration;
    // higher priorities means the system runs before others with lower priority
    this.priority = 300;
  }
  // This is called when a system is added to an engine, you may want to
  // startup your families here.
  onAttach(engine: Engine) {
    // Needed to work properly
    super.onAttach(engine);
    // Families are an easy way to have groups of entities with some criteria.
    this.family = new FamilyBuilder(engine).include(VelocityComponent).build();
  }

  // This, in reality is the only method your system must implement
  // but using onAttach to prepare your families is useful.
  update(engine: Engine, delta: number) {
    for (let entity of this.family.entities) {
      // Easy to get a component by class
      // Be warned, if the entity lacks this component, an error *will* be thrown.
      // But families ensure than you will always have the required components.
      const velocity = entity.getComponent(VelocityComponent);
      velocity.y += this.acceleration;
      // if the family doesn't require that component
      // you can always check for it
      if (entity.hasComponent(PositionComponent)) {
        const position = entity.getComponent(PositionComponent);
      } else {
        // You can create components on an entity easily.
        const position = entity.putComponent(PositionComponent);
      }
    }
  }
}

The Mesa engine also includes blueprints that act as templates for creating entities:

import { Blueprint } from '@mesa-engine/core';
import * as c from '../components';

// Blueprints take a list of components that will be added to the entity when created.
// Components on blueprints can be initialized with certain values.
export class Renderable implements Blueprint {
    components = [
        {component: c.PositionComponent}, 
        {component: c.RenderComponent, values: {sprite: 'defaultImg'}}
    ];
}

// Blueprints can be composed using other blueprints.
// Child blueprints will override component values set by parent blueprints.
// (i.e. the following blueprint will override 'defaultImg' with 'playerImg') 
export class Player implements Blueprint {
    blueprints = [new Renderable];
    components = [{component: c.RenderComponent, values: {sprite: 'playerImg'}}];
}

Entities can be created from blueprints as so:

import { Engine } from '@mesa-engine/core';
import { Player } from "../blueprints";

let playerEntity = engine.buildEntity(Player);
engine.addEntity(playerEntity);

Limitations

You can only have one instance of a component per entity. entity ID's are not generated by default, if you need them to have ID's, set them up yourself:

entity.id = myGeneratedId();

LICENSE

The license is MIT, so use it as you please without worries.