Add snow precipitation to WeatherLayer

- Add _startSnow / _makeSnowflake methods with wobble animation
- Export WanderBehavior and RenderableItem publicly
- Bump version to 0.1.2

Author: gandazgul

deno.json

@@ -1,6 +1,6 @@
 {
     "name": "@caper/engine",
-    "version": "0.1.1",
+    "version": "0.1.2",
     "license": "MIT",
     "nodeModulesDir": "auto",
     "exports": {

mod.d.ts

@@ -882,6 +882,7 @@ export class WeatherLayer {
 	tint: Phaser.GameObjects.Rectangle | null;
 	/** @type {Drop[]} */
 	drops: Drop[];
+	_snow: boolean;
 	_heavy: boolean;
 	/** @type {AmbientMode} */
 	ambientMode: AmbientMode;
@@ -897,12 +898,20 @@ export class WeatherLayer {
 	_ensureUpdateLoop(): void;
 	/** @param {boolean} heavy */
 	_startRain(heavy: boolean): void;
+	/** @param {boolean} heavy */
+	_startSnow(heavy: boolean): void;
 	/**
 	 * @param {boolean} initial - if true, seed positions across the full
 	 *   screen so rain doesn't pop in from the top all at once.
 	 * @returns {Drop}
 	 */
 	_makeDrop(initial: boolean): Drop;
+	/**
+	 * @param {boolean} initial - seed flakes across the screen so snow is
+	 *   already falling when the scene appears.
+	 * @returns {Drop}
+	 */
+	_makeSnowflake(initial: boolean): Drop;
 	_startLeaves(): void;
 	/**
 	 * @param {boolean} initial - seed across the full screen on first build
@@ -923,7 +932,8 @@ export class WeatherLayer {
 export type PrecipitationMode = "none" | "light-rain" | "heavy-rain" | "snow" | "heavy-snow";
 export type AmbientMode = "none" | "falling-leaves";
 /**
- * One falling raindrop drawn as a line each frame.
+ * One falling precipitation particle drawn each frame.
+ * Rain uses short slanted lines; snow uses small soft dots.
  */
 export type Drop = {
 	x: number;
@@ -932,6 +942,10 @@ export type Drop = {
 	vy: number;
 	length: number;
 	alpha: number;
+	radius?: number;
+	wobbleAmp?: number;
+	wobbleFreq?: number;
+	wobblePhase?: number;
 };
 /**
  * One falling leaf sprite, sway + spin animated per-frame.
@@ -1603,7 +1617,33 @@ export type WanderHost = Walker & {
 	despawn: () => void;
 	isSpawned: () => boolean;
 };
-declare class WanderBehavior {
+/**
+ * @typedef {object} WanderOptions
+ * @property {boolean} [startPresent] - force the initial present/absent roll.
+ * @property {{x: number, y: number} | null} [startPos] - when present-on-entry
+ *   (not from an exit), stand here instead of a random walkable point.
+ * @property {number} [presentChance] - chance of being present on attach. Default 1 (always present).
+ * @property {[number, number] | null} [walksRange] - wanders before leaving the scene. `null` = perpetual (never leaves).
+ * @property {[number, number]} [wanderDelayRange] - ms paused between wanders. Default [3000, 6000].
+ * @property {number} [returnInterval] - ms between return-check rolls while absent. Default 18000.
+ * @property {number} [returnChance] - chance to return on each check. Default 0.33.
+ * @property {{x: number, y: number, w: number, h: number}} [area] - explicit roam bounds. When set, random
+ *   destinations are picked inside this rect (no walkable snap) — use it when the character's roam zone differs
+ *   from the player walkable polygon (e.g. a foreground shore strip). Defaults to the scene walkable.
+ * @property {boolean} [startAtExit] - spawn from a random scene exit. Default = can-leave.
+ * @property {boolean} [walkInOnSpawn] - walk to a random point immediately on spawn (vs pausing first). Default false.
+ * @property {string | null} [idleFrame] - texture shown while paused between wanders. Default = host still frame.
+ * @property {number} [interruptResumeMs] - ms before the routine resumes after a click greeting. Default 2600.
+ * @property {boolean} [autoStart] - run the state machine on construction. Default true.
+ */
+/**
+ * The come-and-go wander machine, generalized out of the six controllers that
+ * each hand-rolled it. Drives a {@link import("./walker.js").WanderHost} through
+ * `wandering` → `leaving` → `absent`, picking random walkable points, and
+ * (optionally) leaving the scene after a few walks before checking back on a
+ * timer. Knows nothing about sprites except through the host.
+ */
+export class WanderBehavior {
 	/**
 	 * @param {import("./walker.js").WanderHost} host
 	 * @param {WanderOptions} [opts]
@@ -3555,6 +3595,73 @@ export function buildCutsceneContext(scene: any, cs: Cutscene, present: Map<stri
  * @return {number}
  */
 export function randomInt(...args: number[]): number;
+/**
+ * Shared "renderable item" shape used across a game's item collections (props,
+ * equipment, scene-specific objects). Every collection extends this with its own
+ * positional / domain
+ * fields, but the visual fields are uniform: pick a frame, set a scale,
+ * optionally rotate.
+ *
+ * Pattern for a new collection — declare a typedef that intersects this
+ * with the scene-specific fields, e.g.:
+ *   `import("./itemDef.js").RenderableItem & { x: number, y: number }`
+ */
+export type RenderableItem = {
+	/**
+	 * - registry key
+	 */
+	id: string;
+	/**
+	 * - atlas frame name. Defaults to `id` if omitted.
+	 */
+	frame?: string;
+	/**
+	 * - display scale, default 1
+	 */
+	scale?: number;
+	/**
+	 * - rotation in DEGREES (Phaser setAngle), default 0
+	 */
+	rotation?: number;
+};
+/**
+ * Shared "renderable item" shape used across a game's item collections (props,
+ * equipment, scene-specific objects). Every collection extends this with its own
+ * positional / domain
+ * fields, but the visual fields are uniform: pick a frame, set a scale,
+ * optionally rotate.
+ *
+ * Pattern for a new collection — declare a typedef that intersects this
+ * with the scene-specific fields, e.g.:
+ *   `import("./itemDef.js").RenderableItem & { x: number, y: number }`
+ *
+ * @typedef {object} RenderableItem
+ * @property {string} id - registry key
+ * @property {string} [frame] - atlas frame name. Defaults to `id` if omitted.
+ * @property {number} [scale] - display scale, default 1
+ * @property {number} [rotation] - rotation in DEGREES (Phaser setAngle), default 0
+ */
+/**
+ * A `RenderableItem` placed in a scene at a specific position. Add a list
+ * of these to `AdventureSceneConfig.propItems` and the base scene renders
+ * them automatically (no per-scene loop needed). Subclasses can grab the
+ * resulting sprite via `this.propSprites.get(id)` for later manipulation
+ * (destroy on pickup, toggle visibility, etc.).
+ *
+ * @typedef {RenderableItem & {
+ *   atlas: string,
+ *   x: number,
+ *   y: number,
+ *   depth?: number,
+ *   flipX?: boolean,
+ *   origin?: { x?: number, y?: number },
+ *   shouldRender?: () => boolean,
+ *   seasons?: string[],
+ *   hideIfPickedUp?: boolean,
+ * }} PropItem
+ */
+/** @type {RenderableItem} */
+export const RenderableItem: RenderableItem;
 /**
  * Engine — content registry (ADR 0005).
  *

mod.js

@@ -13,6 +13,7 @@ export { EngineAssetRegistry, engineAssets } from "./src/assets/EngineAssets.js"
 export { FullscreenButton } from "./src/ui/FullscreenButton.js";
 export { HotspotManager } from "./src/interaction/HotspotManager.js";
 export { IdleCharacter } from "./src/movement/IdleCharacter.js";
+export { WanderBehavior } from "./src/movement/behaviors/WanderBehavior.js";
 export { InventoryLayer } from "./src/inventory/InventoryLayer.js";
 export { NPC } from "./src/cast/NPC.js";
 export { NightLayer } from "./src/environment/NightLayer.js";
@@ -52,4 +53,5 @@ export { createAdventureGame } from "./src/scene/createAdventureGame.js";
 export { buildCutsceneContext } from "./src/cutscene/cutsceneActor.js";
 export { bakeCircularCrop, resolveCharacterPortrait } from "./src/characters/portraits.js";
 export { randomInt } from "./src/core/random.js";
+export { RenderableItem } from "./src/inventory/itemDef.js";
 export { transitionIn, TRANSITIONS, transitionTo } from "./src/scene/transitions.js";

src/environment/WeatherLayer.js

@@ -5,14 +5,19 @@ import { engineAssets } from "../assets/EngineAssets.js";
 /** @typedef {"none" | "falling-leaves"} AmbientMode */
 
 /**
- * One falling raindrop drawn as a line each frame.
+ * One falling precipitation particle drawn each frame.
+ * Rain uses short slanted lines; snow uses small soft dots.
  * @typedef {Object} Drop
  * @property {number} x
  * @property {number} y
  * @property {number} vx
  * @property {number} vy
  * @property {number} length
  * @property {number} alpha
+ * @property {number} [radius]
+ * @property {number} [wobbleAmp]
+ * @property {number} [wobbleFreq]
+ * @property {number} [wobblePhase]
  */
 
 /**
@@ -32,6 +37,8 @@ import { engineAssets } from "../assets/EngineAssets.js";
 
 const LIGHT_DROP_COUNT = 110;
 const HEAVY_DROP_COUNT = 320;
+const LIGHT_SNOW_COUNT = 150;
+const HEAVY_SNOW_COUNT = 420;
 const LEAF_COUNT = 18;
 
 const WEATHER_DEPTH = 5000;
@@ -64,6 +71,7 @@ export class WeatherLayer {
         this.tint = null;
         /** @type {Drop[]} */
         this.drops = [];
+        this._snow = false;
         this._heavy = false;
 
         // ── Ambient state (falling leaves) ────────────────────────────────
@@ -90,6 +98,8 @@ export class WeatherLayer {
         this.weatherMode = mode;
         if (mode === "light-rain" || mode === "heavy-rain") {
             this._startRain(mode === "heavy-rain");
+        } else if (mode === "snow" || mode === "heavy-snow") {
+            this._startSnow(mode === "heavy-snow");
         }
         this._ensureUpdateLoop();
     }
@@ -141,6 +151,28 @@ export class WeatherLayer {
         }
     }
 
+    /** @param {boolean} heavy */
+    _startSnow(heavy) {
+        this._heavy = heavy;
+        this._snow = true;
+        const count = heavy ? HEAVY_SNOW_COUNT : LIGHT_SNOW_COUNT;
+
+        const tintAlpha = heavy ? 0.18 : 0.08;
+        this.tint = this.scene.add.rectangle(0, 0, this.scene.scale.width, this.scene.scale.height, 0xb8d3ff, tintAlpha)
+            .setOrigin(0, 0)
+            .setDepth(WEATHER_DEPTH)
+            .setScrollFactor(0);
+
+        this.gfx = this.scene.add.graphics()
+            .setDepth(WEATHER_DEPTH + 1)
+            .setScrollFactor(0);
+
+        this.drops = new Array(count);
+        for (let i = 0; i < count; i++) {
+            this.drops[i] = this._makeSnowflake(true);
+        }
+    }
+
     /**
      * @param {boolean} initial - if true, seed positions across the full
      *   screen so rain doesn't pop in from the top all at once.
@@ -158,6 +190,29 @@ export class WeatherLayer {
         return { x, y, vx: speedX, vy: speedY, length, alpha };
     }
 
+    /**
+     * @param {boolean} initial - seed flakes across the screen so snow is
+     *   already falling when the scene appears.
+     * @returns {Drop}
+     */
+    _makeSnowflake(initial) {
+        const heavy = this._heavy;
+        const x = Phaser.Math.Between(-80, this.scene.scale.width + 80);
+        const y = initial ? Phaser.Math.Between(-40, this.scene.scale.height) : Phaser.Math.Between(-160, -20);
+        return {
+            x,
+            y,
+            vx: Phaser.Math.Between(heavy ? -55 : -35, heavy ? 35 : 25),
+            vy: Phaser.Math.Between(heavy ? 120 : 65, heavy ? 240 : 130),
+            length: 0,
+            alpha: Phaser.Math.FloatBetween(heavy ? 0.65 : 0.45, heavy ? 0.95 : 0.75),
+            radius: Phaser.Math.FloatBetween(heavy ? 1.5 : 1, heavy ? 3.3 : 2.3),
+            wobbleAmp: Phaser.Math.FloatBetween(heavy ? 8 : 5, heavy ? 24 : 16),
+            wobbleFreq: Phaser.Math.FloatBetween(0.8, 1.8),
+            wobblePhase: Phaser.Math.FloatBetween(0, Math.PI * 2),
+        };
+    }
+
     // ─── Falling leaves ──────────────────────────────────────────────────
 
     _startLeaves() {
@@ -230,6 +285,24 @@ export class WeatherLayer {
                 g.lineTo(drop.x - ux * len, drop.y - uy * len);
                 g.strokePath();
             }
+        } else if (this.gfx && (this.weatherMode === "snow" || this.weatherMode === "heavy-snow")) {
+            const g = this.gfx;
+            g.clear();
+            for (const flake of this.drops) {
+                flake.wobblePhase = (flake.wobblePhase ?? 0) + (flake.wobbleFreq ?? 1) * seconds;
+                flake.x += flake.vx * seconds;
+                flake.y += flake.vy * seconds;
+                const wobble = Math.sin(flake.wobblePhase) * (flake.wobbleAmp ?? 0);
+                if (
+                    flake.y > this.scene.scale.height + 20 ||
+                    flake.x + wobble < -100 ||
+                    flake.x + wobble > this.scene.scale.width + 100
+                ) {
+                    Object.assign(flake, this._makeSnowflake(false));
+                }
+                g.fillStyle(0xffffff, flake.alpha);
+                g.fillCircle(flake.x + wobble, flake.y, flake.radius ?? 2);
+            }
         }
 
         // ── Ambient (falling leaves) ──────────────────────────────────
@@ -267,6 +340,7 @@ export class WeatherLayer {
             this.tint = null;
         }
         this.drops = [];
+        this._snow = false;
     }
 
     /** Tear down ambient only. */

src/inventory/itemDef.js

@@ -35,3 +35,7 @@
  *   hideIfPickedUp?: boolean,
  * }} PropItem
  */
+
+/** @type {RenderableItem} */
+export const RenderableItem = null;
+