@caperjs/core 0.1.0

package/src/display/Camera.ts

@@ -0,0 +1,371 @@
+import { Container, Point } from 'pixi.js';
+import { IApplication } from '../core';
+import { Application } from '../core/Application';
+import type { KeyboardEventDetail } from '../plugins';
+import { Signal } from '../signals';
+import type { ContainerLike, PointLike } from '../utils';
+import { bindAllMethods, resolvePointLike } from '../utils';
+
+type CameraConfig = {
+  container: Container;
+  minX: number;
+  maxX: number;
+  minY: number;
+  maxY: number;
+  viewportWidth: number;
+  viewportHeight: number;
+  worldWidth: number;
+  worldHeight: number;
+  target: ContainerLike | null;
+  targetPivot: Point;
+  lerp: number;
+};
+
+// require container to be set
+type OptionalCameraConfig = Partial<CameraConfig>;
+type RequiredCameraConfig = Required<Pick<CameraConfig, 'container'>>;
+type CustomCameraConfig = OptionalCameraConfig & RequiredCameraConfig;
+
+export interface ICamera {
+  onZoom: Signal<(camera?: ICamera) => void>;
+  onZoomComplete: Signal<(camera?: ICamera) => void>;
+  container: Container;
+  minX: number;
+  minY: number;
+  maxX: number;
+  maxY: number;
+  viewportWidth: number;
+  viewportHeight: number;
+  worldWidth: number;
+  worldHeight: number;
+  readonly targetPivot: Point;
+  readonly targetScale: Point;
+  readonly zooming: boolean;
+  readonly zoomLerp: number;
+  readonly lerp: number;
+  readonly target: ContainerLike | null;
+  readonly followOffset: Point;
+  app: IApplication;
+
+  follow(target: ContainerLike, offset: PointLike): void;
+
+  pan(deltaX: number, deltaY: number): void;
+
+  zoom(scale: number, lerp?: number): void;
+
+  update(): void;
+}
+
+export class Camera extends Container implements ICamera {
+  public onZoom = new Signal<(camera?: ICamera) => void>();
+  public onZoomComplete = new Signal<(camera?: ICamera) => void>();
+  public container: Container;
+  public minX: number = 0;
+  public minY: number = 0;
+  public maxX: number;
+  public maxY: number;
+  public viewportWidth: number;
+  public viewportHeight: number;
+  public worldWidth: number;
+  public worldHeight: number;
+
+  constructor(public config: CustomCameraConfig) {
+    super({ isRenderGroup: true });
+    bindAllMethods(this);
+    if (config) {
+      this.container = config.container;
+      this.addChild(this.container);
+      if (config.minX) {
+        this.minX = config.minX;
+      }
+      if (config.maxX) {
+        this.maxX = config.maxX;
+      }
+      if (config.minY) {
+        this.minY = config.minY;
+      }
+      this.viewportWidth = config.viewportWidth ?? this.app.size.width;
+      this.viewportHeight = config.viewportHeight ?? this.app.size.width;
+      this.worldWidth = config.worldWidth ?? this.viewportWidth;
+      this.worldHeight = config.worldHeight ?? this.viewportHeight;
+      this.maxX = config.maxX ?? this.worldWidth - this.viewportWidth;
+      this.maxY = config.maxY ?? this.worldHeight - this.viewportHeight;
+    }
+
+    this._targetPivot.set(this.viewportWidth * 0.5, this.viewportHeight * 0.5);
+    if (config.target) {
+      this.target = config.target;
+    }
+    this._lerp = 1;
+    this.update();
+    if (config.lerp) {
+      this.lerp = config.lerp;
+    }
+    return this;
+  }
+
+  protected _zooming: boolean = false;
+
+  get zooming(): boolean {
+    return this._zooming;
+  }
+
+  protected _zoomLerp: number = 0.1;
+
+  get zoomLerp(): number {
+    return this._zoomLerp;
+  }
+
+  protected _targetPivot: Point = new Point(0, 0);
+
+  get targetPivot(): Point {
+    return this._targetPivot;
+  }
+
+  protected _targetScale: Point = new Point(1, 1);
+
+  get targetScale(): Point {
+    return this._targetPivot;
+  }
+
+  private _lerp: number = 0;
+
+  get lerp(): number {
+    return this._lerp;
+  }
+
+  set lerp(value: number) {
+    // if the value is less than 0 or greater than 1, clamp it to the range [0, 1], and log an error
+    if (value < 0 || value > 1) {
+      throw new Error('Camera lerp value must be in the range [0, 1]');
+    }
+    this._lerp = Math.max(0, Math.min(value, 1));
+  }
+
+  protected _target: ContainerLike | null = null;
+
+  get target(): ContainerLike | null {
+    return this._target;
+  }
+
+  set target(value: ContainerLike | null) {
+    this._target = value;
+    if (this._target) {
+      this.focusOn(this._target);
+    }
+  }
+
+  protected _followOffset: Point = new Point(0, 0);
+  get followOffset(): Point {
+    return this._followOffset;
+  }
+
+  set followOffset(value: PointLike) {
+    this._followOffset = resolvePointLike(value, true);
+  }
+
+  get app(): IApplication {
+    return Application.getInstance();
+  }
+
+  follow(target: ContainerLike, offset?: PointLike) {
+    if (!offset) {
+      offset = { x: 0, y: 0 };
+    }
+    this.followOffset = offset;
+    this.target = target;
+  }
+
+  pan(deltaX: number, deltaY: number) {
+    let newPivotX = this.pivot.x + deltaX;
+    let newPivotY = this.pivot.y + deltaY;
+
+    // Clamp pivot to min and max values
+    newPivotX = Math.max(this.minX, Math.min(newPivotX, this.maxX));
+    newPivotY = Math.max(this.minY, Math.min(newPivotY, this.maxY));
+
+    this._targetPivot.set(newPivotX, newPivotY);
+  }
+
+  zoom(scale: number, lerp: number = 0.1) {
+    this._zoomLerp = lerp;
+    this._zooming = true;
+    this._targetScale.set(scale, scale);
+  }
+
+  update() {
+    this.updateZoom();
+    if (this._target) {
+      this.focusOn(this._target);
+    }
+    this.updatePosition(this._zooming);
+    if (
+      this._zooming &&
+      Math.abs(this.scale.x - this._targetScale.x) < 0.001 &&
+      Math.abs(this.scale.y - this._targetScale.y) < 0.001
+    ) {
+      this.onZoom.emit(this);
+      this._zooming = false;
+      this.scale.set(this._targetScale.x, this._targetScale.y);
+      this.onZoomComplete.emit(this);
+    } else if (this._zooming) {
+      this.onZoom.emit(this);
+    }
+  }
+
+  private focusOn(entity: ContainerLike) {
+    // Get the global position of the entity and convert it to the local position within the container.
+    const globalPosition = entity.getGlobalPosition();
+    const spritePosition = this.toLocal(globalPosition);
+
+    const posXModifier = this.position.x / this.scale.x - this.viewportWidth / 2;
+    const posYModifier = this.position.y / this.scale.y - this.viewportHeight / 2;
+
+    const offsetX = this.followOffset.x / this.scale.x;
+    const offsetY = this.followOffset.y / this.scale.y;
+
+    this._targetPivot.x = (spritePosition.x * this.scale.x + this.viewportWidth / 2) * (1 / this.scale.x) + offsetX;
+
+    const tMinX = this.viewportWidth / this.scale.x / 2 + posXModifier + this.minX - offsetX;
+    const tMaxX = this.worldWidth - this.viewportWidth / this.scale.x / 2 + posXModifier + this.maxX + offsetX;
+
+    if (this._targetPivot.x < tMinX) {
+      this._targetPivot.x = tMinX;
+    } else if (this._targetPivot.x > tMaxX) {
+      this._targetPivot.x = tMaxX;
+    }
+
+    this._targetPivot.y = (spritePosition.y * this.scale.y + this.viewportHeight / 2) * (1 / this.scale.y) + offsetY;
+
+    const tMinY = this.viewportHeight / this.scale.y / 2 + posYModifier + this.minY - offsetY;
+    const tMaxY = this.worldHeight - this.viewportHeight / this.scale.y / 2 + posYModifier + this.maxY - offsetY;
+
+    if (this._targetPivot.y < tMinY) {
+      this._targetPivot.y = tMinY;
+    } else if (this._targetPivot.y > tMaxY) {
+      this._targetPivot.y = tMaxY;
+    }
+  }
+
+  private updateZoom() {
+    const currentScaleX = this.scale.x;
+    const currentScaleY = this.scale.y;
+
+    const interpolatedScaleX = currentScaleX + this._zoomLerp * (this._targetScale.x - currentScaleX);
+    const interpolatedScaleY = currentScaleY + this._zoomLerp * (this._targetScale.y - currentScaleY);
+
+    this.scale.set(Math.max(0, interpolatedScaleX), Math.max(0, interpolatedScaleY));
+  }
+
+  private updatePosition(skipLerp: boolean = false) {
+    if (this.lerp > 0 && !skipLerp) {
+      // Current pivot positions
+      const currentPivotX = this.pivot.x;
+      const currentPivotY = this.pivot.y;
+
+      // Calculate interpolated pivot positions
+      const interpolatedPivotX = currentPivotX + this.lerp * (this._targetPivot.x - currentPivotX);
+      const interpolatedPivotY = currentPivotY + this.lerp * (this._targetPivot.y - currentPivotY);
+
+      // Set the pivot to the interpolated position to smooth out the camera movement
+      this.pivot.set(interpolatedPivotX, interpolatedPivotY);
+    } else {
+      this.pivot.set(this._targetPivot.x, this._targetPivot.y);
+    }
+
+    this.position.set(this.viewportWidth / 2, this.viewportHeight / 2);
+  }
+}
+
+export class CameraController {
+  private dragging: boolean = false;
+  private previousPointerPosition: Point | null = null;
+
+  constructor(
+    public camera: Camera,
+    public interactiveArea: Container,
+  ) {
+    bindAllMethods(this);
+    this.camera = camera;
+    this.interactiveArea = interactiveArea;
+    this.app.keyboard.onKeyDown().connect(this.handleKeyDown);
+    // Keyboard events
+
+    // Mouse and touch events
+    this.interactiveArea.on('pointerdown', this.onPointerDown.bind(this));
+    this.interactiveArea.on('pointermove', this.onPointerMove.bind(this));
+    this.app.stage.on('pointerup', this.onPointerUp.bind(this));
+    this.app.stage.on('pointerupoutside', this.onPointerUp.bind(this));
+
+    // Touch events equivalent
+    this.interactiveArea.on('touchstart', this.onPointerDown.bind(this));
+    this.interactiveArea.on('touchmove', this.onPointerMove.bind(this));
+    this.interactiveArea.on('touchend', this.onPointerUp.bind(this));
+  }
+
+  get app(): IApplication {
+    return Application.getInstance();
+  }
+
+  destroy() {
+    // Mouse and touch events
+    this.interactiveArea.removeAllListeners();
+    this.app.stage.off('pointerup', this.onPointerUp.bind(this));
+    this.app.stage.off('pointerupoutside', this.onPointerUp.bind(this));
+  }
+
+  private handleKeyDown(detail: KeyboardEventDetail) {
+    const panSpeed = 10; // Adjust pan speed as necessary
+    const zoomFactor = 1.1; // Adjust zoom factor as necessary
+
+    switch (detail.event.key) {
+      case 'ArrowUp':
+        this.camera.pan(0, -panSpeed);
+        break;
+      case 'ArrowDown':
+        this.camera.pan(0, panSpeed);
+        break;
+      case 'ArrowLeft':
+        this.camera.pan(-panSpeed, 0);
+        break;
+      case 'ArrowRight':
+        this.camera.pan(panSpeed, 0);
+        break;
+      case '+':
+        this.camera.zoom(zoomFactor);
+        break;
+      case '-':
+        this.camera.zoom(1 / zoomFactor);
+        break;
+    }
+  }
+
+  private onPointerDown(event: MouseEvent | TouchEvent) {
+    this.dragging = true;
+    this.previousPointerPosition = this.getEventPosition(event);
+  }
+
+  private onPointerMove(event: MouseEvent | TouchEvent) {
+    if (!this.dragging || !this.previousPointerPosition) return;
+
+    const currentPosition = this.getEventPosition(event);
+    const deltaX = currentPosition.x - this.previousPointerPosition.x;
+    const deltaY = currentPosition.y - this.previousPointerPosition.y;
+
+    this.camera.pan(deltaX, deltaY);
+    this.previousPointerPosition = currentPosition;
+  }
+
+  private onPointerUp() {
+    this.dragging = false;
+    this.previousPointerPosition = null;
+  }
+
+  private getEventPosition(event: MouseEvent | TouchEvent): Point {
+    if (event instanceof TouchEvent) {
+      return new Point(event.touches[0].clientX, event.touches[0].clientY);
+    } else {
+      return new Point(event.clientX, event.clientY);
+    }
+  }
+}

