@dryanovski/gamefoo 0.2.3 → 0.2.5

package/src/core/behaviours/sprite_render.ts

@@ -0,0 +1,216 @@
+import type Entity from "../../entities/entity";
+import type { Vector2 } from "../../types";
+import { Behaviour } from "../behaviour";
+import type Sprite from "../sprite";
+
+/**
+ * Sprite animation renderer that can be attached to any {@link Entity}.
+ *
+ * `SpriteRender` plays named animations defined in a {@link Sprite}
+ * sheet, advancing frames based on each animation's `duration` and
+ * `loop` settings. It supports horizontal flipping for left/right
+ * facing and an optional pixel offset for fine-tuning draw position.
+ *
+ * @category Behaviours
+ * @since 0.1.0
+ *
+ * @example Attaching and playing an animation
+ * ```ts
+ * import { Asset, Sprite, SpriteRender, Player } from "gamefoo";
+ *
+ * const image  = await Asset.load("hero.png");
+ * const sheet  = new Sprite(image, 32, 32, {
+ *   idle: { frames: [0, 1], duration: 0.25, loop: true },
+ *   run:  { frames: [2, 3, 4, 5], duration: 0.1, loop: true },
+ * });
+ *
+ * const player = new Player("hero", 100, 100, 32, 32);
+ * const sr     = new SpriteRender(player, sheet);
+ * player.attachBehaviour(sr);
+ *
+ * sr.play("idle");
+ * ```
+ *
+ * @example Flipping for directional facing
+ * ```ts
+ * if (velocity.x < 0) {
+ *   spriteRender.setFlipX(true);
+ * } else if (velocity.x > 0) {
+ *   spriteRender.setFlipX(false);
+ * }
+ * ```
+ *
+ * @see {@link Sprite}    — spritesheet metadata
+ * @see {@link Asset}     — image loader
+ * @see {@link Behaviour} — abstract base class
+ */
+export default class SpriteRender extends Behaviour<Entity> {
+  /** @inheritDoc */
+  readonly type = "sprite";
+
+  /** The spritesheet this renderer draws from. */
+  private sheet: Sprite;
+
+  /**
+   * Name of the currently playing animation, or `null` if stopped.
+   *
+   * @defaultValue `null`
+   */
+  private currentFrame: string | null = null;
+
+  /**
+   * Index into the current animation's `frames` array.
+   *
+   * @defaultValue `0`
+   */
+  private currentFrameIndex: number = 0;
+
+  /**
+   * Seconds accumulated towards the next frame advance.
+   *
+   * @defaultValue `0`
+   */
+  private elapsedTime: number = 0;
+
+  /**
+   * Whether the sprite is drawn mirrored horizontally.
+   *
+   * @defaultValue `false`
+   */
+  private flipX: boolean = false;
+
+  /**
+   * Pixel offset applied to the draw position, relative to the
+   * entity's origin.
+   *
+   * @defaultValue `{ x: 0, y: 0 }`
+   */
+  public offset: Vector2 = { x: 0, y: 0 };
+
+  /**
+   * Creates a sprite renderer bound to the given entity and sheet.
+   *
+   * @param owner - The entity whose position determines where the
+   *   sprite is drawn.
+   * @param sheet - A {@link Sprite} containing the image and animation
+   *   definitions.
+   */
+  constructor(owner: Entity, sheet: Sprite) {
+    super(owner);
+    this.sheet = sheet;
+  }
+
+  /**
+   * Starts (or switches to) the named animation.
+   *
+   * If the requested animation is already playing, the call is a no-op
+   * so the current playback position is preserved.
+   *
+   * @param animation - Name matching a key in
+   *   {@link Sprite.animations}.
+   *
+   * @example
+   * ```ts
+   * spriteRender.play("run");
+   * ```
+   */
+  play(animation: string): void {
+    if (this.currentFrame === animation) {
+      return;
+    }
+    this.currentFrame = animation;
+    this.currentFrameIndex = 0;
+    this.elapsedTime = 0;
+  }
+
+  /**
+   * Stops the current animation and resets playback state.
+   *
+   * After calling `stop`, nothing is drawn until {@link SpriteRender.play}
+   * is called again.
+   */
+  stop(): void {
+    this.currentFrame = null;
+    this.currentFrameIndex = 0;
+    this.elapsedTime = 0;
+  }
+
+  /**
+   * Enables or disables horizontal flipping.
+   *
+   * Useful for mirroring a character sprite when facing left.
+   *
+   * @param flip - `true` to mirror horizontally, `false` for normal.
+   */
+  setFlipX(flip: boolean): void {
+    this.flipX = flip;
+  }
+
+  /**
+   * Advances the animation clock and moves to the next frame when the
+   * animation's `duration` has elapsed.
+   *
+   * If the animation does not loop, it holds on the last frame.
+   *
+   * @param deltaTime - Seconds elapsed since the previous frame.
+   */
+  update(deltaTime: number): void {
+    if (!this.currentFrame) {
+      return;
+    }
+
+    const animation = this.sheet.animations.get(this.currentFrame);
+
+    if (!animation) {
+      console.warn(`Animation "${this.currentFrame}" not found in sprite sheet.`);
+      return;
+    }
+
+    this.elapsedTime += deltaTime;
+
+    if (this.elapsedTime >= animation.duration) {
+      this.elapsedTime -= animation.duration;
+      this.currentFrameIndex++;
+
+      if (this.currentFrameIndex >= animation.frames.length) {
+        this.currentFrameIndex = animation.loop ? 0 : animation.frames.length - 1;
+      }
+    }
+  }
+
+  /**
+   * Draws the current animation frame to the canvas.
+   *
+   * Respects {@link SpriteRender.flipX} by temporarily mirroring the
+   * canvas transform, and applies {@link SpriteRender.offset} to the
+   * draw position.
+   *
+   * @param ctx - The canvas 2-D rendering context.
+   */
+  override render(ctx: CanvasRenderingContext2D): void {
+    if (!this.currentFrame) {
+      return;
+    }
+
+    const animation = this.sheet.animations.get(this.currentFrame);
+
+    if (!animation) {
+      return;
+    }
+    const frameKey = animation.frames[this.currentFrameIndex]!;
+    const { x, y, width, height } = this.sheet.getFrameRect(frameKey);
+    const pos = this.owner.getPosition();
+    const drawX = pos.x + this.offset.x;
+    const drawY = pos.y + this.offset.y;
+    const size = this.owner.getSize();
+
+    if (this.flipX) {
+      ctx.save();
+      ctx.scale(-1, 1);
+      ctx.drawImage(this.sheet.image, x, y, width, height, -(drawX + size.width), drawY, size.width, size.height);
+      ctx.restore();
+    } else {
+      ctx.drawImage(this.sheet.image, x, y, width, height, drawX, drawY, size.width, size.height);
+    }
+  }
+}

