@dryanovski/gamefoo 0.2.3 → 0.2.5

package/src/core/behaviours/collidable.ts

@@ -0,0 +1,296 @@
+import type Entity from "../../entities/entity";
+import type { ColliderShape, CollisionInfo, GameObject, WorldBounds } from "../../types";
+import { Behaviour } from "../behaviour";
+import type World from "../world";
+
+/**
+ * Options for constructing a {@link Collidable} behaviour.
+ *
+ * Every field except `shape` is optional and has a sensible default.
+ *
+ * @category Behaviours
+ * @since 0.1.0
+ *
+ * @example Minimal options
+ * ```ts
+ * const opts: CollidableOptions = {
+ *   shape: { type: "aabb", width: 32, height: 32 },
+ * };
+ * ```
+ *
+ * @example Full options
+ * ```ts
+ * const opts: CollidableOptions = {
+ *   shape: { type: "circle", radius: 16 },
+ *   layer: 0,
+ *   tags: new Set(["enemy"]),
+ *   solid: true,
+ *   fixed: false,
+ *   collidesWith: new Set(["player", "bullet"]),
+ *   onCollision: (info) => console.log("hit!", info.other.id),
+ * };
+ * ```
+ */
+type CollidableOptions = {
+  /**
+   * The geometric shape used for intersection tests.
+   *
+   * @see {@link ColliderShape}
+   */
+  shape: ColliderShape;
+
+  /**
+   * Collision layer index. Only colliders on the **same** layer are
+   * tested against each other.
+   *
+   * @defaultValue `0`
+   */
+  layer?: number;
+
+  /**
+   * Tags that identify *this* collider (e.g. `"player"`, `"bullet"`).
+   *
+   * @defaultValue empty `Set`
+   */
+  tags?: Set<string>;
+
+  /**
+   * Tags this collider is **interested in**. The `onCollision` callback
+   * only fires when the other collider has at least one matching tag.
+   *
+   * @defaultValue empty `Set`
+   */
+  collidesWith?: Set<string>;
+
+  /**
+   * Whether overlap resolution should be applied when this collider
+   * intersects another solid collider.
+   *
+   * @defaultValue `false`
+   */
+  solid?: boolean;
+
+  /**
+   * If `true`, this collider is treated as immovable during overlap
+   * resolution — the other entity absorbs the full displacement.
+   *
+   * @defaultValue `false`
+   */
+  fixed?: boolean;
+
+  /**
+   * Callback invoked when a collision with a tag-matched collider is
+   * detected.
+   *
+   * @param info - Details about the collision, including both entities
+   *   and their tag sets.
+   *
+   * @see {@link CollisionInfo}
+   */
+  onCollision?: (info: CollisionInfo) => void;
+};
+
+/**
+ * Collision behaviour that can be attached to any {@link Entity}.
+ *
+ * When attached, the `Collidable` automatically registers itself with
+ * the engine's {@link World} (via {@link Collidable.onAttach}) and
+ * unregisters on detach. Each frame the `World` queries the collider's
+ * shape, bounds, and tags to determine intersections.
+ *
+ * @category Behaviours
+ * @since 0.1.0
+ *
+ * @example Creating and attaching a box collider
+ * ```ts
+ * import { Collidable, Entity, type CollisionInfo } from "gamefoo";
+ *
+ * const entity = new Enemy("goblin", 100, 200, 30, 30);
+ *
+ * entity.attachBehaviour(
+ *   new Collidable(entity, engine.collisions, {
+ *     shape: { type: "aabb", width: 30, height: 30 },
+ *     layer: 0,
+ *     tags: new Set(["enemy"]),
+ *     solid: true,
+ *     collidesWith: new Set(["player"]),
+ *     onCollision: (info: CollisionInfo) => {
+ *       console.log(`${info.self.id} hit ${info.other.id}`);
+ *     },
+ *   }),
+ * );
+ * ```
+ *
+ * @example Circle collider for a projectile
+ * ```ts
+ * entity.attachBehaviour(
+ *   new Collidable(bullet, engine.collisions, {
+ *     shape: { type: "circle", radius: 4 },
+ *     tags: new Set(["bullet"]),
+ *     collidesWith: new Set(["enemy"]),
+ *   }),
+ * );
+ * ```
+ *
+ * @see {@link World}          — the collision detection system
+ * @see {@link ColliderShape}  — supported shape types
+ * @see {@link CollisionInfo}  — payload delivered to callbacks
+ * @see {@link Behaviour}      — abstract base class
+ */
+export class Collidable extends Behaviour<GameObject> {
+  /** @inheritDoc */
+  readonly type = "collidable";
+
+  /**
+   * Geometric shape used for intersection tests.
+   *
+   * @see {@link ColliderShape}
+   */
+  public shape: ColliderShape;
+
+  /**
+   * Collision layer. Only colliders sharing the same layer value are
+   * tested.
+   *
+   * @defaultValue `0`
+   */
+  public layer: number = 0;
+
+  /**
+   * Tags identifying this collider (e.g. `"player"`, `"enemy"`).
+   *
+   * @defaultValue empty `Set`
+   */
+  public tags: Set<string> = new Set();
+
+  /**
+   * Tags this collider wants to be notified about.
+   *
+   * @defaultValue empty `Set`
+   */
+  public collidesWith: Set<string> = new Set();
+
+  /**
+   * Whether this collider participates in overlap resolution.
+   *
+   * @defaultValue `false`
+   */
+  public solid: boolean = false;
+
+  /**
+   * Whether the owning entity is immovable during overlap resolution.
+   *
+   * @defaultValue `false`
+   */
+  public fixed: boolean = false;
+
+  /**
+   * User-supplied callback invoked when a tag-matched collision is
+   * detected.
+   */
+  public onCollision: (info: CollisionInfo) => void;
+
+  /** Reference to the {@link World} this collider is registered with. */
+  private world: World;
+
+  /**
+   * Creates a new collidable behaviour.
+   *
+   * @param owner   - The game object entity that owns this collider.
+   * @param world   - The collision {@link World} to register with.
+   * @param options - Configuration for shape, tags, solidity, and
+   *   callbacks. See {@link CollidableOptions}.
+   */
+  constructor(owner: GameObject, world: World, options: CollidableOptions) {
+    super(owner);
+
+    this.world = world;
+
+    const size = owner.getSize();
+
+    this.shape = options.shape ?? {
+      type: "aabb",
+      width: size.width,
+      height: size.height,
+    };
+    this.layer = options.layer ?? 0;
+    this.tags = options.tags ?? new Set();
+    this.solid = options.solid ?? false;
+    this.fixed = options.fixed ?? false;
+    this.collidesWith = options.collidesWith ?? new Set();
+    this.onCollision = options.onCollision || (() => {});
+  }
+
+  /**
+   * No-op — collision logic lives in {@link World.detect}.
+   *
+   * @param _deltaTime - Unused.
+   */
+  update(_deltaTime: number): void {}
+
+  /**
+   * Lifecycle hook: registers this collider with the {@link World}
+   * when the behaviour is attached to an entity.
+   *
+   * @see {@link Behaviour.onAttach}
+   */
+  override onAttach(): void {
+    this.world.register(this);
+  }
+
+  /**
+   * Lifecycle hook: removes this collider from the {@link World}
+   * when the behaviour is detached.
+   *
+   * @see {@link Behaviour.onDetach}
+   */
+  override onDetach(): void {
+    this.world.unregister(this);
+  }
+
+  /**
+   * Returns the {@link Entity} that owns this behaviour.
+   *
+   * Used by the {@link World} to read and mutate entity position
+   * during overlap resolution.
+   *
+   * @returns The owning entity.
+   */
+  getOwner(): Entity {
+    return this.owner;
+  }
+
+  /**
+   * Computes this collider's axis-aligned bounding rectangle in
+   * world-space, accounting for the shape's optional offset.
+   *
+   * @returns A {@link WorldBounds} rectangle.
+   *
+   * @example
+   * ```ts
+   * const bounds = collidable.getWorldBounds();
+   * // { x: 100, y: 200, width: 30, height: 30 }
+   * ```
+   */
+  getWorldBounds(): WorldBounds {
+    const pos = this.owner.getPosition();
+    const offset = "offset" in this.shape && this.shape.offset ? this.shape.offset : { x: 0, y: 0 };
+
+    if (this.shape.type === "aabb") {
+      return {
+        x: pos.x + offset.x,
+        y: pos.y + offset.y,
+        width: this.shape.width,
+        height: this.shape.height,
+      };
+    }
+
+    const r = this.shape.radius;
+    return {
+      x: pos.x + offset.x - r,
+      y: pos.y + offset.y - r,
+      width: r * 2,
+      height: r * 2,
+    };
+  }
+}