package/src/display/Container.ts

@@ -0,0 +1,240 @@
+import { DestroyOptions, Container as PIXIContainer, Sprite, Texture, Ticker } from 'pixi.js';
+import { Animated, Factory, WithSignals } from '../mixins';
+
+import { Application } from '../core/Application';
+import { Signal } from '../signals';
+import { SignalOrder } from '../signals/Signal';
+import type { AppTypeOverrides, PointLike, Size } from '../utils';
+import { bindAllMethods } from '../utils';
+
+/**
+ * Configuration for the Container class.
+ */
+export type ContainerConfig = {
+  autoResize: boolean;
+  autoUpdate: boolean;
+  priority: SignalOrder;
+};
+
+export const ContainerConfigKeys: (keyof ContainerConfig)[] = ['autoResize', 'autoUpdate', 'priority'];
+
+const defaultConfig: ContainerConfig = { autoResize: true, autoUpdate: false, priority: 0 };
+
+export type BackgroundConfig = {
+  color: number;
+  alpha: number;
+  width: number;
+  height: number;
+  anchor: PointLike;
+  autoResize: boolean;
+};
+
+/**
+ * Interface for the Container class.
+ */
+export interface IContainer {
+  app: AppTypeOverrides['App'];
+
+  animationContext: string | undefined;
+
+  onDestroy: Signal<() => void>;
+
+  destroy(options?: DestroyOptions): void;
+
+  added(): Promise<void> | void;
+
+  removed(): Promise<void> | void;
+
+  childAdded(child: PIXIContainer): Promise<void> | void;
+  childRemoved(child: PIXIContainer): Promise<void> | void;
+
+  resize(size?: Size): void;
+
+  update(ticker?: Ticker | number): void;
+
+  addColoredBackground(colorOrConfig?: number | Partial<BackgroundConfig>, alpha?: number): Sprite;
+}
+
+/**
+ * The Container class extends the _Container class (which includes the Animated and Factory mixins) and implements the IContainer interface.
+ * It represents a container for PIXI.js display objects.
+ */
+export class Container extends Animated(WithSignals(Factory())) implements IContainer {
+  private readonly __caper_method_binding_root = true;
+
+  public onDestroy: Signal<() => void> = new Signal();
+
+  protected __background: Sprite;
+
+  protected _animationContext: string | undefined;
+  public get animationContext(): string | undefined {
+    return this._animationContext;
+  }
+  public set animationContext(value: string) {
+    this._animationContext = value;
+  }
+
+  private __config: ContainerConfig;
+
+  public static onGlobalChildAdded = new Signal<(child: PIXIContainer) => void>();
+  public static onGlobalChildRemoved = new Signal<(child: PIXIContainer) => void>();
+
+  public static childAdded(child: PIXIContainer) {
+    Container.onGlobalChildAdded.emit(child);
+  }
+
+  public static childRemoved(child: PIXIContainer) {
+    Container.onGlobalChildRemoved.emit(child);
+  }
+
+  /**
+   * Get the application instance.
+   */
+  public get app(): AppTypeOverrides['App'] {
+    return Application.getInstance();
+  }
+
+  /**
+   * The constructor for the Container class.
+   * @param config - The configuration for the container.
+   */
+  constructor(config: Partial<ContainerConfig> = {}) {
+    super();
+    this.__config = { ...defaultConfig, ...config };
+    // Bind all methods of this class to the current instance.
+    bindAllMethods(this);
+    // Add an event listener for the 'added' event.
+    this.on('added', this._added);
+    this.on('removed', this._removed);
+    this.on('childAdded', this._childAdded);
+    this.on('childRemoved', this._childRemoved);
+  }
+
+  public addColoredBackground(colorOrConfig: number | Partial<BackgroundConfig> = 0x0, alpha: number = 1): Sprite {
+    const defaultConfig = {
+      color: 0x0,
+      width: this.app.size.width,
+      height: this.app.size.height,
+      anchor: 0.5,
+      alpha: 1,
+      autoResize: true,
+    };
+
+    const opts: BackgroundConfig = Object.assign(
+      defaultConfig,
+      typeof colorOrConfig === 'number'
+        ? {
+            color: colorOrConfig,
+            alpha: alpha,
+          }
+        : colorOrConfig,
+    );
+
+    this.__background = this.add.sprite({
+      asset: Texture.WHITE,
+      width: opts.width,
+      height: opts.height,
+      anchor: opts.anchor,
+      tint: opts.color,
+      alpha: opts.alpha,
+      resolution: 2,
+    });
+
+    this.setChildIndex(this.__background, 0);
+
+    if (opts.autoResize) {
+      this.addSignalConnection(this.app.onResize.connect(this.__resizeBackground));
+      this.__resizeBackground();
+    }
+
+    return this.__background;
+  }
+
+  /**
+   * Update the container. This method is meant to be overridden by subclasses.
+   * @param ticker
+   */
+  public update(ticker?: Ticker | number) {
+    void ticker;
+  }
+
+  /**
+   * Resize the container. This method is meant to be overridden by subclasses.
+   * @param size
+   */
+  public resize(size?: Size) {
+    void size;
+  }
+
+  /**
+   * This method is called when the container is added to the stage. It is meant to be overridden by subclasses.
+   */
+  public added() {}
+
+  public childAdded(child: PIXIContainer) {
+    void child;
+  }
+
+  destroy(options?: DestroyOptions): void {
+    this.app.animation.killAll(this.animationContext);
+    if (this.__config.autoUpdate) {
+      this.app.ticker.remove(this.update, this);
+    }
+    this.onDestroy.emit();
+    super.destroy(options);
+  }
+
+  public removed() {}
+
+  public childRemoved(child: PIXIContainer) {
+    void child;
+  }
+
+  protected __resizeBackground() {
+    this.__background.width = this.app.size.width;
+    this.__background.height = this.app.size.height;
+  }
+
+  /**
+   * This method is called when the container is added to the stage. It sets up auto-resizing and auto-updating if enabled.
+   */
+  private _added() {
+    if (this.__config.autoResize) {
+      this.addSignalConnection(this.app.onResize.connect(this.resize, this.__config.priority ?? 'highest'));
+    }
+
+    if (this.__config.autoUpdate) {
+      this.app.ticker.add(this.update, this, -999999);
+    }
+    this.added();
+  }
+
+  private _removed() {
+    if (this.__config.autoResize) {
+      this.app.onResize.disconnect(this.resize);
+    }
+
+    if (this.__config.autoUpdate) {
+      this.app.ticker.remove(this.update, this);
+    }
+
+    this.removed();
+  }
+
+  private _childAdded(child: PIXIContainer) {
+    Container.childAdded(child);
+    this.childAdded(child);
+  }
+
+  private _childRemoved(child: PIXIContainer) {
+    Container.childRemoved(child);
+    this.childRemoved(child);
+  }
+
+  protected addAnimation(
+    anim: gsap.core.Tween | gsap.core.Timeline | (gsap.core.Tween | gsap.core.Timeline)[],
+    contextId?: string,
+  ): gsap.core.Tween | gsap.core.Timeline | (gsap.core.Tween | gsap.core.Timeline)[] {
+    return this.app.addAnimation(anim, contextId ?? this.animationContext);
+  }
+}