package/src/core/camera.ts

@@ -0,0 +1,145 @@
+import type { Vector2 } from "../types";
+
+/**
+ * A 2-D viewport camera that tracks a target position within the game
+ * world.
+ *
+ * The camera stores its own `(x, y)` centre and viewport dimensions.
+ * Each frame the {@link Engine} calls {@link Camera.follow} with the
+ * player's position so the viewport stays centred on the action.
+ *
+ * @category Core
+ * @since 0.1.0
+ *
+ * @example Basic usage inside the engine
+ * ```ts
+ * const camera = new Camera(800, 600);
+ * camera.follow(player.getPosition());
+ *
+ * const view = camera.getViewRect();
+ * // view → { x: px - 400, y: py - 300, width: 800, height: 600 }
+ * ```
+ *
+ * @example Manual camera control
+ * ```ts
+ * const camera = new Camera(800, 600);
+ * camera.moveTo({ x: 0, y: 0 });       // jump to origin
+ * console.log(camera.getPosition());    // { x: 0, y: 0 }
+ * ```
+ *
+ * @see {@link Engine} — owns and drives the camera each frame
+ */
+export default class Camera {
+  /** Current X coordinate of the camera centre. */
+  private x: number = 0;
+
+  /** Current Y coordinate of the camera centre. */
+  private y: number = 0;
+
+  /** Viewport width in pixels. */
+  private width: number;
+
+  /** Viewport height in pixels. */
+  private height: number;
+
+  /**
+   * Creates a camera with the given viewport dimensions.
+   *
+   * @param width  - Viewport width in pixels.
+   * @param height - Viewport height in pixels.
+   */
+  constructor(width: number, height: number) {
+    this.width = width;
+    this.height = height;
+  }
+
+  /**
+   * Centres the camera on a target position.
+   *
+   * Called by the engine every frame when a player is set.
+   *
+   * @param target - The world-space position to track.
+   *
+   * @example
+   * ```ts
+   * camera.follow(player.getPosition());
+   * ```
+   */
+  follow(target: Vector2): void {
+    this.x = target.x;
+    this.y = target.y;
+  }
+
+  /**
+   * Instantly teleports the camera to a specific position.
+   *
+   * Functionally identical to {@link Camera.follow} but communicates
+   * intent more clearly for one-shot repositioning (e.g. scene
+   * transitions).
+   *
+   * @param target - The world-space position to jump to.
+   *
+   * @example
+   * ```ts
+   * camera.moveTo({ x: 500, y: 300 });
+   * ```
+   */
+  moveTo(target: Vector2): void {
+    this.x = target.x;
+    this.y = target.y;
+  }
+
+  /**
+   * Returns the current centre position of the camera.
+   *
+   * @returns A new {@link Vector2} copy of the camera centre.
+   */
+  getPosition(): Vector2 {
+    return { x: this.x, y: this.y };
+  }
+
+  /**
+   * Computes the axis-aligned rectangle that represents the visible
+   * area in world-space.
+   *
+   * The rectangle is centred on the camera's current position.
+   *
+   * @returns An object with `x` (left edge), `y` (top edge), `width`,
+   *   and `height`.
+   *
+   * @example
+   * ```ts
+   * const rect = camera.getViewRect();
+   * // Use rect to cull off-screen objects
+   * if (entity.x < rect.x || entity.x > rect.x + rect.width) {
+   *   return; // off-screen — skip rendering
+   * }
+   * ```
+   */
+  getViewRect(): { x: number; y: number; width: number; height: number } {
+    return {
+      x: this.x - this.width / 2,
+      y: this.y - this.height / 2,
+      width: this.width,
+      height: this.height,
+    };
+  }
+
+  /**
+   * Updates the viewport dimensions, e.g. after a window resize.
+   *
+   * @param width  - New viewport width in pixels.
+   * @param height - New viewport height in pixels.
+   *
+   * @example
+   * ```ts
+   * window.addEventListener("resize", () => {
+   *   camera.resize(window.innerWidth, window.innerHeight);
+   * });
+   * ```
+   */
+  resize(width: number, height: number): void {
+    this.width = width;
+    this.height = height;
+  }
+}