Blecsd Game

@blecsd/game Package Skill

The @blecsd/game package provides a high-level API for building terminal games with blECSd. It wraps the core ECS world, input system, and game loop into a simple createGame() factory. All blECSd functional programming rules apply.

Install: pnpm add @blecsd/game Peer dependency: blecsd >= 0.7.0 Import: import { createGame } from '@blecsd/game'

Quick Start

import { createGame } from '@blecsd/game';

const game = createGame({
  title: 'My Game',
  width: 80,
  height: 24,
  targetFPS: 30,
  mouse: true,
  alternateScreen: true,
  hideCursor: true,
});

// Create UI
const player = game.createBox({
  position: { x: 10, y: 10 },
  dimensions: { width: 3, height: 1 },
  content: '@',
});

// Input
game.onKey('q', () => game.quit());

// Update loop
game.onUpdate((dt) => {
  if (game.isKeyDown('up')) moveUp(dt);
  if (game.isKeyDown('down')) moveDown(dt);
});

// Start
game.start();

API Reference

createGame(config?)

Factory function that returns a Game interface. Config is optional:

interface GameConfig {
  title?: string;                // Window title
  width?: number;                // Terminal width
  height?: number;               // Terminal height
  targetFPS?: number;            // Target frame rate (default: 60)
  mouse?: boolean;               // Enable mouse input
  alternateScreen?: boolean;     // Use alternate screen buffer
  hideCursor?: boolean;          // Hide terminal cursor
  fixedTimestep?: {
    tickRate: number;            // Physics tick rate (e.g., 60)
    maxUpdatesPerFrame: number;  // Prevent spiral of death
    interpolate: boolean;        // Interpolate between ticks
  };
}

Widget Creation

All widget factories take a config object and return an entity ID:

const box = game.createBox(config);
const text = game.createText(config);
const button = game.createButton(config);
const input = game.createInput(config);
const textarea = game.createTextarea(config);
const textbox = game.createTextbox(config);
const checkbox = game.createCheckbox(config);
const radio = game.createRadioButton(config);
const radioSet = game.createRadioSet(config);
const select = game.createSelect(config);
const slider = game.createSlider(config);
const progress = game.createProgressBar(config);
const list = game.createList(config);
const form = game.createForm(config);

Input System

Key Handlers

// Single key handler
game.onKey('space', () => shoot());
game.onKey('escape', () => pause());

// Any key handler
game.onAnyKey((keyName) => {
  console.log(`Key pressed: ${keyName}`);
});

// Check if key is currently held
if (game.isKeyDown('left')) moveLeft();
if (game.isKeyDown('right')) moveRight();

Mouse Handler

game.onMouse((event) => {
  // event: { x, y, button, action }
  if (event.action === 'click') {
    handleClick(event.x, event.y);
  }
});

Action System

Map multiple keys/buttons to named actions:

game.defineActions([
  { action: 'move_up', keys: ['up', 'w', 'k'] },
  { action: 'move_down', keys: ['down', 's', 'j'] },
  { action: 'move_left', keys: ['left', 'a', 'h'] },
  { action: 'move_right', keys: ['right', 'd', 'l'] },
  { action: 'shoot', keys: ['space'], mouseButtons: [0] },
  { action: 'interact', keys: ['e', 'enter'] },
]);

// Check action state
game.onUpdate((dt) => {
  if (game.isActionActive('move_up')) player.y -= speed * dt;
  if (game.isActionActive('move_down')) player.y += speed * dt;
  if (game.isActionActive('shoot')) fireBullet();
});

Game Loop

Variable Timestep (UI, movement)

game.onUpdate((deltaTime) => {
  // deltaTime is seconds since last frame
  playerX += velocityX * deltaTime;
  playerY += velocityY * deltaTime;
  updateAnimations(deltaTime);
});

Fixed Timestep (Physics, deterministic logic)

