Skip to content

A fast 2D and 3D game engine — TypeScript SDK, C++/WebAssembly core, visual editor. Ship one project to web, desktop, WeChat MiniGames, playable ads, and native Android / iOS.

11.3 KB
Raw Blame
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
/**
 * @file    CameraDirector.ts
 * @brief   The camera director — picks the active view target among the scene's
 *          cameras and BLENDS smoothly between targets over time, the way UE's
 *          APlayerCameraManager (SetViewTargetWithBlend) and Unity Cinemachine's
 *          Brain do. It resolves ONE main point-of-view per frame (the previous
 *          target's POV lerped toward the new target's), which the camera plugin
 *          builds into the rendered view. Cameras stay declarative view defs; the
 *          director is the runtime that selects + transitions between them.
 */
import type { App } from '../app/app';
import { defineResource } from '../ecs/resource';
import { applyEasing, EasingType } from '../animation/Easing';
import type { CameraPOV } from './CameraPlugin';

/** Easing for a view-target transition. */
export const BlendCurve = {
  Linear: 0,
  EaseIn: 1,
  EaseOut: 2,
  EaseInOut: 3,
} as const;
export type BlendCurve = (typeof BlendCurve)[keyof typeof BlendCurve];

export function applyCurve(curve: number, t: number): number {
  const x = t < 0 ? 0 : t > 1 ? 1 : t;
  // BlendCurve 0..3 aligns with Easing's Linear/EaseInQuad/EaseOutQuad/EaseInOutQuad
  // (identical formulas) — delegate so the easing math lives in one place.
  return applyEasing(curve as EasingType, x);
}

/** Signed shortest angular delta a→b (radians), so a blend never spins the long way. */
function shortAngle(a: number, b: number): number {
  const TWO_PI = Math.PI * 2;
  let d = (b - a) % TWO_PI;
  if (d > Math.PI) d -= TWO_PI;
  if (d < -Math.PI) d += TWO_PI;
  return d;
}

/** Interpolate two POVs. Continuous fields lerp; discrete ones snap to the target. */
export function lerpPOV(a: CameraPOV, b: CameraPOV, t: number): CameraPOV {
  const l = (x: number, y: number) => x + (y - x) * t;
  return {
    entity: b.entity,
    isActive: b.isActive,
    x: l(a.x, b.x),
    y: l(a.y, b.y),
    z: l(a.z, b.z),
    rotation: a.rotation + shortAngle(a.rotation, b.rotation) * t,
    projection: t < 0.5 ? a.projection : b.projection, // discrete: flip at the midpoint
    orthoSize: l(a.orthoSize, b.orthoSize),
    fov: l(a.fov, b.fov),
    near: l(a.near, b.near),
    far: l(a.far, b.far),
    viewport: b.viewport,
    clearFlags: b.clearFlags,
    priority: b.priority,
    pixelPerfect: t < 0.5 ? a.pixelPerfect : b.pixelPerfect, // discrete: flip at the midpoint
    cullingMask: b.cullingMask, // discrete: the target camera decides what it shows
    renderTarget: b.renderTarget, // discrete: a blend cannot be half in a texture
  };
}

function clonePOV(p: CameraPOV): CameraPOV {
  return { ...p, viewport: { ...p.viewport } };
}

/** A transient camera shake — a decaying view-space perturbation (UE modifier). */
export interface ActiveShake {
  amplitude: number; // positional, world units
  rotation: number; // rotational, radians
  frequency: number; // Hz
  duration: number; // seconds
  startTime: number; // seconds; -1 until first applied
  seed: number; // decorrelates concurrent shakes
}

export interface CameraDirectorState {
  /** Committed view-target entity, or -1 → fall back to the active/priority camera. */
  target: number;
  // Pending setViewTarget request, applied on the next resolve.
  hasPending: boolean;
  pendingTarget: number;
  pendingTime: number; // seconds
  pendingCurve: number;
  // Active blend.
  blending: boolean;
  from: CameraPOV | null;
  startTime: number; // seconds (engine elapsed clock)
  duration: number; // seconds
  curve: number;
  /** Last resolved main POV — also the snapshot source when a new blend starts. */
  currentMain: CameraPOV | null;
  /** Active transient shakes (applied to the rendered POV, never to the Transform). */
  shakes: ActiveShake[];
  shakeSeq: number;
  /**
   * The view a playing timeline's camera track asks for, set every step it has one. While present it
   * is the view and `setViewTarget` waits; when the track has nothing to say the scene's own camera is
   * the view again.
   */
  timelineShot: TimelineShot | null;
  /** The timeline player that set `timelineShot`, so only it can take it back. */
  timelineOwner: number;
}

