Craters

craters logo

Craters is a modular JavaScript framework reimplemented in TypeScript for rapid HTML5 game development

Documentation

Features

Entity Component System (ECS): A robust, functional ECS architecture for managing game logic (World, Entity, System, Query).
Collision Detection:
- SAT Library: Separating Axis Theorem implementation for accurate collision detection between circles and convex polygons.
- QuadTree: Spatial partitioning data structure for efficient broad-phase collision detection.
Rendering:
- WebGLRenderer: High-performance sprite batching.
- Canvas2DRenderer: Fallback or simple 2D rendering with primitive drawing support.
Input Management: Unified keyboard, mouse, and touch input handling using modern KeyboardEvent.code.
Sound: Web Audio API wrapper for sound effects and music.
Asset Management: Simple loader for images and other resources.
Tilemaps: Support for loading and rendering tilemaps.

Installation

npm install craters

Usage

Basic ECS Setup

import { EntityComponentSystem as ECS, RenderLoop } from "craters";

// 1. Define Components
class Position extends ECS.Component {
  constructor(public x: number, public y: number) { super(); }
}

class Velocity extends ECS.Component {
  constructor(public dx: number, public dy: number) { super(); }
}

// 2. Define System
class MovementSystem extends ECS.System {
  public execute(delta: number): void {
    // Query entities with Position and Velocity
    const query = this.world.createQuery([Position, Velocity]);
    
    query.entities.forEach(entity => {
      const pos = entity.getComponent(Position);
      const vel = entity.getComponent(Velocity);
      pos.x += vel.dx * delta;
      pos.y += vel.dy * delta;
    });
  }
}

// 3. Setup World
const world = new ECS.World();
world.registerSystem(new MovementSystem());

// 4. Create Entity
const player = world.createEntity();
player.addComponent(new Position(0, 0));
player.addComponent(new Velocity(1, 0));

// 5. Run Loop
const loop = new RenderLoop((delta) => {
  world.execute(delta);
});

Examples

Play craters sandbox

Contributing

In lieu of a formal styleguide, take care to maintain the existing coding style. Add unit tests for any new or changed functionality. Lint and test your code using Grunt.

Also, please don't edit files in the "dist" subdirectory as they are generated via Grunt. You'll find source code in the "src" subdirectory!

Release History

See CHANGELOG.md for the full release history.

Craters - v0.1.2