samengine 1.9.1 → 1.10.0

package/dist/samegui/index.js

@@ -1,5 +1,12 @@
 // HTML Overlay
 import { hash } from "../utils/index.js";
+/**
+ * Tiny immediate-mode HTML overlay for debug tools and simple in-game menus.
+ *
+ * Call `begin()` before emitting UI for the frame, then call `button`, `text`,
+ * and `checkbox` in a stable order, and finally call `end()`. Elements are
+ * backed by real DOM nodes but identified by hashed labels or explicit ids.
+ */
 export class HtmlUI {
     constructor() {
         this.elements = new Map();
@@ -22,9 +29,15 @@ export class HtmlUI {
         this.panel.style.borderRadius = "6px";
         this.root.appendChild(this.panel);
     }
+    /**
+     * Starts a new UI frame and records which controls are used this frame.
+     */
     begin() {
         this.frameIds = [];
     }
+    /**
+     * Ends the UI frame and clears one-frame button click states.
+     */
     end() {
         // reset clicks AFTER frame
         for (const id of this.frameIds) {
@@ -49,6 +62,11 @@ export class HtmlUI {
         }
         return e.el;
     }
+    /**
+     * Creates or updates a button.
+     *
+     * @returns `true` during the frame after the DOM button was clicked.
+     */
     button(label, idOverride) {
         const id = hash(idOverride ?? label);
         this.frameIds.push(id);
@@ -60,6 +78,9 @@ export class HtmlUI {
         };
         return this.clicked.get(id) === true;
     }
+    /**
+     * Creates or updates a text label in the overlay panel.
+     */
     text(label, idOverride) {
         const id = hash(idOverride ?? label);
         this.frameIds.push(id);
@@ -73,6 +94,11 @@ export class HtmlUI {
         }
         e.el.textContent = label;
     }
+    /**
+     * Creates or updates a checkbox and returns its current value.
+     *
+     * `defaultValue` is only used the first time the checkbox id appears.
+     */
     checkbox(label, defaultValue, idOverride) {
         const id = hash(idOverride ?? label);
         this.frameIds.push(id);

package/dist/save.d.ts

@@ -1,24 +1,36 @@
 /**
+ * Old save data shape used by the legacy save helpers.
+ *
  * @deprecated Use samengine/storage instead
  */
 export type SaveData = Record<string, any>;
 /**
+ * localStorage key used by the legacy save helpers.
+ *
  * @deprecated Use samengine/storage instead
  */
 export declare let SAVE_KEY: string;
 /**
+ * Stores save data as JSON under `SAVE_KEY`.
+ *
  * @deprecated Use samengine/storage instead
  */
 export declare function saveGame(data: SaveData): void;
 /**
+ * Loads and parses JSON save data from `SAVE_KEY`.
+ *
  * @deprecated Use samengine/storage instead
  */
 export declare function loadGame(): SaveData | null;
 /**
+ * Removes the current save entry from localStorage.
+ *
  * @deprecated Use samengine/storage instead
  */
 export declare function clearSave(): void;
 /**
+ * Downloads the current save data as `savegame.json`.
+ *
  * @deprecated Use samengine/storage instead
  */
 export declare function exportSave(): void;

package/dist/save.js

@@ -1,9 +1,13 @@
 // Please rename the SaveKey
 /**
+ * localStorage key used by the legacy save helpers.
+ *
  * @deprecated Use samengine/storage instead
  */
 export let SAVE_KEY = "my_game_save";
 /**
+ * Stores save data as JSON under `SAVE_KEY`.
+ *
  * @deprecated Use samengine/storage instead
  */
 export function saveGame(data) {
@@ -17,6 +21,8 @@ export function saveGame(data) {
     }
 }
 /**
+ * Loads and parses JSON save data from `SAVE_KEY`.
+ *
  * @deprecated Use samengine/storage instead
  */
 export function loadGame() {
@@ -32,6 +38,8 @@ export function loadGame() {
     }
 }
 /**
+ * Removes the current save entry from localStorage.
+ *
  * @deprecated Use samengine/storage instead
  */
 export function clearSave() {
@@ -39,6 +47,8 @@ export function clearSave() {
     console.log("Save cleared!");
 }
 /**
+ * Downloads the current save data as `savegame.json`.
+ *
  * @deprecated Use samengine/storage instead
  */
 export function exportSave() {

package/dist/sound/audioplayer.d.ts

@@ -1,17 +1,56 @@
+/**
+ * Web Audio based sound manager for short effects and looping music.
+ *
+ * Sounds are decoded once and cached by URL. In normal builds, audio files are
+ * loaded with `fetch(url)`. Single-file exports can provide `window.__loadResource`
+ * to resolve embedded resources before falling back to normal fetch.
+ */
 export declare class SoundSystem {
     private ctx;
     private bufferCache;
     private activeSources;
     private masterGain;
+    /**
+     * Creates or reuses an `AudioContext` and connects a master gain node.
+     *
+     * Browsers often require user interaction before audio can play. If playback
+     * is blocked or suspended, call `resume()` from a click/key handler.
+     */
     constructor();
+    /**
+     * Loads, decodes, and caches an audio file.
+     *
+     * @param url Audio URL or embedded resource key.
+     * @returns Decoded `AudioBuffer`.
+     */
     load(url: string): Promise<AudioBuffer>;
+    /**
+     * Plays an audio file and returns the active source node.
+     *
+     * @param url Audio URL or embedded resource key.
+     * @param options Per-playback settings such as volume, loop, and speed.
+     */
     play(url: string, options?: {
         volume?: number;
         loop?: boolean;
         playbackRate?: number;
     }): Promise<AudioBufferSourceNode>;
+    /**
+     * Stops every source started through this `SoundSystem`.
+     */
     stopAll(): void;
+    /**
+     * Sets the master volume for all current and future sounds.
+     *
+     * `1` is full volume, `0` is silent. Values above `1` amplify.
+     */
     setVolume(v: number): void;
+    /**
+     * Resumes the underlying `AudioContext` if the browser suspended it.
+     */
     resume(): Promise<void>;
+    /**
+     * Suspends the underlying `AudioContext` without clearing loaded buffers.
+     */
     pause(): Promise<void>;
 }

package/dist/sound/audioplayer.js

@@ -1,4 +1,17 @@
+/**
+ * Web Audio based sound manager for short effects and looping music.
+ *
+ * Sounds are decoded once and cached by URL. In normal builds, audio files are
+ * loaded with `fetch(url)`. Single-file exports can provide `window.__loadResource`
+ * to resolve embedded resources before falling back to normal fetch.
+ */
 export class SoundSystem {
+    /**
+     * Creates or reuses an `AudioContext` and connects a master gain node.
+     *
+     * Browsers often require user interaction before audio can play. If playback
+     * is blocked or suspended, call `resume()` from a click/key handler.
+     */
     constructor() {
         this.bufferCache = new Map();
         this.activeSources = new Set();
@@ -8,7 +21,12 @@ export class SoundSystem {
         this.masterGain.gain.value = 1;
         this.masterGain.connect(this.ctx.destination);
     }
-    // ================= LOAD =================
+    /**
+     * Loads, decodes, and caches an audio file.
+     *
+     * @param url Audio URL or embedded resource key.
+     * @returns Decoded `AudioBuffer`.
+     */
     async load(url) {
         if (this.bufferCache.has(url)) {
             return this.bufferCache.get(url);
@@ -38,7 +56,12 @@ export class SoundSystem {
         this.bufferCache.set(url, buffer);
         return buffer;
     }
-    // ================= PLAY =================
+    /**
+     * Plays an audio file and returns the active source node.
+     *
+     * @param url Audio URL or embedded resource key.
+     * @param options Per-playback settings such as volume, loop, and speed.
+     */
     async play(url, options = {}) {
         const buffer = await this.load(url);
         const source = this.ctx.createBufferSource();
@@ -56,7 +79,9 @@ export class SoundSystem {
         };
         return source;
     }
-    // ================= STOP =================
+    /**
+     * Stops every source started through this `SoundSystem`.
+     */
     stopAll() {
         for (const s of this.activeSources) {
             try {
@@ -66,16 +91,25 @@ export class SoundSystem {
         }
         this.activeSources.clear();
     }
-    // ================= GLOBAL VOLUME =================
+    /**
+     * Sets the master volume for all current and future sounds.
+     *
+     * `1` is full volume, `0` is silent. Values above `1` amplify.
+     */
     setVolume(v) {
         this.masterGain.gain.value = v;
     }
-    // ================= CONTEXT CONTROL =================
+    /**
+     * Resumes the underlying `AudioContext` if the browser suspended it.
+     */
     async resume() {
         if (this.ctx.state === "suspended") {
             await this.ctx.resume();
         }
     }
+    /**
+     * Suspends the underlying `AudioContext` without clearing loaded buffers.
+     */
     async pause() {
         if (this.ctx.state === "running") {
             await this.ctx.suspend();

package/dist/storage/index.d.ts

@@ -1,19 +1,57 @@
+/**
+ * Wrapper shape for values that may receive expiration metadata in the future.
+ *
+ * The current `StorageLib` methods store raw values directly, so this type is
+ * mainly useful when callers want to manage their own `expiresAt` convention.
+ */
 export type StoredValue<T> = {
     value: T;
     expiresAt?: number;
 };
+/**
+ * Small typed wrapper around `localStorage`.
+ *
+ * Values are serialized with `JSON.stringify` and read with `JSON.parse`. If a
+ * value cannot be parsed, `get` returns `null` instead of throwing.
+ */
 export declare class StorageLib {
+    /**
+     * Stores a JSON-serializable value under a key.
+     */
     static set<T>(key: string, value: T): void;
+    /**
+     * Reads and parses a value from localStorage.
+     *
+     * @returns The parsed value or `null` when the key is missing or invalid JSON.
+     */
     static get<T>(key: string): T | null;
+    /**
+     * Removes a single key from localStorage.
+     */
     static remove(key: string): void;
+    /**
+     * Clears the complete browser localStorage for the current origin.
+     *
+     * Be careful: this affects all keys on the same domain, not only samengine
+     * keys.
+     */
     static clear(): void;
+    /**
+     * Checks whether a key exists in localStorage.
+     */
     static has(key: string): boolean;
     /**
-     * Gesamten Storage als JSON exportieren
+     * Exports the complete localStorage content as a JSON string.
+     *
+     * Existing JSON values are parsed back into objects; non-JSON values are kept
+     * as strings.
      */
     static exportToJson(pretty?: boolean): string;
     /**
-     * JSON in den Storage importieren
+     * Imports a JSON object into localStorage.
+     *
+     * @param json JSON object string, usually created by `exportToJson`.
+     * @param overwrite If false, existing keys are preserved.
      */
     static importFromJson(json: string, overwrite?: boolean): void;
 }

package/dist/storage/index.js

@@ -1,8 +1,21 @@
-// Store Data in the Browser
+/**
+ * Small typed wrapper around `localStorage`.
+ *
+ * Values are serialized with `JSON.stringify` and read with `JSON.parse`. If a
+ * value cannot be parsed, `get` returns `null` instead of throwing.
+ */
 export class StorageLib {
+    /**
+     * Stores a JSON-serializable value under a key.
+     */
     static set(key, value) {
         localStorage.setItem(key, JSON.stringify(value));
     }
+    /**
+     * Reads and parses a value from localStorage.
+     *
+     * @returns The parsed value or `null` when the key is missing or invalid JSON.
+     */
     static get(key) {
         const item = localStorage.getItem(key);
         if (!item) {
@@ -15,17 +28,32 @@ export class StorageLib {
             return null;
         }
     }
+    /**
+     * Removes a single key from localStorage.
+     */
     static remove(key) {
         localStorage.removeItem(key);
     }
+    /**
+     * Clears the complete browser localStorage for the current origin.
+     *
+     * Be careful: this affects all keys on the same domain, not only samengine
+     * keys.
+     */
     static clear() {
         localStorage.clear();
     }
+    /**
+     * Checks whether a key exists in localStorage.
+     */
     static has(key) {
         return localStorage.getItem(key) !== null;
     }
     /**
-     * Gesamten Storage als JSON exportieren
+     * Exports the complete localStorage content as a JSON string.
+     *
+     * Existing JSON values are parsed back into objects; non-JSON values are kept
+     * as strings.
      */
     static exportToJson(pretty = true) {
         const data = {};
@@ -44,7 +72,10 @@ export class StorageLib {
         return JSON.stringify(data, null, pretty ? 2 : 0);
     }
     /**
-     * JSON in den Storage importieren
+     * Imports a JSON object into localStorage.
+     *
+     * @param json JSON object string, usually created by `exportToJson`.
+     * @param overwrite If false, existing keys are preserved.
      */
     static importFromJson(json, overwrite = true) {
         const data = JSON.parse(json);

package/dist/text/index.d.ts

@@ -0,0 +1,14 @@
+import { type Rect } from "../types/index.js";
+/**
+ * For Text Input: Use canvasinput-ts
+ */
+export interface TextStyle {
+    color: string;
+    font: string;
+    size: number;
+}
+/**
+ * Rendert Text innerhalb eines Rechtecks mit automatischem Umbruch.
+ * Lange Wörter werden ebenfalls umgebrochen.
+ */
+export declare function renderTextBox(ctx: CanvasRenderingContext2D, rect: Rect, text: string, style: TextStyle, padding?: number): void;

package/dist/text/index.js

@@ -0,0 +1,58 @@
+/**
+ * Rendert Text innerhalb eines Rechtecks mit automatischem Umbruch.
+ * Lange Wörter werden ebenfalls umgebrochen.
+ */
+export function renderTextBox(ctx, rect, text, style, padding = 4) {
+    ctx.fillStyle = style.color;
+    ctx.font = `${style.size}px ${style.font}`;
+    ctx.textBaseline = "top";
+    const maxWidth = rect.width - padding * 2;
+    const lineHeight = style.size * 1.2;
+    let y = rect.y + padding;
+    const paragraphs = text.split("\n");
+    for (const paragraph of paragraphs) {
+        let line = "";
+        const words = paragraph.split(" ");
+        for (let word of words) {
+            // Wort zu lang → innerhalb des Wortes umbrechen
+            while (ctx.measureText(word).width > maxWidth) {
+                let chunk = "";
+                for (const char of word) {
+                    const test = chunk + char;
+                    if (ctx.measureText(test).width > maxWidth) {
+                        break;
+                    }
+                    chunk = test;
+                }
+                // Höhenbegrenzung
+                if (y + lineHeight > rect.y + rect.height) {
+                    return;
+                }
+                ctx.fillText(chunk, rect.x + padding, y);
+                y += lineHeight;
+                word = word.substring(chunk.length);
+            }
+            const testLine = line.length > 0
+                ? `${line} ${word}`
+                : word;
+            if (ctx.measureText(testLine).width > maxWidth) {
+                if (y + lineHeight > rect.y + rect.height) {
+                    return;
+                }
+                ctx.fillText(line, rect.x + padding, y);
+                y += lineHeight;
+                line = word;
+            }
+            else {
+                line = testLine;
+            }
+        }
+        if (line.length > 0) {
+            if (y + lineHeight > rect.y + rect.height) {
+                return;
+            }
+            ctx.fillText(line, rect.x + padding, y);
+            y += lineHeight;
+        }
+    }
+}

package/dist/texture.d.ts

@@ -1,37 +1,137 @@
 import { Rect } from "./types/rectangle.js";
+/**
+ * Loaded texture image.
+ *
+ * `undefined` means the texture was not loaded or the cache key does not exist.
+ */
 export type Texture = HTMLImageElement | undefined;
+/**
+ * Optional drawing settings used by texture, atlas, and animation rendering.
+ */
 export type DrawOptions = {
+    /** Target width before `scale` is applied. Defaults to source width. */
     width?: number;
+    /** Target height before `scale` is applied. Defaults to source height. */
     height?: number;
+    /** Rotation in radians around the rendered image center. */
     rotation?: number;
+    /** Mirrors the image horizontally around its center. */
     flipX?: boolean;
+    /** Mirrors the image vertically around its center. */
     flipY?: boolean;
+    /** Multiplies the final rendered width and height. */
     scale?: number;
 };
+/**
+ * Loads an image and stores it in the texture cache.
+ *
+ * Normal builds load from `/resources/${src}`. Single-file exports can provide
+ * embedded resources through `window.__resources`; if a matching key exists,
+ * that data URL is used instead. The cache key always remains the original
+ * `src` string, so `getTexture(src)` works the same in both modes.
+ *
+ * @param src Resource path relative to the resources folder.
+ * @returns Promise resolving to the loaded `HTMLImageElement`.
+ */
 export declare function loadTextureAsync(src: string): Promise<HTMLImageElement>;
+/**
+ * Reads a texture from the cache.
+ *
+ * This does not start loading by itself. Call `loadTextureAsync` first or handle
+ * the `undefined` result.
+ */
 export declare function getTexture(src: string): Texture;
+/**
+ * Draws a texture to the canvas.
+ *
+ * The image is drawn around its center for rotation and flipping, but `x` and
+ * `y` still describe the top-left target position. If the texture is missing,
+ * a magenta fallback rectangle is drawn to make missing assets visible.
+ */
 export declare function drawTexture(ctx: CanvasRenderingContext2D, texture: Texture, x: number, y: number, options?: DrawOptions): void;
+/**
+ * A spritesheet image plus named frame rectangles inside that image.
+ */
 export type TextureAtlas = {
+    /** Spritesheet image. */
     image: HTMLImageElement;
+    /** Named source rectangles inside `image`. */
     frames: Record<string, Rect>;
 };
+/**
+ * Loads a texture atlas image and its JSON frame data.
+ *
+ * The JSON file is fetched from the resources folder and must contain a
+ * `frames` object with frame names mapped to rectangles:
+ *
+ * ```json
+ * {
+ *   "frames": {
+ *     "player_idle_0": { "x": 0, "y": 0, "width": 32, "height": 32 }
+ *   }
+ * }
+ * ```
+ */
 export declare function loadAtlas(imageSrc: string, dataSrc: string): Promise<TextureAtlas>;
+/**
+ * Draws one named frame from a texture atlas.
+ *
+ * Missing frame names are logged through `dlog` and skipped.
+ */
 export declare function drawAtlasFrame(ctx: CanvasRenderingContext2D, atlas: TextureAtlas, frameName: string, x: number, y: number, options?: DrawOptions): void;
+/**
+ * Keeps track of time and current frame for a named-frame animation.
+ *
+ * The player only stores animation state. It does not draw anything by itself;
+ * call `drawAnimation` after `update(dt)` to render the current atlas frame.
+ */
 export declare class AnimationPlayer {
     animation: Animation;
     private time;
     private currentFrameIndex;
     private finished;
+    /**
+     * Creates a player for the given animation definition.
+     */
     constructor(animation: Animation);
+    /**
+     * Advances the animation by `deltaTime` seconds.
+     *
+     * Looping animations wrap back to the first frame. Non-looping animations
+     * stop on their final frame and then report `isFinished() === true`.
+     */
     update(deltaTime: number): void;
+    /**
+     * Returns the frame name that should currently be rendered from the atlas.
+     */
     getCurrentFrame(): string;
+    /**
+     * Restarts the animation from the first frame.
+     */
     reset(): void;
+    /**
+     * Returns whether a non-looping animation reached its final frame.
+     */
     isFinished(): boolean;
 }
+/**
+ * Animation definition based on named frames inside a `TextureAtlas`.
+ */
 export type Animation = {
+    /** Frame names in playback order. */
     frames: string[];
+    /** Playback speed in frames per second. */
     fps: number;
+    /** Whether playback should wrap to the first frame. Defaults to false-like. */
     loop?: boolean;
 };
+/**
+ * Draws the current frame of an `AnimationPlayer`.
+ */
 export declare function drawAnimation(ctx: CanvasRenderingContext2D, atlas: TextureAtlas, player: AnimationPlayer, x: number, y: number, options?: DrawOptions): void;
+/**
+ * Helper for side-view sprites.
+ *
+ * Returns `true` when a negative direction should flip a sprite horizontally.
+ */
 export declare function getFlipFromDirection(dir: number): boolean;