Camera System

The camera system controls what portion of a cell is visible during play mode. It enables viewport framing, multi-cell scrolling, subject following with dead zones, and zoom.

Quick Reference

Coordinate System

The camera operates in the unified coordinate system:

• 1×1 cell: Coordinates span (0,0) to (1,1)
• N×M cell: Coordinates span (0,0) to (N,M)
• Viewport height: Always 1 unit at zoom=1
• Viewport width: Depends on aspect ratio (e.g., 1.78 units for 16:9)

Viewport Size

The viewport size in coordinate units is:

viewportWidth  = aspectRatio / zoom
viewportHeight = 1 / zoom

Examples at zoom=1:

Examples at zoom=2 (200%):

Camera Preview

Toggle camera preview in build mode:

• Press C key
• View menu → Camera Preview

When preview is visible:

• Drag frame: Move initial camera position
• Drag corners: Resize (change zoom level)
• Click aspect label: Cycle through presets
• Right-click: Open context menu

Grid Snapping (Shift+Drag)

In multi-cell (N×M) cells, hold Shift while resizing to snap the viewport to cell boundaries:

• Viewport height snaps to integer values (1, 2, 3...)
• Useful for showing exactly 1, 2, or 3 rows at a time

Aspect Ratio

Camera aspect ratio defines the viewport shape. Default is 1:1 (square).

Available presets:

Set via:

• Click aspect label in camera preview to cycle
• Right-click → Aspect Ratio submenu
• Game Settings → Camera Aspect Ratio (project-wide default)

Initial Position

Each cell stores its own initial camera position (X, Y, and zoom level). Set by dragging the camera frame in preview mode. When play mode starts, the camera initializes to this position.

For 1×1 cells, initial position is typically (0.5, 0.5) - centered on the cell.

For larger cells (N×M), position the camera to show the desired starting area.

Subject Following

Objects with subject: true are tracked by the camera. The camera adjusts to keep subjects visible.

Designating Subjects

set Player.subject true    # Camera follows this object
set Player.subject false   # Stop following

Multiple subjects: Camera tracks the centroid of all subjects.

Camera Behavior

When subjects exist:

1. Camera initializes centered on subject centroid
2. Camera follows subjects as they move
3. Dead zone controls how tightly camera tracks

Dead Zone

The dead zone is a centered region of the viewport where subjects can move freely without triggering camera movement.

Configuration

Set in Game Settings → Camera Dead Zone (0.0 to 1.0):

How It Works

Dead zone is always centered in the viewport:

• With deadZone=0.4, subject can be anywhere from 30%-70% of viewport
• When subject exits dead zone, camera follows to keep subject at edge

┌─────────────────────────────┐
│         (camera moves)       │
│    ┌───────────────────┐    │
│    │   Dead Zone        │    │
│    │   (no movement)    │    │
│    └───────────────────┘    │
│         (camera moves)       │
└─────────────────────────────┘

Canvas Dragging

For cells larger than the viewport (MxN cells), users can drag empty space to manually pan the camera.

How It Works

1. Click and drag on empty canvas area (not on any object)
2. Camera pans with the drag movement
3. When released, camera snaps back to center on subject (if one exists)

Configuration

Canvas dragging is enabled by default for MxN cells. Disable it per-cell via script:

set Cell.canvasDraggable false    # Disable manual panning
set Cell.canvasDraggable true     # Re-enable

Behavior Notes

• With subject: Camera pans during drag, then recenters on subject when released
• Without subject: Camera stays at the new position after drag
• Object drag: When dragging objects (with draggable property), camera pauses following to prevent erratic movement

Multi-Cell Scrolling

For cells larger than the viewport (N×M where N > viewport width or M > viewport height), the camera scrolls to follow subjects.

Camera Offset

The camera tracks scroll position as an offset in "viewport units":

offsetX = viewportLeft / viewportWidth
offsetY = viewportTop / viewportHeight

Where viewportLeft and viewportTop are the top-left corner coordinates of the visible area.

Bounds

Camera is clamped to cell bounds - it won't scroll past edges:

• Minimum offset: (0, 0) - viewport at top-left
• Maximum offset: varies based on cell size and viewport

Examples

Center on Player Start

Position camera preview centered on where player spawns:

1. Press C to show preview
2. Drag frame to center on player object
3. Play mode will start with this view

Zoom In on Action

For a close-up view:

1. Drag corner handles inward to increase zoom
2. Position frame over focal point
3. Objects appear larger at runtime

Scrolling Platformer

For a 6×1 horizontal level:

1. Create 6×1 cell
2. Place subject (player) near left
3. Camera will scroll as player moves right
4. Set dead zone to 0.4 for comfortable tracking

Tall Dungeon

For a 2×4 vertical dungeon:

1. Create 2×4 cell
2. Set aspect ratio to 9:16 (mobile portrait)
3. Camera scrolls vertically as subject moves