package/src/display/Entity.ts

@@ -0,0 +1,50 @@
+import { Container } from './Container';
+
+/**
+ * Optional convenience base class for entities discovered from
+ * `src/entities/`. The factory system (`this.add.entity(id, props)`) does
+ * **not** require entities to extend this class — any class with a
+ * single-options-object constructor works. `Entity<Props>` just gives you
+ * typed prop storage and a conventional lifecycle for free.
+ *
+ * **Lifecycle** (inherited from Container):
+ *
+ *   1. `constructor(props)` — props are stashed on `this.props` before
+ *      Container's constructor runs. Don't reference `this.app` yet.
+ *   2. **addChild** — the factory auto-adds the instance to the calling
+ *      Container; Pixi emits an `added` event.
+ *   3. `added()` — override this to build the display tree using
+ *      `this.props`. Safe to use `this.app`, `this.add.*`, and any asset.
+ *      Runs after construction, after stage attachment.
+ *
+ * @example
+ * ```ts
+ * import { defineEntity, Entity } from '@caperjs/core';
+ *
+ * type ActorProps = { color?: number; x?: number; y?: number };
+ *
+ * export const entity = defineEntity({ id: 'actor' });
+ *
+ * export default class Actor extends Entity<ActorProps> {
+ *   added() {
+ *     this.x = this.props.x ?? 0;
+ *     this.y = this.props.y ?? 0;
+ *     this.add.graphics().circle(0, 0, 50).fill(this.props.color ?? 0xffffff);
+ *   }
+ * }
+ * ```
+ *
+ * Then from a scene:
+ * ```ts
+ * this.add.entity('actor', { color: 0xff0000, x: 50, y: 100 });
+ * ```
+ */
+export class Entity<Props = void> extends Container {
+  /** Props passed into the factory call. Populated before `added()` fires. */
+  public readonly props: Props;
+
+  constructor(props?: Props) {
+    super();
+    this.props = (props ?? ({} as Props)) as Props;
+  }
+}