/** A shot between two cameras, `weight` of the way from `from` (or none) to `to`. */
export interface TimelineShot {
  from: number | null;
  to: number;
  weight: number;
  curve: number;
}

export const DEFAULT_DIRECTOR: CameraDirectorState = {
  target: -1,
  hasPending: false,
  pendingTarget: -1,
  pendingTime: 0,
  pendingCurve: BlendCurve.EaseInOut,
  blending: false,
  from: null,
  startTime: 0,
  duration: 0,
  curve: BlendCurve.EaseInOut,
  currentMain: null,
  shakes: [],
  shakeSeq: 0,
  timelineShot: null,
  timelineOwner: -1,
};

/** A fresh director state (own arrays) — use per App, not the shared default. */
export function createDirectorState(): CameraDirectorState {
  return { ...DEFAULT_DIRECTOR, from: null, currentMain: null, shakes: [] };
}

export const CameraDirector = defineResource<CameraDirectorState>(
  { ...DEFAULT_DIRECTOR },
  'CameraDirector',
);

/**
 * Where director commands land: the App (host code) or the CameraDirector
 * resource state itself (systems — `Res(CameraDirector)`).
 */
export type CameraDirectorHost = App | CameraDirectorState;

function directorOf(host: CameraDirectorHost): CameraDirectorState {
  return typeof (host as App).getResource === 'function'
    ? (host as App).getResource(CameraDirector)
    : (host as CameraDirectorState);
}

/**
 * Switch the active view target, optionally blending over `time` seconds with an
 * easing `curve`. Records intent; the director applies it on the next frame
 * (snapshotting the current view as the blend start). `time<=0` (or no prior
 * view) is an instant cut. Pass the App from host code, or the
 * `Res(CameraDirector)` state from inside a system.
 */
export function setViewTarget(
  host: CameraDirectorHost,
  entity: number,
  opts?: { time?: number; curve?: number },
): void {
  const dir = directorOf(host);
  dir.hasPending = true;
  dir.pendingTarget = entity;
  dir.pendingTime = opts?.time ?? 0;
  dir.pendingCurve = opts?.curve ?? BlendCurve.EaseInOut;
}

/**
 * A playing timeline's camera track says which camera is the view (and, across an overlap, how far one is
 * blended into the next). Pass `null` to give the view back: only the player that set a shot can clear it.
 */
export function setTimelineShot(host: CameraDirectorHost, owner: number, shot: TimelineShot | null): void {
  const dir = directorOf(host);
  if (shot) {
    dir.timelineShot = shot;
    dir.timelineOwner = owner;
  } else if (dir.timelineOwner === owner) {
    dir.timelineShot = null;
    dir.timelineOwner = -1;
  }
}

/**
 * Trigger a transient camera shake on the active view — a decaying perturbation
 * applied to the rendered POV only (never to a camera's Transform, so it always
 * recovers and never dirties the scene). The UE `StartCameraShake` analog.
 * Pass the App from host code, or the `Res(CameraDirector)` state from a system.
 */
export function shakeCamera(
  host: CameraDirectorHost,
  opts?: { amplitude?: number; rotation?: number; frequency?: number; duration?: number },
): void {
  const dir = directorOf(host);
  dir.shakes.push({
    amplitude: opts?.amplitude ?? 12,
    rotation: opts?.rotation ?? 0,
    frequency: opts?.frequency ?? 22,
    duration: opts?.duration ?? 0.4,
    startTime: -1,
    seed: dir.shakeSeq++,
  });
}

// Deterministic smooth pseudo-noise in ~[-1, 1] (two decorrelated sines).
const shakeNoise = (t: number, seed: number): number =>
  Math.sin(t + seed * 1.3) * 0.6 + Math.sin(t * 1.7 + seed * 2.9) * 0.4;

