@datamoc/mw_games 0.1.1 → 0.2.0

package/dist/rpg/Collision.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Lightweight 2D collision: overlap tests for AABBs and circles, plus a resolver that stops
+ * a moving AABB at the edge of a solid tile instead of passing through it.
+ *
+ * This is not a rigid-body physics engine - out of scope for a tile/turn-first framework the
+ * way a full 3D engine is (see item 45's own caution) - it is the missing primitive behind
+ * `rpg.FreeMover`'s own doc comment: "both own position and animation only, nothing about
+ * collision or passability". A game wires this in itself; `FreeMover` stays unopinionated
+ * about whether a game wants tile solidity, circle-vs-circle hits, or no collision at all.
+ */
+export interface AABB {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+export interface Circle {
+    x: number;
+    y: number;
+    radius: number;
+}
+export declare function aabbOverlap(a: AABB, b: AABB): boolean;
+export declare function circleOverlap(a: Circle, b: Circle): boolean;
+export declare function circleAabbOverlap(circle: Circle, box: AABB): boolean;
+/** true when tile `(tileX, tileY)` blocks movement */
+export type SolidTile = (tileX: number, tileY: number) => boolean;
+export interface ResolveTileMoveOptions {
+    tileSize: number;
+    isSolid: SolidTile;
+}
+/**
+ * Moves `box` by `(dx, dy)`, one axis at a time, stopping flush against the edge of the
+ * first solid tile it would otherwise enter rather than tunnelling through it at high
+ * speed. Axis separation (resolve the whole x move, then the whole y move against the
+ * already-resolved x) is the standard, simple choice for an axis-aligned tile grid - a full
+ * swept-AABB solver buys nothing here since every tile edge is already axis-aligned.
+ */
+export declare function resolveAabbAgainstTiles(box: AABB, dx: number, dy: number, options: ResolveTileMoveOptions): {
+    x: number;
+    y: number;
+};
+//# sourceMappingURL=Collision.d.ts.map

package/dist/rpg/Collision.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Collision.d.ts","sourceRoot":"","sources":["../../src/rpg/Collision.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,MAAM,WAAW,IAAI;IACpB,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;IACV,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,MAAM;IACtB,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;IACV,MAAM,EAAE,MAAM,CAAC;CACf;AAED,wBAAgB,WAAW,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,IAAI,GAAG,OAAO,CAErD;AAED,wBAAgB,aAAa,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,OAAO,CAK3D;AAED,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,IAAI,GAAG,OAAO,CAMpE;AAED,sDAAsD;AACtD,MAAM,MAAM,SAAS,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC;AAElE,MAAM,WAAW,sBAAsB;IACtC,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,SAAS,CAAC;CACnB;AAED;;;;;;GAMG;AACH,wBAAgB,uBAAuB,CAAC,GAAG,EAAE,IAAI,EAAE,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,OAAO,EAAE,sBAAsB,GAAG;IAAE,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAA;CAAE,CAOpI"}

package/dist/rpg/Collision.js

@@ -0,0 +1,77 @@
+/**
+ * Lightweight 2D collision: overlap tests for AABBs and circles, plus a resolver that stops
+ * a moving AABB at the edge of a solid tile instead of passing through it.
+ *
+ * This is not a rigid-body physics engine - out of scope for a tile/turn-first framework the
+ * way a full 3D engine is (see item 45's own caution) - it is the missing primitive behind
+ * `rpg.FreeMover`'s own doc comment: "both own position and animation only, nothing about
+ * collision or passability". A game wires this in itself; `FreeMover` stays unopinionated
+ * about whether a game wants tile solidity, circle-vs-circle hits, or no collision at all.
+ */
+export function aabbOverlap(a, b) {
+    return a.x < b.x + b.width && a.x + a.width > b.x && a.y < b.y + b.height && a.y + a.height > b.y;
+}
+export function circleOverlap(a, b) {
+    const dx = a.x - b.x;
+    const dy = a.y - b.y;
+    const r = a.radius + b.radius;
+    return dx * dx + dy * dy < r * r;
+}
+export function circleAabbOverlap(circle, box) {
+    const closestX = clamp(circle.x, box.x, box.x + box.width);
+    const closestY = clamp(circle.y, box.y, box.y + box.height);
+    const dx = circle.x - closestX;
+    const dy = circle.y - closestY;
+    return dx * dx + dy * dy < circle.radius * circle.radius;
+}
+/**
+ * Moves `box` by `(dx, dy)`, one axis at a time, stopping flush against the edge of the
+ * first solid tile it would otherwise enter rather than tunnelling through it at high
+ * speed. Axis separation (resolve the whole x move, then the whole y move against the
+ * already-resolved x) is the standard, simple choice for an axis-aligned tile grid - a full
+ * swept-AABB solver buys nothing here since every tile edge is already axis-aligned.
+ */
+export function resolveAabbAgainstTiles(box, dx, dy, options) {
+    const { tileSize, isSolid } = options;
+    if (!(tileSize > 0))
+        throw new Error('collision tileSize must be positive');
+    const x = sweepAxis(box.x, box.y, box.width, box.height, dx, tileSize, isSolid, true);
+    const y = sweepAxis(x, box.y, box.width, box.height, dy, tileSize, isSolid, false);
+    return { x, y };
+}
+function sweepAxis(x, y, width, height, delta, tileSize, isSolid, horizontal) {
+    if (delta === 0)
+        return horizontal ? x : y;
+    const position = horizontal ? x : y;
+    const size = horizontal ? width : height;
+    const target = position + delta;
+    //the perpendicular span of tiles the box's edge sweeps across while moving
+    const crossStart = Math.floor((horizontal ? y : x) / tileSize);
+    const crossEnd = Math.floor(((horizontal ? y + height : x + width) - 1e-6) / tileSize);
+    const solidAt = (leading, cross) => horizontal ? isSolid(leading, cross) : isSolid(cross, leading);
+    if (delta > 0) {
+        const fromCell = Math.floor((position + size - 1e-6) / tileSize);
+        const toCell = Math.floor((target + size - 1e-6) / tileSize);
+        for (let cell = fromCell + 1; cell <= toCell; cell++) {
+            for (let cross = crossStart; cross <= crossEnd; cross++) {
+                if (solidAt(cell, cross))
+                    return cell * tileSize - size;
+            }
+        }
+    }
+    else {
+        const fromCell = Math.floor(position / tileSize);
+        const toCell = Math.floor(target / tileSize);
+        for (let cell = fromCell - 1; cell >= toCell; cell--) {
+            for (let cross = crossStart; cross <= crossEnd; cross++) {
+                if (solidAt(cell, cross))
+                    return (cell + 1) * tileSize;
+            }
+        }
+    }
+    return target;
+}
+function clamp(value, min, max) {
+    return value < min ? min : value > max ? max : value;
+}
+//# sourceMappingURL=Collision.js.map

package/dist/rpg/Collision.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Collision.js","sourceRoot":"","sources":["../../src/rpg/Collision.ts"],"names":[],"mappings":"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"}

package/dist/rpg/FreeMover.d.ts

@@ -0,0 +1,45 @@
+import type { AnimatedSprite } from '../render/AnimatedSprite.ts';
+export interface FreeMoverOptions {
+    /** world units crossed per second */
+    speed?: number;
+    /**
+     * An animation to play while moving, given the current facing in radians (0 along +x,
+     * increasing clockwise in screen space). Bucketing that into however many directions a
+     * sprite sheet actually has (4, 8, whatever) is the game's own job - this stays
+     * unopinionated about how many facings exist, the same way `GridMover`'s callbacks are
+     * unopinionated about animation names.
+     */
+    walkAnimation?: (facing: number) => string;
+    /** an animation to play while standing still, given the current facing in radians */
+    idleAnimation?: (facing: number) => string;
+}
+/**
+ * Movement not snapped to any grid: a float position plus a continuous facing angle, for a
+ * twin-stick shooter, a bullet-hell, or any top-down game whose player moves and aims freely
+ * rather than stepping cell to cell. `rpg.GridMover` is the tile-to-tile counterpart to this;
+ * both own position and animation only, nothing about collision or passability.
+ */
+export declare class FreeMover {
+    x: number;
+    y: number;
+    /** radians; unchanged while not moving, so a stopped unit keeps facing where it last went */
+    facing: number;
+    private sprite;
+    private speed;
+    private options;
+    private moving;
+    constructor(sprite: AnimatedSprite, x: number, y: number, options?: FreeMoverOptions);
+    get isMoving(): boolean;
+    /**
+     * Moves this frame along `(dx, dy)`, which need not be normalized - only its direction
+     * and whether it is nonzero matter, so a caller can pass a raw stick reading straight
+     * through. `(0, 0)` stops the unit in place, facing whichever way it was last moving.
+     */
+    move(dx: number, dy: number, dt: number): void;
+    /** faces a direction without moving, the free-movement equivalent of `GridMover.turnTo` */
+    turnTo(dx: number, dy: number): void;
+    private place;
+    private playWalk;
+    private playIdle;
+}
+//# sourceMappingURL=FreeMover.d.ts.map

package/dist/rpg/FreeMover.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"FreeMover.d.ts","sourceRoot":"","sources":["../../src/rpg/FreeMover.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,6BAA6B,CAAC;AAElE,MAAM,WAAW,gBAAgB;IAChC,qCAAqC;IACrC,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf;;;;;;OAMG;IACH,aAAa,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,MAAM,CAAC;IAE3C,qFAAqF;IACrF,aAAa,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,MAAM,CAAC;CAC3C;AAED;;;;;GAKG;AACH,qBAAa,SAAS;IACrB,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;IAEV,6FAA6F;IAC7F,MAAM,SAAK;IAEX,OAAO,CAAC,MAAM,CAAiB;IAC/B,OAAO,CAAC,KAAK,CAAS;IACtB,OAAO,CAAC,OAAO,CAAmB;IAClC,OAAO,CAAC,MAAM,CAAS;IAEvB,YAAY,MAAM,EAAE,cAAc,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,OAAO,GAAE,gBAAqB,EASvF;IAED,IAAI,QAAQ,IAAI,OAAO,CAEtB;IAED;;;;OAIG;IACH,IAAI,CAAC,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,IAAI,CAkB7C;IAED,2FAA2F;IAC3F,MAAM,CAAC,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,IAAI,CAInC;IAED,OAAO,CAAC,KAAK;IAKb,OAAO,CAAC,QAAQ;IAKhB,OAAO,CAAC,QAAQ;CAIhB"}

package/dist/rpg/FreeMover.js

@@ -0,0 +1,68 @@
+/**
+ * Movement not snapped to any grid: a float position plus a continuous facing angle, for a
+ * twin-stick shooter, a bullet-hell, or any top-down game whose player moves and aims freely
+ * rather than stepping cell to cell. `rpg.GridMover` is the tile-to-tile counterpart to this;
+ * both own position and animation only, nothing about collision or passability.
+ */
+export class FreeMover {
+    constructor(sprite, x, y, options = {}) {
+        /** radians; unchanged while not moving, so a stopped unit keeps facing where it last went */
+        this.facing = 0;
+        this.moving = false;
+        this.sprite = sprite;
+        this.x = x;
+        this.y = y;
+        this.speed = options.speed ?? 4;
+        this.options = options;
+        this.place();
+        this.playIdle();
+    }
+    get isMoving() {
+        return this.moving;
+    }
+    /**
+     * Moves this frame along `(dx, dy)`, which need not be normalized - only its direction
+     * and whether it is nonzero matter, so a caller can pass a raw stick reading straight
+     * through. `(0, 0)` stops the unit in place, facing whichever way it was last moving.
+     */
+    move(dx, dy, dt) {
+        const length = Math.hypot(dx, dy);
+        if (length > 0) {
+            this.facing = Math.atan2(dy, dx);
+            this.x += (dx / length) * this.speed * dt;
+            this.y += (dy / length) * this.speed * dt;
+            if (!this.moving) {
+                this.moving = true;
+                this.playWalk();
+            }
+        }
+        else if (this.moving) {
+            this.moving = false;
+            this.playIdle();
+        }
+        this.place();
+        this.sprite.update(dt);
+    }
+    /** faces a direction without moving, the free-movement equivalent of `GridMover.turnTo` */
+    turnTo(dx, dy) {
+        if (this.moving || (dx === 0 && dy === 0))
+            return;
+        this.facing = Math.atan2(dy, dx);
+        this.playIdle();
+    }
+    place() {
+        this.sprite.x = this.x;
+        this.sprite.y = this.y;
+    }
+    playWalk() {
+        const name = this.options.walkAnimation?.(this.facing);
+        if (name && this.sprite.has(name))
+            this.sprite.play(name);
+    }
+    playIdle() {
+        const name = this.options.idleAnimation?.(this.facing);
+        if (name && this.sprite.has(name))
+            this.sprite.play(name);
+    }
+}
+//# sourceMappingURL=FreeMover.js.map

package/dist/rpg/FreeMover.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"FreeMover.js","sourceRoot":"","sources":["../../src/rpg/FreeMover.ts"],"names":[],"mappings":"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"}

package/dist/rpg/Marshal.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Ruby's `Marshal` binary serialisation format (version 4.8, unchanged since Ruby 1.8) -
+ * the container `Game.rxdata` and every other RPG Maker XP/VX save are written in. This is
+ * format engineering, not RPG Maker's own code or content: the byte layout below is Ruby's
+ * own standard-library format, learned the ordinary way any undocumented format is, by
+ * reading real files in it. Nothing here knows what an RPG Maker save's own classes
+ * (`Game_Party`, `Game_Actor`) mean; it only turns the container's bytes into a faithful,
+ * generic JS shape a game can then interpret however it needs to. See CLAUDE.md's licence
+ * convention and ROADMAP.md item 100 for where this line sits.
+ *
+ * What decodes: nil, true, false, Fixnum, Bignum, Float, String, Symbol, Array, Hash
+ * (including one with a default value, read separately via `hashDefaultOf` rather than as a
+ * fake entry - a real Hash key equal to any string sentinel would otherwise collide with
+ * it), and Object (`o`, a class name plus its instance variables) - everything a plain-data
+ * save file actually needs. `_dump`/`_load` values
+ * (`u`) decode to their class name plus the opaque bytes their own `_load` would need,
+ * since that per-class binary layout is a second, undocumented format nested inside this
+ * one and out of scope the same way a container format never explains the media it holds.
+ * `marshal_dump`/`marshal_load` values (`U`) decode fully, since their payload is an
+ * ordinary Marshal value. Backreferences (`@`, `;`) resolve against the same link tables a
+ * real Ruby `Marshal.load` keeps, so a value referenced twice decodes to the same object
+ * twice rather than being duplicated.
+ */
+/** an RPG Maker (or any other) object: its class name and every instance variable, by name */
+export interface RubyObject {
+    class: string;
+    ivars: Record<string, unknown>;
+}
+/** a value only `_dump`/`_load` on its own class could decode further - see the module doc */
+export interface RubyUserDefined {
+    class: string;
+    raw: Uint8Array;
+}
+/**
+ * Marks a JS string as a Ruby Symbol rather than a String when encoding - `decodeMarshal`
+ * maps both to a plain JS string (the distinction rarely matters for reading a save back),
+ * but writing needs to know which one to produce. `RubyObject.ivars`' keys are always
+ * written as symbols regardless, since that half of the format has no other option.
+ */
+export declare class RubySymbol {
+    readonly name: string;
+    constructor(name: string);
+}
+/** the default value of a Hash decoded from `Hash.new(default)` (Marshal's `}` tag), if any */
+export declare function hashDefaultOf(hash: Map<unknown, unknown>): unknown;
+/** marks a Map for `encodeMarshal` to write back out as a `Hash.new(default)`, tag `}` */
+export declare function withHashDefault(hash: Map<unknown, unknown>, defaultValue: unknown): Map<unknown, unknown>;
+/** decodes one Marshal document (a whole `.rxdata` file, or any other Marshal dump) */
+export declare function decodeMarshal(bytes: Uint8Array): unknown;
+/**
+ * Encodes one Marshal document from the same shapes `decodeMarshal` produces: `null`,
+ * `boolean`, `number` (written as a Fixnum when it is a safe integer, a Float otherwise),
+ * `string` (a Marshal String, unless wrapped in `RubySymbol`), `Array`, `Map` (a Hash, key
+ * order preserved), and `RubyObject`.
+ *
+ * Every value is written fresh rather than reusing Ruby's own backreference scheme for a
+ * repeated string, symbol or object - valid Marshal either way, since backreferences are an
+ * optional size optimisation, not something a reader is required to produce. A save written
+ * this way is larger than Ruby's own `Marshal.dump` would make it, never incorrect.
+ * `RubyUserDefined` (a `_dump`/`_load` value) cannot be re-encoded at all, for the same
+ * reason `decodeMarshal` cannot interpret its bytes: that per-class binary layout is a
+ * second format this module was never taught.
+ */
+export declare function encodeMarshal(value: unknown): Uint8Array;
+//# sourceMappingURL=Marshal.d.ts.map

package/dist/rpg/Marshal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Marshal.d.ts","sourceRoot":"","sources":["../../src/rpg/Marshal.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,8FAA8F;AAC9F,MAAM,WAAW,UAAU;IAC1B,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC/B;AAED,8FAA8F;AAC9F,MAAM,WAAW,eAAe;IAC/B,KAAK,EAAE,MAAM,CAAC;IACd,GAAG,EAAE,UAAU,CAAC;CAChB;AAED;;;;;GAKG;AACH,qBAAa,UAAU;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAEtB,YAAY,IAAI,EAAE,MAAM,EAEvB;CACD;AASD,+FAA+F;AAC/F,wBAAgB,aAAa,CAAC,IAAI,EAAE,GAAG,CAAC,OAAO,EAAE,OAAO,CAAC,GAAG,OAAO,CAElE;AAED,0FAA0F;AAC1F,wBAAgB,eAAe,CAAC,IAAI,EAAE,GAAG,CAAC,OAAO,EAAE,OAAO,CAAC,EAAE,YAAY,EAAE,OAAO,GAAG,GAAG,CAAC,OAAO,EAAE,OAAO,CAAC,CAGzG;AAyND,uFAAuF;AACvF,wBAAgB,aAAa,CAAC,KAAK,EAAE,UAAU,GAAG,OAAO,CAExD;AAMD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,UAAU,CAIxD"}