package/src/core/behaviours/control.ts

@@ -0,0 +1,80 @@
+import type Entity from "../../entities/entity";
+import { Behaviour } from "../behaviour";
+import type Input from "../input";
+
+/**
+ * Keyboard-driven movement behaviour for a {@link Entity}.
+ *
+ * `Control` reads the current keyboard state from an {@link Input}
+ * instance every frame and translates WASD / arrow-key presses into
+ * entity position changes. Diagonal movement is normalised so the
+ * entity moves at a consistent speed in all directions.
+ *
+ * @category Behaviours
+ * @since 0.1.0
+ *
+ * @example Attaching to a player
+ * ```ts
+ * import { Control, Input, Player } from "gamefoo";
+ *
+ * const input  = new Input();
+ * const player = new Player("hero", 400, 300, 50, 50);
+ *
+ * player.attachBehaviour(new Control(player, input));
+ * ```
+ *
+ * @see {@link Input}     — the polling input manager consumed by this behaviour
+ * @see {@link Behaviour} — abstract base class
+ */
+export class Control extends Behaviour<Entity> {
+  /** @inheritDoc */
+  readonly type = "control";
+
+  /** The input manager to poll each frame. */
+  private input: Input;
+
+  /**
+   * Movement speed in pixels per second.
+   *
+   * @defaultValue `500`
+   */
+  private speed: number = 500;
+
+  /**
+   * Creates a new keyboard control behaviour.
+   *
+   * @param owner - The game object entity whose position will be updated.
+   * @param input - The {@link Input} instance to read key state from.
+   */
+  constructor(owner: Entity, input: Input) {
+    super(owner);
+    this.input = input;
+  }
+
+  /**
+   * Reads the current key state and moves the owner entity.
+   *
+   * Supported keys: `W` / `ArrowUp`, `S` / `ArrowDown`,
+   * `A` / `ArrowLeft`, `D` / `ArrowRight`.
+   *
+   * Diagonal input is normalised so the effective speed remains
+   * constant regardless of direction.
+   *
+   * @param deltaTime - Seconds elapsed since the previous frame.
+   */
+  update(deltaTime: number): void {
+    let dx = 0;
+    let dy = 0;
+
+    if (this.input.isKeyDown("a") || this.input.isKeyDown("arrowleft")) dx -= 1;
+    if (this.input.isKeyDown("d") || this.input.isKeyDown("arrowright")) dx += 1;
+    if (this.input.isKeyDown("w") || this.input.isKeyDown("arrowup")) dy -= 1;
+    if (this.input.isKeyDown("s") || this.input.isKeyDown("arrowdown")) dy += 1;
+
+    const len = Math.sqrt(dx * dx + dy * dy);
+    if (len > 0) {
+      this.owner.x += (dx / len) * this.speed * deltaTime;
+      this.owner.y += (dy / len) * this.speed * deltaTime;
+    }
+  }
+}

