@debuffjp/core 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,69 @@
-# Temporary Holding Version
+# @debuffjp/core
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Game loop, fixed-step clock, scenes, camera, sprites, typed creative parameters and a batched WebGL2 renderer with automatic Canvas 2D fallback. No dependencies.
+
+```bash
+npm install @debuffjp/core
+```
+
+```ts
+import { Game } from "@debuffjp/core";
+
+const game = new Game({ canvas, width: 320, height: 180, scale: "integer", pixelArt: true });
+
+const tuning = game.params.define("player", {
+  speed: { type: "number", default: 140, min: 0, max: 600, units: "px/s" },
+});
+
+game
+  .add({
+    id: "play",
+    update(dt) {
+      /* simulation at a fixed step */
+    },
+    render(draw, alpha) {
+      /* draw in logical units */
+    },
+    inspect: () => ({
+      /* JSON snapshot for tools and tests */
+    }),
+  })
+  .go("play");
+game.start();
+```
+
+## API
+
+| Export | Purpose |
+| --- | --- |
+| `Game` | Loop, scenes, scaling, `camera`, `random`, `params`, `stats`, `freeze()`, `timeScale`, `step(n)` |
+| `game.use(plugin)`, `Plugin` | Install runtime plugins. See [docs/plugins.md](https://github.com/debuffjp/debuff/blob/main/docs/plugins.md) |
+| `game.hooks` | `beforeUpdate`, `afterUpdate`, `beforeRender`, `afterRender`, `sceneChange`. Each returns an unsubscribe function |
+| `game.inspect` | `register(name, () => json)` for dev tools and scenarios |
+| `Scene` | `{ id, enter?, update?, render?, exit?, inspect? }` |
+| `Camera` | Smoothed follow, deadzone, bounds, trauma shake, culling, `toWorld()` |
+| `Sprite`, `sliceGrid` | Frames, named animations, origin, flip, impact flash |
+| `ParamRegistry`, `ParamGroup` | Typed, ranged, unit-annotated values; `describe()` is JSON |
+| `Random` | Seeded PRNG: `next`, `range`, `int`, `pick` |
+| `FixedClock` | Fixed-step accumulator with render interpolation |
+| `Storage` | `localStorage` wrapper that never throws |
+| `FrameStats` | Allocation-free frame interval / work timings |
+| `clamp`, `lerp`, `damp`, `approach`, `overlaps`, `circlesOverlap` | Math helpers |
+
+### Scale modes
+
+- `fit` (default): fill the container, keep the aspect ratio.
+- `integer`: whole device-pixel scales for crisp pixel art.
+- `none`: logical size in CSS pixels.
+
+Game code always uses logical units. The backing store follows `devicePixelRatio`.
+
+## Start-up splash
+
+Production builds open with a short "made with debuff" card. It lasts 1.6 seconds and any key skips it. Clicking or tapping the card opens [debuff.jp](https://debuff.jp) in a new tab and skips it too. It never shows in dev, or when time is driven by `step()` (scenarios and agents). To remove it:
+
+```ts
+new Game({ canvas, width, height, splash: false });
+```
+
+You can also set its length with `splash: { duration: 1 }`, or end it from code with `game.skipSplash()`.

package/dist/camera.d.ts

@@ -0,0 +1,60 @@
+import type { Random } from "./random.js";
+export interface CameraOptions {
+    /** Viewport size in logical pixels. */
+    width: number;
+    height: number;
+    /** World bounds the camera may not leave. Omit for unbounded. */
+    bounds?: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+}
+/** 2D camera with smoothed follow, deadzone and trauma-based shake.
+ *  `x`/`y` is the world point at the viewport centre. */
+export declare class Camera {
+    x: number;
+    y: number;
+    zoom: number;
+    /** Follow responsiveness in 1/s; higher snaps faster. 0 disables smoothing. */
+    lerp: number;
+    /** Half-size of the region the target may move in without the camera moving. */
+    deadzone: {
+        x: number;
+        y: number;
+    };
+    /** Max shake offset in pixels at trauma 1. */
+    shakeAmplitude: number;
+    /** Trauma lost per second. */
+    shakeDecay: number;
+    /** Multiplier on shake. `Game` lowers it when the player prefers reduced motion. */
+    motionScale: number;
+    private trauma;
+    private offsetX;
+    private offsetY;
+    private target;
+    readonly width: number;
+    readonly height: number;
+    bounds: CameraOptions["bounds"];
+    constructor(options: CameraOptions);
+    follow(target: {
+        x: number;
+        y: number;
+    } | undefined, snap?: boolean): void;
+    /** Add shake trauma in [0, 1]. Shake intensity scales with trauma². */
+    shake(amount: number): void;
+    update(dt: number, random: Random): void;
+    /** The camera as an affine matrix `[a, b, c, d, e, f]` from world to viewport units.
+     *  Use with `draw.withCamera(camera, () => { ... })`. Positions snap to whole pixels. */
+    view(): [number, number, number, number, number, number];
+    /** Convert a viewport point (e.g. pointer) to world coordinates. */
+    toWorld(sx: number, sy: number): {
+        x: number;
+        y: number;
+    };
+    /** True if a world-space rectangle overlaps the view (for culling). */
+    sees(x: number, y: number, w: number, h: number): boolean;
+    private clamp;
+}
+//# sourceMappingURL=camera.d.ts.map

package/dist/camera.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"camera.d.ts","sourceRoot":"","sources":["../src/camera.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAE1C,MAAM,WAAW,aAAa;IAC5B,uCAAuC;IACvC,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,iEAAiE;IACjE,MAAM,CAAC,EAAE;QAAE,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;CAClE;AAED;yDACyD;AACzD,qBAAa,MAAM;IACjB,CAAC,SAAK;IACN,CAAC,SAAK;IACN,IAAI,SAAK;IACT,+EAA+E;IAC/E,IAAI,SAAK;IACT,gFAAgF;IAChF,QAAQ;QAAK,CAAC;QAAK,CAAC;MAAM;IAC1B,8CAA8C;IAC9C,cAAc,SAAK;IACnB,8BAA8B;IAC9B,UAAU,SAAO;IACjB,oFAAoF;IACpF,WAAW,SAAK;IAEhB,OAAO,CAAC,MAAM,CAAK;IACnB,OAAO,CAAC,OAAO,CAAK;IACpB,OAAO,CAAC,OAAO,CAAK;IACpB,OAAO,CAAC,MAAM,CAAuC;IACrD,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,MAAM,EAAE,aAAa,CAAC,QAAQ,CAAC,CAAC;IAEhC,YAAY,OAAO,EAAE,aAAa,EAIjC;IAED,MAAM,CAAC,MAAM,EAAE;QAAE,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,SAAS,EAAE,IAAI,UAAO,GAAG,IAAI,CAOtE;IAED,uEAAuE;IACvE,KAAK,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAE1B;IAED,MAAM,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,CAevC;IAED;6FACyF;IACzF,IAAI,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAGvD;IAED,oEAAoE;IACpE,OAAO,CAAC,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG;QAAE,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAA;KAAE,CAKxD;IAED,uEAAuE;IACvE,IAAI,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,OAAO,CAIxD;IAED,OAAO,CAAC,KAAK;CAQd"}

package/dist/camera.js

@@ -0,0 +1,86 @@
+/** 2D camera with smoothed follow, deadzone and trauma-based shake.
+ *  `x`/`y` is the world point at the viewport centre. */
+export class Camera {
+    x = 0;
+    y = 0;
+    zoom = 1;
+    /** Follow responsiveness in 1/s; higher snaps faster. 0 disables smoothing. */
+    lerp = 8;
+    /** Half-size of the region the target may move in without the camera moving. */
+    deadzone = { x: 0, y: 0 };
+    /** Max shake offset in pixels at trauma 1. */
+    shakeAmplitude = 8;
+    /** Trauma lost per second. */
+    shakeDecay = 1.5;
+    /** Multiplier on shake. `Game` lowers it when the player prefers reduced motion. */
+    motionScale = 1;
+    trauma = 0;
+    offsetX = 0;
+    offsetY = 0;
+    target;
+    width;
+    height;
+    bounds;
+    constructor(options) {
+        this.width = options.width;
+        this.height = options.height;
+        this.bounds = options.bounds;
+    }
+    follow(target, snap = true) {
+        this.target = target;
+        if (target && snap) {
+            this.x = target.x;
+            this.y = target.y;
+            this.clamp();
+        }
+    }
+    /** Add shake trauma in [0, 1]. Shake intensity scales with trauma². */
+    shake(amount) {
+        this.trauma = Math.min(1, this.trauma + amount);
+    }
+    update(dt, random) {
+        if (this.target) {
+            const dx = this.target.x - this.x;
+            const dy = this.target.y - this.y;
+            const tx = Math.abs(dx) > this.deadzone.x ? this.target.x - Math.sign(dx) * this.deadzone.x : this.x;
+            const ty = Math.abs(dy) > this.deadzone.y ? this.target.y - Math.sign(dy) * this.deadzone.y : this.y;
+            const k = this.lerp > 0 ? 1 - Math.exp(-this.lerp * dt) : 1;
+            this.x += (tx - this.x) * k;
+            this.y += (ty - this.y) * k;
+        }
+        this.clamp();
+        this.trauma = Math.max(0, this.trauma - this.shakeDecay * dt);
+        const power = this.trauma * this.trauma * this.shakeAmplitude * this.motionScale;
+        this.offsetX = power * random.range(-1, 1);
+        this.offsetY = power * random.range(-1, 1);
+    }
+    /** The camera as an affine matrix `[a, b, c, d, e, f]` from world to viewport units.
+     *  Use with `draw.withCamera(camera, () => { ... })`. Positions snap to whole pixels. */
+    view() {
+        const z = this.zoom;
+        return [z, 0, 0, z, this.width / 2 - z * Math.round(this.x + this.offsetX), this.height / 2 - z * Math.round(this.y + this.offsetY)];
+    }
+    /** Convert a viewport point (e.g. pointer) to world coordinates. */
+    toWorld(sx, sy) {
+        return {
+            x: (sx - this.width / 2) / this.zoom + this.x,
+            y: (sy - this.height / 2) / this.zoom + this.y,
+        };
+    }
+    /** True if a world-space rectangle overlaps the view (for culling). */
+    sees(x, y, w, h) {
+        const hw = this.width / 2 / this.zoom;
+        const hh = this.height / 2 / this.zoom;
+        return x + w >= this.x - hw && x <= this.x + hw && y + h >= this.y - hh && y <= this.y + hh;
+    }
+    clamp() {
+        const b = this.bounds;
+        if (!b)
+            return;
+        const hw = this.width / 2 / this.zoom;
+        const hh = this.height / 2 / this.zoom;
+        this.x = b.width <= hw * 2 ? b.x + b.width / 2 : Math.min(Math.max(this.x, b.x + hw), b.x + b.width - hw);
+        this.y = b.height <= hh * 2 ? b.y + b.height / 2 : Math.min(Math.max(this.y, b.y + hh), b.y + b.height - hh);
+    }
+}
+//# sourceMappingURL=camera.js.map

package/dist/camera.js.map

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

package/dist/clock.d.ts

@@ -0,0 +1,21 @@
+/** Fixed-timestep accumulator. Simulation advances in exact `step` increments so
+ *  scenarios can replay identically; rendering receives the leftover `alpha`. */
+export interface FixedClockOptions {
+    /** Simulation step in seconds. Default 1/60. */
+    step?: number;
+    /** Cap on real elapsed time per frame, to avoid a spiral after tab switches. Default 0.25s. */
+    maxFrame?: number;
+}
+export declare class FixedClock {
+    readonly step: number;
+    readonly maxFrame: number;
+    /** Total simulated seconds. */
+    time: number;
+    /** Total simulation steps taken. */
+    tick: number;
+    private accumulator;
+    constructor(options?: FixedClockOptions);
+    /** Feed real elapsed seconds; calls `update` once per whole step. Returns render alpha in [0, 1). */
+    advance(elapsed: number, update: (dt: number) => void): number;
+}
+//# sourceMappingURL=clock.d.ts.map

package/dist/clock.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"clock.d.ts","sourceRoot":"","sources":["../src/clock.ts"],"names":[],"mappings":"AAAA;iFACiF;AACjF,MAAM,WAAW,iBAAiB;IAChC,gDAAgD;IAChD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,+FAA+F;IAC/F,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,qBAAa,UAAU;IACrB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,+BAA+B;IAC/B,IAAI,SAAK;IACT,oCAAoC;IACpC,IAAI,SAAK;IACT,OAAO,CAAC,WAAW,CAAK;IAExB,YAAY,OAAO,GAAE,iBAAsB,EAG1C;IAED,qGAAqG;IACrG,OAAO,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,IAAI,GAAG,MAAM,CAU7D;CACF"}

package/dist/clock.js

@@ -0,0 +1,26 @@
+export class FixedClock {
+    step;
+    maxFrame;
+    /** Total simulated seconds. */
+    time = 0;
+    /** Total simulation steps taken. */
+    tick = 0;
+    accumulator = 0;
+    constructor(options = {}) {
+        this.step = options.step ?? 1 / 60;
+        this.maxFrame = options.maxFrame ?? 0.25;
+    }
+    /** Feed real elapsed seconds; calls `update` once per whole step. Returns render alpha in [0, 1). */
+    advance(elapsed, update) {
+        // Small epsilon absorbs float drift so e.g. 0.1 + 0.1 + 0.05 doesn't lose a step.
+        this.accumulator += Math.min(Math.max(elapsed, 0), this.maxFrame);
+        while (this.accumulator >= this.step - 1e-9) {
+            update(this.step);
+            this.accumulator = Math.max(0, this.accumulator - this.step);
+            this.time += this.step;
+            this.tick++;
+        }
+        return this.accumulator / this.step;
+    }
+}
+//# sourceMappingURL=clock.js.map

package/dist/clock.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"clock.js","sourceRoot":"","sources":["../src/clock.ts"],"names":[],"mappings":"AASA,MAAM,OAAO,UAAU;IACZ,IAAI,CAAS;IACb,QAAQ,CAAS;IAC1B,+BAA+B;IAC/B,IAAI,GAAG,CAAC,CAAC;IACT,oCAAoC;IACpC,IAAI,GAAG,CAAC,CAAC;IACD,WAAW,GAAG,CAAC,CAAC;IAExB,YAAY,OAAO,GAAsB,EAAE;QACzC,IAAI,CAAC,IAAI,GAAG,OAAO,CAAC,IAAI,IAAI,CAAC,GAAG,EAAE,CAAC;QACnC,IAAI,CAAC,QAAQ,GAAG,OAAO,CAAC,QAAQ,IAAI,IAAI,CAAC;IAC3C,CAAC;IAED,qGAAqG;IACrG,OAAO,CAAC,OAAe,EAAE,MAA4B;QACnD,kFAAkF;QAClF,IAAI,CAAC,WAAW,IAAI,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,OAAO,EAAE,CAAC,CAAC,EAAE,IAAI,CAAC,QAAQ,CAAC,CAAC;QAClE,OAAO,IAAI,CAAC,WAAW,IAAI,IAAI,CAAC,IAAI,GAAG,IAAI,EAAE,CAAC;YAC5C,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YAClB,IAAI,CAAC,WAAW,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,WAAW,GAAG,IAAI,CAAC,IAAI,CAAC,CAAC;YAC7D,IAAI,CAAC,IAAI,IAAI,IAAI,CAAC,IAAI,CAAC;YACvB,IAAI,CAAC,IAAI,EAAE,CAAC;QACd,CAAC;QACD,OAAO,IAAI,CAAC,WAAW,GAAG,IAAI,CAAC,IAAI,CAAC;IACtC,CAAC;CACF"}

