Toubani (tourterelle)

A small TypeScript 2D game helper built on top of the ouider bridge. It wraps ODOM canvas APIs with a lightweight game loop, asset pipeline, sprite/scene graph utilities, tile rendering, simple physics/collision helpers, camera controls, and Web Audio playback.

Features

• Simple game loop with lifecycle hooks (preload, setup, update, draw)
• Asset manager for images, sprite sheets, and decoded audio buffers
• Sprite sheets and animations, plus a scene graph for transforms/parallax
• Tile map rendering with camera-aware culling
• Basic input handling (keyboard and mouse pressed/held state)
• Minimal physics for AABB bodies on a tilemap and tag-based collision rules
• Camera helper for pan/zoom/anchor transforms
• Web Audio playback via ouider (no direct DOM audio)

Installation

npm install
npm run build   # bundles to dist/ via tsup

Toubani expects to run inside an ouider environment. Your app should already initialize ouider (e.g. OUID.config() in your bootstrap).

Quick start

Create a canvas (provided by ouider) and hand it to tulon:

import { tulon, GameContext } from "toubani";
import { ODOM } from "ouider";

const canvas = new ODOM.CanvasElement(/* ouider element */);

const game = tulon({
  canvas,
  preload(assets) {
    assets.image("player", "/player.png");
    assets.sound("step", "/step.mp3");
  },
  setup({ world, assets }) {
    // stash reusable objects on world for later frames
    world.playerImage = assets.getImage("player");
  },
  update({ dt, input, audio }) {
    if (input.isPressed("Space")) {
      audio.play("step", { volume: 0.6 });
    }
  },
  async draw({ ctx2d, canvas }) {
    const w = await canvas.width();
    const h = await canvas.height();
    ctx2d.clearRect(0, 0, w, h);
    ctx2d.fillStyle = "#20262e";
    ctx2d.fillRect(0, 0, w, h);
    // draw stuff...
  },
});

await game.init();
game.start();

Library modules

• Game/core: Game, tulon, and the GameConfig/GameContext contracts in src/game.ts and src/core.ts.
• Assets/audio: AssetManager loads images/sounds and builds sprite sheets; AudioManager decodes and plays sounds through Web Audio via ouider.
• Sprites/scene: SpriteSheet, SpriteAnimation, Sprite, SpriteLayer, and a small scene graph (Scene, SceneNode, SpriteNode) for nested transforms.
• Tiles/camera: TileRenderer and helpers for tile maps/tilesets, plus Camera2D for pan/zoom/rotation with configurable focus anchors.
• Physics/collision: PhysicsBody for AABB tile collisions with gravity/friction and CollisionSystem for tag-based collider handlers.
• Input: InputManager tracks key and mouse pressed/held state per frame.

Examples

See examples/simple for runnable demos:

• src/Game.ts: side-scroller style scene showing tile rendering, physics, camera follow, and sprite animations.
• src/checkers/checkers.ts: simple checkers board rendered on the canvas using camera transforms and click handling.

Each example has its own package.json/webpack config; install and run from examples/simple to try them in an ouider host.

Developing

• Build: npm run build (tsup → dist/)
• TypeScript config: tsconfig.json targets CommonJS output for the bundled library.

Notes

• Audio uses Web Audio via ouider’s AudioContext bridge; sounds are fetched through OUID.fetch, decoded once, and played from buffers (no DOM audio elements).
• Assets cache image sizes on load to support sprite and tile calculations.