0.6.3

1681 Engine

A 2D game engine for the web, built on PixiJS 8 and written in TypeScript, for games in any art style: hand-drawn, HD, vector or pixel art. Pixel art gets a module of its own, Dither.

It grew out of a shipped online action RPG, so its pieces were made for a real game under real load: a fast ECS, a fixed-step simulation a server can replay bit for bit, Tiled maps, input that works the same on keyboard, gamepad and touch, and for pixel art, effects painted on the world's own pixel grid and dithered lighting.

import { Engine, Scene, defineComponent, system } from '1681-engine';

const Position = defineComponent<{ x: number; y: number }>('Position');

class Level extends Scene {
  override onEnter() {
    this.world.spawn([Position, { x: 0, y: 0 }]);
    this.world.addSystem(
      system('drift', 'fixed', ({ world, dt }) => {
        world.each(Position, (_e, p) => (p.x += 30 * dt));
      }),
    );
  }
}

const engine = await Engine.create({ parent: document.body });
await engine.scenes.replace(new Level());

Status: 0.x, early. The API will change between minor versions until 1.0. See CHANGELOG.md.

Entry points

The core never imports the pixel module (a test holds it to that), so a game that does not use it does not ship it. React and React DOM (19) are optional peer dependencies needed only by 1681-engine/react; nothing else imports React. Start a pixel-art game with Engine.create({ pixelPerfect: true }): sharp textures and a camera that lands on whole pixels. Without it, textures are smooth and drawn at the screen's own density.

Features

A React UI

import { createRoot } from 'react-dom/client';
import { ConfirmDialog, Panel, TitleTips, UiProvider, askConfirm, injectBaseCss } from '1681-engine/react';

injectBaseCss(); // the base stylesheet, first in <head>, so the game's own CSS wins
// theme it with custom properties: frames are 9-slice border-images the game draws
document.documentElement.style.cssText += `
  --e1681-font: 'My Pixel Font'; --e1681-accent: #f0c060;
  --e1681-frame: url(/ui/frame.svg); --e1681-frame-slice: 16 20 20 16 fill; --e1681-frame-width: 16px 20px 20px 16px;`;

createRoot(document.getElementById('ui')!).render(
  <UiProvider labels={{ cancel: 'Annuler', ok: 'OK' }}>
    <Panel title="Inventory" onClose={close} width={420}>…</Panel>
    <ConfirmDialog />
    <TitleTips />
  </UiProvider>,
);
if (await askConfirm('Drop the sword?')) drop();

Windows and dialogs are fitted into the screen by fitToViewport and placed in whole pixels; tooltips and the select's list by placeTooltip and listWidth. On a touch device (isTouchUi, or UiProvider touch) a Panel is a full-screen sheet and tooltips are off. Every word the kit prints is a prop or a labels entry with an English default.

Install

npm install 1681-engine pixi.js

pixi.js (8.6 or later) is a peer dependency. The package is ESM only and ships its TypeScript types. On a server (the multiplayer Room) it needs Node 22 or later.

The engine renders with WebGL 2 by default. Engine.create({ preference: 'webgpu' }) opts into WebGPU, which is experimental here: it falls back to WebGL where the browser lacks it, but has not been profiled the way the WebGL path has.

Documentation

https://phadec.github.io/1681-engine/ — the guide, the API reference and the examples running live.

The documentation site (guide, API reference generated from the source, live examples) is built with npm run docs:build and published to GitHub Pages by .github/workflows/docs.yml; npm run docs:dev serves it locally.

• Getting started: an engine, a scene, entities and systems, assets, a Tiled map, input, the camera, a rigged character, light and music, and multiplayer, step by step.
• Architecture: how the frame loop, scenes, ECS and rendering fit together, and the rules that keep it fast.
• A page per module: input, physics, navigation, particles, game feel, ambient, transitions, post-processing, lobby and matchmaking, UI, React kit, localisation, saves, diagnostics and debug, behaviour trees, dialogue, mobile.
• Examples, run with npm run dev:
  • top-down: a Tiled map, asset loading, an animated hero, input actions on keyboard, gamepad and touch, camera follow.
  • platformer: physics from a tile grid (crates, a moving platform, one-way planks, sensor coins), particles, a canvas HUD and pause dialog, a versioned save, scene transitions, two languages, rebindable keys and a debug overlay.
  • night-garden: smooth vector art, a rigged hero animated by blended poses, a lantern and fireflies in the dark.
  • pixel-dungeon: the pixel module: dithered torchlight, a carried light, slimes that evaporate into their own pixels.
  • ecs-stress: tens of thousands of bodies on typed-array components, with the frame rate and step time.
  • multiplayer: npm run example:server, then two tabs: prediction, reconciliation and interpolation.
  • physics-toys: bodies that turn (crates, balls, polygons, a spinning bar) under bloom, a vignette and the other effects.
  • lobby: npm run example:lobby, then the page: rooms, codes, ready flags, chat, the queue and a ready check.
  • walk-room: the smallest whole game, with pixel effects.
  • dialogue: a playground for dialogue scripts, checked as they are typed and played with their variables in view.

Develop

npm install
npm run dev        # examples at http://127.0.0.1:5180/
npm test           # unit tests under node
npm run typecheck  # sources and tests
npm run bench      # ECS benchmark
npm run build      # dist/: both ESM bundles and their .d.ts files
npm run check      # typecheck, test and build, as CI runs it
npm run docs:dev   # the documentation site, with the API reference and examples

Contributions are welcome: read CONTRIBUTING.md first.

License

MIT