🎮 ECS Game Engine

✨ Features

🚀 Core Performance

• Archetype-based storage for O(1) queries
• Entity ID recycling with zero allocations
• Cache-friendly data structures
• Dirty tracking for selective updates

🎯 Developer Experience

• Full TypeScript with strict typing
• Zero runtime dependencies
• Hot reloading with Bun
• Interactive scaffolding for rapid development
• Comprehensive test coverage

🧩 Architecture

• System dependencies & scheduling
• Event-driven communication
• Plugin system with hot loading
• Object pooling for memory efficiency

🌐 Multiplayer

• WebSocket server built-in
• Type-safe network protocol
• Session management
• Real-time synchronization

📜 Core Principles

Entities = IDs • Components = Data • Systems = Logic

Built on proven ECS patterns for maximum performance and maintainability. Learn more →

🚀 Quick Start

Installation

bun add @danjdewhurst/ecs-ts

Requirements: Bun 1.2+

💻 Basic Usage

import { World, BaseSystem, type Component } from "@danjdewhurst/ecs-ts";

// 1. Define components (pure data)
interface Position extends Component {
  readonly type: "position";
  x: number;
  y: number;
}

// 2. Create systems (game logic)
class MovementSystem extends BaseSystem {
  readonly name = "MovementSystem";
  readonly priority = 1;

  update(world: World, deltaTime: number): void {
    const entities = this.queryEntities(world, "position", "velocity");

    for (const entityId of entities) {
      const pos = world.getComponent<Position>(entityId, "position");
      const vel = world.getComponent<Velocity>(entityId, "velocity");

      if (pos && vel) {
        pos.x += vel.dx * deltaTime;
        pos.y += vel.dy * deltaTime;
      }
    }
  }
}

// 3. Create world and run
const world = new World();
world.addSystem(new MovementSystem());

const entity = world.createEntity();
world.addComponent(entity, { type: "position", x: 0, y: 0 });
world.addComponent(entity, { type: "velocity", dx: 10, dy: 5 });

world.update(1 / 60); // Update at 60 FPS

📚 Documentation

Core Concepts

| Concept | Description | Example | | ------------- | ------------------------------------ | ----------------------------------------- | | World | Container for all ECS data | const world = new World() | | Entity | Unique ID representing a game object | world.createEntity() | | Component | Pure data attached to entities | { type: 'health', hp: 100 } | | System | Logic that processes entities | class MovementSystem extends BaseSystem | | Query | Find entities by components | world.query('position', 'velocity') |

Advanced Features

// Subscribe to events
world.subscribeToEvent("player-death", (event) => {
  console.log(`Player ${event.data.playerId} died`);
});

// Emit events
world.emitEvent({
  type: "player-death",
  timestamp: Date.now(),
  data: { playerId: entity },
});

class PhysicsSystem extends BaseSystem {
  readonly name = "PhysicsSystem";
  readonly priority = 1;
  // No dependencies - runs first
}

class CollisionSystem extends BaseSystem {
  readonly name = "CollisionSystem";
  readonly priority = 10; // Higher priority, but runs AFTER physics
  readonly dependencies = ["PhysicsSystem"]; // Explicit dependency
}

class DamageSystem extends BaseSystem {
  readonly name = "DamageSystem";
  readonly priority = 1;
  readonly dependencies = ["CollisionSystem"]; // Runs after collision
}

// Systems execute in dependency order: Physics → Collision → Damage
// Regardless of add order or priority

// Validate dependencies before adding
const validation = world.validateSystemDependencies([
  new PhysicsSystem(),
  new CollisionSystem(),
]);

// Get execution order
const order = world.getSystemExecutionOrder();
// [PhysicsSystem, CollisionSystem, DamageSystem]

// View dependency graph
const graph = world.getSystemDependencyGraph();

Benefits:

• ✅ Prevents logic errors from incorrect system ordering
• ✅ Self-documenting system relationships
• ✅ Detects circular dependencies with helpful errors
• ✅ Foundation for future parallel execution

import { GameServer } from "@danjdewhurst/ecs-ts/websocket";

const server = new GameServer(world, {
  port: 3000,
  maxClients: 100,
});

await server.start();

class MyPlugin implements Plugin {
  readonly name = "MyPlugin";
  readonly version = "1.0.0";

  async initialize(world: World): Promise<void> {
    // Setup systems, components, etc.
  }
}

const pluginManager = new PluginManager();
await pluginManager.loadPlugin(new MyPlugin());
await pluginManager.initializeAll(world);

# Launch interactive scaffolding wizard
bun run scaffold

# OR use direct commands with aliases
bun run scaffold component    # Generate component (alias: c, comp)
bun run scaffold system       # Generate system (alias: s, sys)
bun run scaffold example      # Generate example (alias: e, ex)
bun run scaffold game         # Generate game template (alias: g)
bun run scaffold plugin       # Generate plugin (alias: p, plug)
bun run scaffold --help       # Show all commands and options

# Automatically creates tests and updates index files
# Follows ECS patterns and project conventions

Generate:

• Components with custom properties and factory functions
• Systems with dependencies and component queries
• Examples demonstrating specific functionality
• Game templates with complete setups
• Plugins following plugin architecture

// Object pooling
const bulletPool = new ObjectPool(
  () => ({ x: 0, y: 0, active: false }),
  (bullet) => {
    bullet.active = false;
  }
);

// Dirty tracking for selective updates
world.dirtyTracker.markDirty(entityId, "position");

🧩 Examples

# Clone and run examples
git clone https://github.com/danjdewhurst/ecs-ts.git
cd ecs-ts && bun install

bun examples/basic-example.ts                  # Core ECS
bun examples/system-dependencies-example.ts    # System dependencies
bun examples/event-system-example.ts           # Events
bun examples/websocket-example.ts              # Multiplayer
bun examples/plugin-system-example.ts          # Plugins
bun examples/performance-optimization.ts       # Optimization

🧩 Development

# Install dependencies
bun install

# Development commands
bun test           # Run tests (100% coverage)
bun run typecheck  # Type checking
bun run check      # Lint & format
bun run build      # Build for production
bun run scaffold   # Interactive code scaffolding

# Commit with conventional commits
bun run commit     # Interactive commit helper

Test Coverage

• ✅ 24 test suites with comprehensive coverage
• ✅ Core ECS, Events, WebSocket, Plugins, Performance
• ✅ Unit and integration tests
• ✅ 100% critical path coverage

📈 Performance

| Operation | Complexity | Notes | | -------------------- | ---------- | --------------------- | | Entity Creation | O(1) | ID recycling | | Component Add/Remove | O(1) | Hash map | | Single Query | O(1) | Archetype lookup | | Multi Query | O(k) | k = matching entities | | System Update | O(n) | n = active entities |

🤝 Contributing

Contributions welcome! Please follow conventional commits and ensure all tests pass.

See CONTRIBUTING.md for details.

📄 License

MIT © 2025 danjdewhurst