@carrot/engine-framework-cameras

ts

Camera behaviours for the Carrot engine framework - wraps the low-level Camera from @carrot/engine-renderer in a framework Behaviour.

Installation

npm install @carrot/engine-framework-cameras

Architecture / How It Works

CameraBehaviour

CameraBehaviour extends Behaviour and owns a low-level Camera instance from @carrot/engine-renderer. It provides four static factories for common projection setups:

• ortho2d() - 2D orthographic projection sized to the engine canvas. Subscribes to engine.onResize and auto-rebuilds the projection matrix on each resize.
• perspective(config) - standard perspective projection from fov, aspect, near, far.
• orthographic(bounds) - explicit orthographic bounds (left/right/bottom/top/near/far).
• custom(matrix) - raw projection matrix, no automatic management.

Transform Sync

For 3D entities, CameraBehaviour syncs the entity's Transform3D world matrix into the camera's view matrix (as the inverse of the world matrix) each frame. For 2D entities, the view matrix is identity - the ortho projection handles positioning directly.

Resize Handling

The ortho2d mode listens for engine resize events and rebuilds the orthographic projection to match the new canvas dimensions. Other projection modes are not affected by resize.

Bundle Registration

registerCameraBehaviours(registry) registers the CameraBehaviour type on a BehaviourRegistry, enabling template-based instantiation.

Dependencies

Package	Used For
@carrot/engine-framework	Behaviour, BehaviourRegistry
@carrot/engine-renderer	Camera, ClearFlags
@carrot/engine-textures	RenderTexture for render-to-texture targets
@carrot/engine	Engine resize events
@carrot/maths-geometry	Matrix4x4 for custom projections
@carrot/colors	ColorRgbLike for clear colour
@carrot/signals	Signal subscription for resize events

Build

npm run build    # runs tsc

Output goes to dist/. Package is ESM ("type": "module").

---

Usage Guide

Camera behaviours for the Carrot engine framework.

Import

import {
  CameraBehaviour, registerCameraBehaviours,
} from '@carrot/engine-framework-cameras';

import type {
  CameraProjectionMode, OrthographicBounds, PerspectiveConfig,
} from '@carrot/engine-framework-cameras';

Common Patterns

1. Basic 2D camera

import { Entity } from '@carrot/engine-framework';
import { CameraBehaviour } from '@carrot/engine-framework-cameras';

const cam = Entity.create2d('MainCamera');
cam.addBehaviour(CameraBehaviour.ortho2d());
scene.addEntity(cam);

The ortho2d camera auto-rebuilds its projection when the engine resizes - no manual handling needed.

2. Perspective camera

const cam3d = Entity.create3d('Camera3D');
cam3d.addBehaviour(CameraBehaviour.perspective({
  fov: 60,
  aspect: 16 / 9,
  near: 0.1,
  far: 1000,
}));
scene.addEntity(cam3d);

3. Orthographic camera with explicit bounds

const minimap = Entity.create2d('MinimapCamera');
minimap.addBehaviour(CameraBehaviour.orthographic({
  left: -50, right: 50,
  bottom: -50, top: 50,
  near: 0.1, far: 100,
}));
scene.addEntity(minimap);

4. Custom projection matrix

const cam = Entity.create3d('CustomCam');
cam.addBehaviour(CameraBehaviour.custom(myProjectionMatrix));

5. Configuring clear settings and render order

import { ClearFlags } from '@carrot/engine-renderer';

const camBehaviour = CameraBehaviour.ortho2d();
camBehaviour.clearFlags = ClearFlags.All;
camBehaviour.clearColor = { r: 0.1, g: 0.1, b: 0.15, a: 1 };
camBehaviour.renderOrder = 0; // render first

6. Rendering to a texture

const camBehaviour = CameraBehaviour.ortho2d();
camBehaviour.target = myRenderTexture; // null = default framebuffer

7. Switching projection at runtime

const camBehaviour = entity.getBehaviour(CameraBehaviour)!;

// Switch to perspective
camBehaviour.setPerspective({ fov: 60, aspect: 16 / 9, near: 0.1, far: 500 });

// Switch back to auto-resizing 2D ortho
camBehaviour.setOrtho2d();

8. Register camera behaviours for templates

import { registerCameraBehaviours } from '@carrot/engine-framework-cameras';

registerCameraBehaviours(game.behaviours);

const prefab: EntityTemplate = {
  name: 'Camera',
  transform: { type: '2d', x: 0, y: 0 },
  behaviours: [
    { type: 'cameraBehaviour', properties: { projection: 'ortho2d' } },
  ],
};

9. Layer masking

const camBehaviour = CameraBehaviour.ortho2d();
camBehaviour.layerMask = (1 << 0) | (1 << 2); // only render layers 0 and 2