const game = createGame({
  fixedTimestep: {
    tickRate: 60,             // 60 physics ticks per second
    maxUpdatesPerFrame: 5,    // Prevent spiral of death
    interpolate: true,        // Smooth between ticks
  },
});

game.onFixedUpdate((fixedDt, tick) => {
  // fixedDt is always 1/60 (or 1/tickRate)
  // tick is the current tick number
  applyPhysics(fixedDt);
  checkCollisions();
});

Render Callback

game.onRender((alpha) => {
  // alpha is interpolation factor (0-1) between physics ticks
  // Use for smooth rendering when using fixed timestep
  const renderX = prevX + (currX - prevX) * alpha;
  const renderY = prevY + (currY - prevY) * alpha;
  drawPlayer(renderX, renderY);
});

Lifecycle

game.start();              // Start the game loop
game.stop();               // Stop the game loop
game.pause();              // Pause (loop still runs, logic skipped)
game.resume();             // Resume from pause
game.quit();               // Full cleanup and exit

// State queries
game.isRunning();          // Is the loop active?
game.isPaused();           // Is the game paused?

// Performance stats
const stats = game.getStats();
// { fps, frameTime, updateTime, renderTime, entityCount }

ECS World Access

For advanced use, access the underlying blECSd world:

import { addEntity, addComponent, hasComponent } from 'blecsd';
import { Position, Velocity } from 'blecsd/components';

// Access world directly
const eid = addEntity(game.world);
addComponent(game.world, eid, Position);
addComponent(game.world, eid, Velocity);
Position.x[eid] = 40;
Velocity.x[eid] = 2;

Common Game Patterns

Roguelike Movement

const game = createGame({ title: 'Roguelike', alternateScreen: true });

let playerX = 40, playerY = 12;

game.defineActions([
  { action: 'up', keys: ['up', 'k'] },
  { action: 'down', keys: ['down', 'j'] },
  { action: 'left', keys: ['left', 'h'] },
  { action: 'right', keys: ['right', 'l'] },
]);

game.onUpdate(() => {
  if (game.isActionActive('up')) playerY--;
  if (game.isActionActive('down')) playerY++;
  if (game.isActionActive('left')) playerX--;
  if (game.isActionActive('right')) playerX++;
});

game.onKey('q', () => game.quit());
game.start();

Simple Physics Game

const game = createGame({
  targetFPS: 60,
  fixedTimestep: { tickRate: 60, maxUpdatesPerFrame: 3, interpolate: true },
});

let ballX = 40, ballY = 12, velX = 10, velY = 5;

game.onFixedUpdate((dt) => {
  ballX += velX * dt;
  ballY += velY * dt;

  // Bounce off walls
  if (ballX <= 0 || ballX >= 79) velX *= -1;
  if (ballY <= 0 || ballY >= 23) velY *= -1;
});

game.start();

Dashboard with Stats

const game = createGame({ title: 'Dashboard' });

const fpsText = game.createText({
  position: { x: 0, y: 0 },
  dimensions: { width: 20, height: 1 },
});

game.onUpdate(() => {
  const stats = game.getStats();
  setText(game.world, fpsText, `FPS: ${stats.fps.toFixed(1)}`);
});

game.start();

Best Practices

1. Use defineActions for game input. Map multiple keys to actions instead of checking individual keys everywhere.
2. Use fixed timestep for physics. Variable timestep causes non-deterministic physics. Use fixedTimestep config and onFixedUpdate.
3. Access game.world for advanced ECS. The game API is a convenience wrapper. For full power, use the blECSd core APIs on game.world.
4. Set maxUpdatesPerFrame to prevent spiral of death when the game can't keep up.
5. Use interpolate: true with fixed timestep for smooth rendering between physics ticks.
6. Clean up with game.quit(). This restores the terminal state (cursor, alternate screen, mouse).
7. All blECSd rules apply. No classes, no this, pure functions, early returns, Zod validation at boundaries.