/**
 * Apply + age the active shakes, returning the POV offset for rendering. Drops
 * expired shakes. Mutates the shake list, so it runs only on the advancing
 * (render) resolve — the peek resolve leaves the view un-shaken (so screen<->world
 * doesn't jitter while the camera shakes).
 */
function applyShakes(dir: CameraDirectorState, pov: CameraPOV, now: number): CameraPOV {
  if (dir.shakes.length === 0) return pov;
  let ox = 0;
  let oy = 0;
  let orot = 0;
  const alive: ActiveShake[] = [];
  for (const s of dir.shakes) {
    if (s.startTime < 0) s.startTime = now;
    const e = now - s.startTime;
    if (e >= s.duration || s.duration <= 0) continue; // expired → dropped
    const decay = 1 - e / s.duration;
    const phase = 2 * Math.PI * s.frequency * e;
    ox += s.amplitude * decay * shakeNoise(phase, s.seed);
    oy += s.amplitude * decay * shakeNoise(phase, s.seed + 11);
    orot += s.rotation * decay * shakeNoise(phase, s.seed + 23);
    alive.push(s);
  }
  dir.shakes = alive;
  if (ox === 0 && oy === 0 && orot === 0) return pov;
  return { ...pov, x: pov.x + ox, y: pov.y + oy, rotation: pov.rotation + orot };
}

/** The active camera by policy: isActive wins (authoritative), else highest priority. */
function pickActive(candidates: CameraPOV[]): CameraPOV {
  const active = candidates.find((c) => c.isActive);
  if (active) return active;
  let best = candidates[0];
  for (const c of candidates) if (c.priority > best.priority) best = c;
  return best;
}

/**
 * Resolve the main POV for this frame from the full-frame camera candidates.
 * `advance` runs the state machine (consume a pending target, tick the blend);
 * pass false to just peek the last resolved POV (so a second consumer per frame
 * — the early UICameraInfo sync — doesn't double-advance the blend).
 */
export function resolveMainPOV(
  dir: CameraDirectorState,
  candidates: CameraPOV[],
  now: number,
  advance: boolean,
): CameraPOV | null {
  if (candidates.length === 0) {
    if (advance) dir.currentMain = null;
    return null;
  }
  if (!advance) {
    return dir.currentMain ?? pickActive(candidates);
  }

  // Apply a pending setViewTarget — snapshot the current view as the blend start.
  if (dir.hasPending) {
    dir.hasPending = false;
    if (dir.pendingTime > 0 && dir.currentMain) {
      dir.from = clonePOV(dir.currentMain);
      dir.blending = true;
      dir.startTime = now;
      dir.duration = dir.pendingTime;
      dir.curve = dir.pendingCurve;
    } else {
      dir.blending = false;
      dir.from = null;
    }
    dir.target = dir.pendingTarget;
  }

  const shot = dir.timelineShot;
  const shotTo = shot ? candidates.find((c) => c.entity === shot.to) : undefined;
  if (shot && shotTo) {
    const shotFrom = shot.from === null ? undefined : candidates.find((c) => c.entity === shot.from);
    const cut = shotFrom ? lerpPOV(shotFrom, shotTo, applyCurve(shot.curve, shot.weight)) : shotTo;
    dir.blending = false;
    dir.from = null;
    dir.currentMain = cut;
    return applyShakes(dir, cut, now);
  }

  const targetPOV =
    (dir.target >= 0 ? candidates.find((c) => c.entity === dir.target) : undefined) ??
    pickActive(candidates);

  let main: CameraPOV;
  if (dir.blending && dir.from) {
    const elapsed = now - dir.startTime;
    if (dir.duration <= 0 || elapsed >= dir.duration) {
      dir.blending = false;
      dir.from = null;
      main = targetPOV;
    } else {
      main = lerpPOV(dir.from, targetPOV, applyCurve(dir.curve, elapsed / dir.duration));
    }
  } else {
    main = targetPOV;
  }

  // currentMain stays the pre-shake view (blend snapshot + screen<->world use it);
  // shake is a render-only transient offset on top.
  dir.currentMain = main;
  return applyShakes(dir, main, now);
}