Gameable Engine

Add a top-down camera ​

Goal ​

Pan, rotate and zoom a fixed-tilt perspective view for an RPG or strategy game.

Files you will edit ​

  • src/game.ts

Steps ​

  1. Create the rig during game initialization and update it once per tick:

    ts
    import { createTopDownCamera, defineGame, type TopDownCamera } from 'gameable';

let rig: TopDownCamera;
export default defineGame({
  init() {
    rig = createTopDownCamera({
      distance: 14,
      pitch: (55 * Math.PI) / 180,
      bounds: { min: [-50, -50], max: [50, 50] },
    });
    rig.focusOn({ x: 0, y: 0, z: 0 });
  },
  systems: [(ctx) => rig.update(ctx, ctx.dt)],
});

    Do not also declare player.camera in defineGame. The host gives that player camera precedence and skips the game's frame camera. The rig writes the frame through ctx.camera.set() and ctx.camera.lookAt().

  2. Use WASD or arrows to pan, Q/E to rotate, the wheel to zoom, and middle-button drag to grab the ground. Touch drag pans and pinch zooms. edgePan: true enables edge scrolling; it defaults to false. Pan speed scales with distance. Yaw zero places the eye on +Z; forward pan moves toward -Z. Pitch is radians below the horizon; Math.PI / 2 looks straight down.

  3. Call rig.follow(entity) to track its Transform. Pan input breaks follow; rig.follow(0) stops it explicitly. pan(dx, dz) uses camera-relative metres, with positive dz forward. zoom(factor) multiplies distance, clamped to minDistance (6) and maxDistance (40). Save rig.state as JSON and restore with Object.assign(rig.state, saved); keep methods outside saved actor state.

    For an actor-owned view, add topDownCamera(options) to a defineActor class that spreads CameraActor.spec, then select it with activateCamera(ctx, actor). Its initial focus is the actor position, and its pose is saved automatically. Only the active camera's component reads controls and writes the frame.

Verify ​

Run npm run dev in your game. Pan, rotate, zoom to both limits, and drag on touch. Confirm that follow breaks when panning and that focus stays within bounds.

See also ​