@gaiaengine/2d

A TypeScript/ES module built on top of Pixi.js and inspired by @commonmodule/ts. It provides a lightweight 2D game engine framework with:

• Core Node Hierarchy (GameNode, DisplayNode, TransformableNode, etc.)
• Collision Detection (shapes, polygon collision, broad-phase management)
• Resource Loading (textures, spritesheets, audio, text, binary)
• Tile-Based Map Rendering (rectangular grid system, layered terrain and objects)
• UI Components (joystick, DOM overlays, debug displays)
• Sound and Music (background music, sound effects, volume management)
• Scenes and Camera (game scenes, camera movement, zoom, panning)
• Shape Nodes (circles, ellipses, rectangles with optional fill/stroke)

Table of Contents

1. Installation
2. API Reference
   • Collision
     • Collidable & Colliders
     • CollisionChecker
     • CollisionDetector & ZoneCollisionDetector
   • Core
     • GameNode
     • DisplayNode
     • TransformableNode
     • WindowEventNode
     • Movable
     • StateSet
     • Coordinates
     • compareCoordinates()
   • Debug Utilities
     • DebugManager
     • DebugDisplay
     • DebugColliderDrawNode
   • Timers & Delays
     • Delay
     • Interval
   • DOM Wrapper
     • DomWrapperNode
     • DomTextNode
   • Image & Sprites
     • BaseImageSprite
     • Sprite
     • AnimatedSprite
     • Background
   • Input
     • Joystick & CrossPlatformJoystick
   • Loading Resources
     • TextureLoader
     • SpritesheetLoader
     • AudioBufferLoader
     • BinaryLoader
     • TextLoader
     • BitmapFontLoader
     • ResourcePreloader
   • Tile Maps
     • RectMap
     • RectMapObject & RectMapTerrain
     • AnimatedRectMapObject & AnimatedRectMapTerrain
     • MapData
     • TerrainDirection
   • Particles
     • ParticleSystem
   • Scenes & Camera
     • Scene
     • Camera
     • TransitionOverlay
   • Screens & Layers
     • GameScreen
     • Fullscreen
     • LetterboxedScreen
     • PanZoomGameScreen
     • Layer
     • SuperRootNode
   • Shape Nodes
     • ShapeNode
     • CircleNode
     • EllipseNode
     • RectangleNode
   • Audio & Sound
     • AudioContextManager
     • BackgroundMusic
     • RandomSoundLooper
     • Sound
     • SoundEffectsPlayer
     • VolumeManager
   • Text & Fonts
     • BitmapFont
     • BitmapTextNode
     • TextNode
   • Zoning & Broad-Phase
     • ZoneManager
   • Configuration
     • GaiaEngineConfig
3. Usage Examples
4. Contributing
5. License

Installation

npm install @gaiaengine/2d
# or
yarn add @gaiaengine/2d

Note: This library internally depends on Pixi.js (^7.2.4) and also references @commonmodule/ts for event and resource loading utilities. Make sure these are also installed or available in your environment.

API Reference

Collision

Collidable & Colliders

• Collidable: An interface indicating an object has an array of colliders and a globalTransform to place them in the game world.

  export default interface Collidable {
    colliders: Collider[];
    globalTransform: Transform;
  }

• Collider: A type union for shape definitions used in collision:

  type Collider =
    | RectCollider
    | CircleCollider
    | EllipseCollider
    | PolygonCollider;

• Colliders include:

  • BaseCollider: minimal x, y offset.
  • RectCollider: rectangle with width, height.
  • CircleCollider: circle with radius.
  • EllipseCollider: ellipse with width, height.
  • PolygonCollider: polygon with a set of { x, y } points.

• ColliderType: enum to identify shape type:

  enum ColliderType {
    Rectangle,
    Circle,
    Ellipse,
    Polygon,
  }

CollisionChecker

A static utility class that checks collision between any two colliders of known type. Methods include:

• checkCollision(colliderA, transformA, colliderB, transformB)
• rectRectCollision(...)
• circleCircleCollision(...)
• rectCircleCollision(...)
• polygonPolygonCollision(...)
• and many more specialized checks

It also provides point-inside shape checks, line-line intersection checks, and internal methods to approximate shapes (like approximateCircle, approximateEllipse) for polygon-based intersection tests.

CollisionDetector & ZoneCollisionDetector