package/src/core/behaviours/healtkit.ts

@@ -0,0 +1,166 @@
+import type Entity from "../../entities/entity";
+import { Behaviour } from "../behaviour";
+
+/**
+ * Health-tracking behaviour for a {@link Entity}.
+ *
+ * `HealthKit` manages a current and maximum HP value, provides damage
+ * and healing methods, and exposes queries for health percentage and
+ * death state.
+ *
+ * @category Behaviours
+ * @since 0.1.0
+ *
+ * @example Attaching to a player
+ * ```ts
+ * import { HealthKit, Player } from "gamefoo";
+ *
+ * const player = new Player("hero", 400, 300, 50, 50);
+ * player.attachBehaviour(new HealthKit(player, 100));
+ *
+ * player.healthkit?.takeDamage(25);
+ * console.log(player.healthkit?.getHealth());        // 75
+ * console.log(player.healthkit?.getHealthPercent());  // 0.75
+ * ```
+ *
+ * @example Custom max HP
+ * ```ts
+ * const hk = new HealthKit(entity, 50, 200);
+ * // starts at 50 HP, max is 200
+ * hk.heal(999);
+ * console.log(hk.getHealth()); // 200 (clamped to max)
+ * ```
+ *
+ * @see {@link Behaviour} — abstract base class
+ * @see {@link Player}    — has a convenience getter for this behaviour
+ */
+export class HealthKit extends Behaviour<Entity> {
+  /** @inheritDoc */
+  readonly type = "healthkit";
+
+  /** Current health points. */
+  private health: number;
+
+  /** Maximum health points (healing cap). */
+  private maxHP: number;
+
+  /**
+   * Creates a new health behaviour.
+   *
+   * @param owner  - The entity this behaviour is attached to.
+   * @param health - Starting health value.
+   * @param maxHP  - Maximum health cap. If omitted, defaults to the
+   *   initial `health` value.
+   */
+  constructor(owner: Entity, health: number, maxHP?: number) {
+    super(owner);
+    this.health = health;
+    this.maxHP = maxHP || health;
+  }
+
+  /**
+   * No-op — health does not change passively each frame.
+   *
+   * @param _deltaTime - Unused.
+   */
+  update(_deltaTime: number): void {}
+
+  /**
+   * Reduces health by the given amount, clamping at zero.
+   *
+   * @param amount - Damage to apply (positive number).
+   *
+   * @example
+   * ```ts
+   * healthkit.takeDamage(30);
+   * ```
+   */
+  takeDamage(amount: number): void {
+    this.health = Math.max(0, this.health - amount);
+  }
+
+  /**
+   * Increases health by the given amount, clamping at
+   * {@link HealthKit.maxHP}.
+   *
+   * @param amount - Health to restore (positive number).
+   *
+   * @example
+   * ```ts
+   * healthkit.heal(50);
+   * ```
+   */
+  heal(amount: number): void {
+    this.health = Math.min(this.maxHP, this.health + amount);
+  }
+
+  /**
+   * Returns the current health value.
+   *
+   * @returns Current HP.
+   */
+  getHealth(): number {
+    return this.health;
+  }
+
+  /**
+   * Returns the maximum health cap.
+   *
+   * @returns Maximum HP.
+   */
+  getMaxHealth(): number {
+    return this.maxHP;
+  }
+
+  /**
+   * Updates the maximum health cap.
+   *
+   * If the current health exceeds the new cap it is clamped down.
+   *
+   * @param value - The new maximum HP.
+   *
+   * @example
+   * ```ts
+   * healthkit.setMaxHealth(150);
+   * ```
+   */
+  setMaxHealth(value: number): void {
+    this.maxHP = value;
+    if (this.health > this.maxHP) {
+      this.health = this.maxHP;
+    }
+  }
+
+  /**
+   * Whether the entity is dead (health is zero or below).
+   *
+   * @returns `true` if `health <= 0`.
+   *
+   * @example
+   * ```ts
+   * if (healthkit.isDead()) {
+   *   entity.destroy();
+   * }
+   * ```
+   */
+  isDead(): boolean {
+    return this.health <= 0;
+  }
+
+  /**
+   * Returns health as a normalised ratio in the range `[0, 1]`.
+   *
+   * Useful for rendering health bars.
+   *
+   * @returns `health / maxHP`, or `0` if `maxHP` is zero.
+   *
+   * @example
+   * ```ts
+   * const barWidth = 100 * healthkit.getHealthPercent();
+   * ctx.fillRect(x, y, barWidth, 8);
+   * ```
+   */
+  getHealthPercent(): number {
+    return this.maxHP > 0 ? this.health / this.maxHP : 0;
+  }
+}