package/dist/game.d.ts

@@ -0,0 +1,149 @@
+import { Camera } from "./camera.js";
+import { FixedClock, type FixedClockOptions } from "./clock.js";
+import { type GameErrorContext, Hooks } from "./hooks.js";
+import { InspectRegistry } from "./inspect.js";
+import { ParamRegistry } from "./params.js";
+import { type Plugin } from "./plugin.js";
+import { Random } from "./random.js";
+import { Draw } from "./render/draw.js";
+import type { Scene } from "./scene.js";
+import { type SplashOptions } from "./splash.js";
+import { FrameStats } from "./stats.js";
+/**
+ * How the logical resolution maps onto the page:
+ * - `fit`: scale to fill the container, preserving aspect ratio (letterboxed).
+ * - `integer`: like `fit` but only whole-number scales, for crisp pixel art.
+ * - `none`: canvas stays at its logical size in CSS pixels.
+ */
+export type ScaleMode = "fit" | "integer" | "none";
+export interface GameOptions {
+    canvas: HTMLCanvasElement;
+    /** Logical resolution. Game code always works in these units. */
+    width: number;
+    height: number;
+    /** Default "fit". */
+    scale?: ScaleMode;
+    /** Element whose size drives scaling. Default: the canvas's parent. */
+    container?: HTMLElement;
+    /** Nearest-neighbour sampling for crisp pixel art. Default false. */
+    pixelArt?: boolean;
+    /**
+     * Rendering backend. `auto` (default) uses WebGL2 and falls back to Canvas 2D when it is unavailable.
+     * Both implement the same `draw` API (ADR 0007).
+     */
+    renderer?: "auto" | "webgl2" | "2d";
+    seed?: number;
+    clock?: FixedClockOptions;
+    /** Opaque background colour, cleared every frame. Default "#000". */
+    background?: string;
+    /**
+     * Honour the player's reduced-motion preference. `"auto"` (default) follows
+     * `prefers-reduced-motion` live; `true`/`false` force it.
+     */
+    reducedMotion?: "auto" | boolean;
+    /**
+     * A short "made with debuff" card when the game first starts, before your first frame. Any key,
+     * click or tap skips it. Not shown in dev, or when time is driven by `step()` (scenarios, agents).
+     * `false` removes it. Default on.
+     */
+    splash?: boolean | SplashOptions;
+}
+/** Owns the loop, clock, RNG, params, camera and active scene. Renders with the
+ *  standard Canvas 2D API; nothing here depends on a third-party renderer. */
+export declare class Game {
+    readonly canvas: HTMLCanvasElement;
+    /** Immediate-mode drawing API, passed to `Scene.render` and render hooks. */
+    readonly draw: Draw;
+    readonly width: number;
+    readonly height: number;
+    readonly clock: FixedClock;
+    readonly random: Random;
+    readonly params: ParamRegistry;
+    readonly camera: Camera;
+    readonly stats: FrameStats;
+    /** Typed lifecycle hooks for plugins and game code. */
+    readonly hooks: Hooks;
+    /** Named JSON snapshot providers for dev tools and scenarios. */
+    readonly inspect: InspectRegistry;
+    readonly scaleMode: ScaleMode;
+    readonly pixelArt: boolean;
+    background: string;
+    /** Multiplier on simulation dt; 0.5 = slow motion. */
+    timeScale: number;
+    /**
+     * True when the player prefers reduced motion. Camera shake is scaled down automatically; read this
+     * to tone down your own effects (flashes, screen-wide particles, parallax speed).
+     */
+    get reducedMotion(): boolean;
+    set reducedMotion(value: boolean);
+    /** Pause automatically while the tab is hidden. */
+    pauseWhenHidden: boolean;
+    /** Current backing-store pixels per logical unit (CSS scale × devicePixelRatio). */
+    renderScale: number;
+    private freezeTime;
+    private motionReduced;
+    private motionQuery;
+    private readonly onMotionChange;
+    private lastAlpha;
+    private readonly pluginRegistry;
+    private readonly scenes;
+    private active;
+    private frameHandle;
+    /** What the frame is doing right now, so a loop error can say where it came from. */
+    private phase;
+    private splashTotal;
+    private splashLeft;
+    private readonly onSplashSkip;
+    /** A click or tap on the splash opens the debuff site (the gesture allows the new tab); elsewhere it just skips. */
+    private readonly onSplashPointer;
+    private lastTime;
+    private running;
+    /** Whether the caller wants the loop running; visibility pausing respects this. */
+    private wanted;
+    private observer;
+    private readonly container;
+    private readonly onVisibility;
+    constructor(options: GameOptions);
+    /** End the start-up splash now (if it is showing or pending). */
+    skipSplash(): void;
+    /** Install a plugin. Throws if the name is invalid or already installed. */
+    use(plugin: Plugin): this;
+    /** Names of installed plugins, in install order. */
+    get plugins(): readonly string[];
+    /** Stop the loop, run plugin cleanups (reverse order) and detach browser listeners. */
+    dispose(): void;
+    /** The error that stopped the loop, if any. Cleared by `start()`. */
+    lastError: (GameErrorContext & {
+        error: unknown;
+    }) | undefined;
+    get scene(): Scene | undefined;
+    get isRunning(): boolean;
+    add(scene: Scene): this;
+    go(id: string): void;
+    start(): void;
+    stop(): void;
+    /** Advance by real elapsed seconds and render once. Exposed so tests and scenarios
+     *  can drive the game without requestAnimationFrame. */
+    frame(elapsed: number): void;
+    /** Render the current state again without advancing time or touching frame stats (captures, editors). */
+    redraw(): void;
+    /** Hit-stop: pause simulation for `seconds` (rendering continues). */
+    freeze(seconds: number): void;
+    get frozen(): boolean;
+    /** Advance exactly `steps` simulation steps (deterministic; for scenarios). */
+    step(steps?: number): void;
+    /** Recompute CSS size and backing-store resolution. Called automatically on container
+     *  resize and devicePixelRatio changes. */
+    resize(): void;
+    /** Convert client (event) coordinates to logical game coordinates. Bound, so it can be passed around (e.g. to `Input`). */
+    readonly toLogical: (clientX: number, clientY: number) => {
+        x: number;
+        y: number;
+    };
+    private run;
+    private halt;
+    /** devicePixelRatio changes (zoom, moving between monitors) don't fire resize on the container. */
+    private watchDpr;
+    private render;
+}
+//# sourceMappingURL=game.d.ts.map

package/dist/game.d.ts.map

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