• CollisionDetector: A game node that holds two lists: subjects and obstacles. For each frame, it checks collisions between every subject and obstacle and calls onCollision(subject, obstacle) if they overlap.
• ZoneCollisionDetector: Extends CollisionDetector but uses a ZoneManager for broad-phase optimization. Subjects are tested only against obstacles in nearby zones.

Core

GameNode

• A fundamental tree node for building a scene graph.
• It extends EventTreeNode (from @commonmodule/ts) and maintains a parent-child relationship.
• append(...) and remove() let you build or tear down node hierarchies.
• update(deltaTime: number) is called every frame (or on your chosen loop) to update this node and its children.

DisplayNode

• Extends TransformableNode but holds a Pixi.js Container (or subclass).
• Syncs x, y, scale, rotation, and alpha with the underlying Pixi display object.
• Example usage:

  class CustomDisplayNode extends DisplayNode {
    constructor() {
      super(new Container());
    }
    // ...
  }

TransformableNode

• A GameNode with position, scale, rotation, and alpha.
• Maintains both transform (local) and globalTransform.
• Typically extended by DisplayNode or GameObject.

WindowEventNode

• A specialized GameNode that can bind window-level events (e.g. keydown, resize) via onWindow("event", callback).
• Automatically unbinds them when removed.

Movable

• A GameObject subclass adding velocity, acceleration, min/max speeds, and optional bounds.
• move(radian, speed) or moveTo(x, y, speed, onArrive?) for basic movement logic.
• stop() to reset speed.

StateSet

• A utility class that handles a set of states (each state is a GameObject). Only one state is visible at a time.
• e.g., Idle, Running, Jumping states each with their own display object.

Coordinates

A simple interface { x: number; y: number }.

compareCoordinates()

Utility function to check if two coordinates are the same.

Debug Utilities

DebugManager

• Tracks debug statistics, e.g. displayNodeCount.

DebugDisplay

• A GameObject that shows a small overlay of FPS and current node count.
• Appends a text node to the DOM, typically used in dev mode.

DebugColliderDrawNode

• A GameObject that draws the collider shapes (RectCollider, CircleCollider, etc.) as outlines for debugging.
• Typically appended to the same parent that has colliders.

Timers & Delays

Delay

• A GameNode that waits a specified duration (delayDuration) before invoking a callback, then removes itself.

Interval

• A GameNode that invokes a callback periodically every intervalDuration seconds, akin to setInterval, but in the game update loop.
• Optionally starts immediately (startImmediately).

DOM Wrapper

DomWrapperNode

• A subclass of TransformableNode that wraps a DomNode from @commonmodule/app.
• Positions the DOM element in absolute coordinates synchronized with the engine’s globalTransform and the current screen scale.

DomTextNode

• A DomWrapperNode specialized for text content.
• this.domNode.text = "..."; sets the textual content.

Image & Sprites

BaseImageSprite

• An abstract GameObject that loads and manages a single texture.
• src property triggers a load.
• Subclassed by Sprite and Background.

Sprite

• A BaseImageSprite that uses either a direct image or a spritesheet frame.
• If using a spritesheet + Atlas, it references a specific frame ID.

AnimatedSprite

• Similar usage to Sprite, but if you have multiple frames in the atlas.animations, it constructs a Pixi AnimatedSprite.
• Can set animation, loop, fps, and handle onAnimationEnd.

Background

• A special BaseImageSprite that uses a Pixi TilingSprite.
• Allows setting scrollSpeedX, scrollSpeedY for parallax or scrolling backgrounds.

Input

Joystick & CrossPlatformJoystick

• Joystick: A simple arrow-key-based or WASD-like input class that triggers onMove(radian) or onRelease(). Also tracks pressed keys.
• CrossPlatformJoystick: Extends Joystick, adding mobile touch-based controls with an on-screen joystick DomNode.
  • It draws a background “joystick ring” and a “knob”.
  • Fires the same callbacks as Joystick but uses touch events.

Loading Resources

TextureLoader

• Extends ResourceLoader<Texture> from @commonmodule/ts.
• Loads images into Pixi Texture objects.
• Uses reference counting and frees them when no longer in use.

SpritesheetLoader

• Extends ResourceLoader<Spritesheet>.
• Given an ID, source URL, and a JSON Atlas, it loads the image and creates a Pixi Spritesheet.

AudioBufferLoader

• Extends ResourceLoader<AudioBuffer>.
• Fetches audio data, decodes it via AudioContext.decodeAudioData.

BinaryLoader

• Extends ResourceLoader<Uint8Array>.
• Fetches raw binary data from a URL.

TextLoader

• Extends ResourceLoader<string>.
• Fetches text files from a URL.

BitmapFontLoader

• Extends ResourceLoader<BitmapFont>.
• Parses .fnt XML data and related texture.
• Produces a BitmapFont with character metrics, line height, etc.

ResourcePreloader

• A helper class that can preload a list of resources (text, binary, texture, audio, or spritesheet) in parallel.

Tile Maps

RectMap

• A RectTileLoader subclass for rendering a tile map with “rectangular tiles”.
• Maintains two layers: terrainLayer and objectLayer.
• Uses a MapData structure to determine which terrain or object ID should be placed at each tile coordinate.
• Supports additional “neighbors-based” tiles for corners or transitions.
• Implements deferred loading/unloading of tiles based on camera position (using tileSize and extraLoadTileCount).

RectMapObject & RectMapTerrain

• Basic classes that extend Sprite to represent static, single-frame map sprites, with optional fade-in (fadeDuration).

AnimatedRectMapObject & AnimatedRectMapTerrain

• Extend AnimatedSprite, allowing multiple-frame animations for map objects or terrains.
• Support a fade-in effect too.

MapData

• Defines the structure of the terrain, objects, frames, colliders, etc.

  interface MapData {
    terrains: { [id: string]: TerrainData };
    objects: { [id: string]: MapObjectData };
    terrainMap: { [cord: string]: string };
    mapObjects: { x: number; y: number; object: string }[];
  }

• MapDataTransformer can convert MapData into a set of Pixi Atlas data.

TerrainDirection

• An enum describing how to render partial/corner fill for transitions:
  • e.g. TopLeft, FillTopRightBottom, etc.

Particles

ParticleSystem

• A GameObject for creating bursts of particles.
• Configurable spawn count, lifetime, direction, speed, fade speed, etc.
• Uses Pixi Sprite for each particle.

Scenes & Camera

Scene

• An abstract GameObject subclass representing a screen or scene in your game.
• Typically manages its own nodes, background, UI, etc.
• transitionTo(SomeOtherScene) is an example method that can show a TransitionOverlay.

Camera

• A helper class associated with GameScreen to track camera position (x, y) and scale (zoom).
• setPosition(x, y), set scale, etc.

TransitionOverlay

• A DOM-based fade overlay that transitions out the current scene and in a new one.
• Typically used by Scene.transitionTo.

Screens & Layers

GameScreen

• The main rendering surface, built around a Pixi Renderer with an internal update loop using requestAnimationFrame.
• Has a root SuperRootNode, a Camera, and an optional set of named Layer objects.
• Accepts options for width, height, backgroundColor, layers, pixelated.

Fullscreen

• Extends GameScreen, automatically resizing to fill the browser window.
• Attaches to document.body and updates on resize events.

LetterboxedScreen

• Extends GameScreen to maintain aspect ratio with letterboxes (black bars).
• Uses additional DOM elements to fill in top/bottom/left/right letterbox regions.

PanZoomGameScreen

• Extends GameScreen, adding “click-and-drag to pan” and “mouse wheel to zoom.”
• Saves camera position & zoom in a persistent store.

Layer

• A simple GameObject used to group children with a specific zIndex.

SuperRootNode

• A top-level GameObject that sits inside the GameScreen’s renderer.
• Usually only used internally; direct parent for layers and the game’s main root node.

Shape Nodes

ShapeNode

• An abstract DisplayNode<Graphics> that draws a shape on a Pixi Graphics.
• Subclassed by CircleNode, EllipseNode, RectangleNode.

CircleNode

• Draws a circle at (0,0) of a given radius.
• Optionally fill or stroke.

EllipseNode

• Draws an ellipse with width, height.

RectangleNode

• Draws a rectangle with width, height.
• Coordinates are centered by default (-width/2, -height/2 offset).

Audio & Sound

AudioContextManager

• A singleton that holds the AudioContext.
• Checks OGG support, ensures the context is resumed on user interaction.

BackgroundMusic

• Plays a set of looped music tracks (OGG or MP3).
• Randomly chooses among them, restarts on track end, etc.
• Integrates with VolumeManager.backgroundMusicVolume.

RandomSoundLooper

• Loops random sound effects from a set of sources at a certain volume.
• Pauses/resumes on mobile browser visibility changes.

Sound

• Wraps a single audio buffer playback in the AudioContext.
• Supports play, pause, stop, loop, volume, fade, etc.
• Reference counted by AudioBufferLoader.

SoundEffectsPlayer

• A singleton that plays short sound effects from a list of URLs, at random, or from a single URL.
• Respects VolumeManager.soundEffectsVolume.

VolumeManager

• A global volume manager storing two volumes: backgroundMusicVolume and soundEffectsVolume.
• Notifies all subscribed sounds or players on changes.

Text & Fonts

BitmapFont

• Represents parsed .fnt data with a Pixi Texture.
• Has character metrics and size/lineHeight info.

BitmapTextNode

• A GameObject that lays out text glyphs using a loaded BitmapFont.
• Creates a separate Pixi Sprite for each character, aligned by the font metrics.

TextNode

• A GameObject that renders standard Pixi Text.
• Allows specifying style, anchor, and auto-loading custom fonts via a FontLoader from @commonmodule/app.

Zoning & Broad-Phase

ZoneManager

• A GameNode that divides space into grid “zones”.
• For each frame, checks if objects have moved to a new zone and updates them accordingly.
• Ideal for broad-phase collision checks, used by ZoneCollisionDetector.

Configuration

GaiaEngineConfig

• A simple config singleton with isDevMode flag.
• If isDevMode is true, certain debug behaviors are enabled (like DebugDisplay or console logs).

Usage Examples

1. Creating a Simple GameScreen

import { Fullscreen, GameObject, Sprite } from "@gaiaengine/2d";

const screen = new Fullscreen({ backgroundColor: 0x222222 });
const player = new Sprite(100, 100, "player.png");

screen.root.append(player);

// animate loop is handled by the internal requestAnimationFrame

2. Adding Collision Detection

import {
  Collidable,
  CollisionDetector,
  GameObject,
  RectCollider,
} from "@gaiaengine/2d";

class Player extends GameObject implements Collidable {
  colliders = [
    { type: 0, width: 50, height: 50, x: 0, y: 0 }, // ColliderType.Rectangle=0
  ];
  // ...
}

class Obstacle extends GameObject implements Collidable {
  colliders = [
    { type: 0, width: 32, height: 32, x: 0, y: 0 },
  ];
  // ...
}

const detector = new CollisionDetector<Player, Obstacle>(
  (subject, obstacle) => {
    console.log("Collision detected between", subject, "and", obstacle);
  },
);
screen.root.append(detector);

const player = new Player();
const block = new Obstacle();

detector.addSubject(player);
detector.addObstacle(block);

3. Using a ParticleSystem

import { ParticleSystem } from "@gaiaengine/2d";

const particles = new ParticleSystem({
  src: "star.png",
  count: { min: 10, max: 20 },
  lifetime: { min: 0.5, max: 1.5 },
  direction: { min: 0, max: Math.PI * 2 },
  speed: { min: 50, max: 150 },
  scale: { min: 0.5, max: 1.0 },
  fadingSpeed: -1.0,
  rotationToDirection: false,
});

screen.root.append(particles);
particles.burst(200, 200);

4. Loading a RectMap

import {
  MapData,
  RectMap,
  ResourcePreloader,
  // ...
} from "@gaiaengine/2d";

const mapData: MapData = {
  terrains: {/* ... */},
  objects: {/* ... */},
  terrainMap: {/* "0,0": "grass", etc. */},
  mapObjects: [],
};

// Preload required textures/spritesheets
await ResourcePreloader.preloadResources([
  {
    type: "spritesheet",
    id: "my-spritesheet",
    src: "atlas.png",
    atlas: {/* ... */},
  },
]);

// Create a RectMap
const tileMap = new RectMap(
  32, // tile size in px
  { mySpritesheet: "atlas.png" }, // map of ID => src
  mapData, // the map data
  {
    extraLoadTileCount: 2,
    debounceDelay: 0.2,
    tileFadeDuration: 0.5,
  },
);
screen.root.append(tileMap);

Contributing

1. Fork the repository.
2. Create a new branch: git checkout -b feature/my-feature.
3. Make your changes and commit: git commit -m "Add my feature".
4. Push the changes: git push origin feature/my-feature.
5. Open a pull request.

License

This package is released under the MIT License. See LICENSE for details.

Author: yj.gaia
Inspired by: @commonmodule/app
Pixi.js: https://pixijs.com/