samengine 1.9.0 → 1.10.0

package/dist/samegui/index.js

@@ -0,0 +1,137 @@
+// 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();
+        this.clicked = new Map();
+        this.frameIds = [];
+        this.valueMap = new Map();
+        this.root = document.createElement("div");
+        this.root.style.position = "absolute";
+        this.root.style.inset = "0";
+        this.root.style.pointerEvents = "none";
+        document.body.appendChild(this.root);
+        this.panel = document.createElement("div");
+        this.panel.style.position = "absolute";
+        this.panel.style.left = "20px";
+        this.panel.style.top = "20px";
+        this.panel.style.padding = "10px";
+        this.panel.style.background = "rgba(30,30,30,0.9)";
+        this.panel.style.color = "white";
+        this.panel.style.pointerEvents = "auto";
+        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) {
+            this.clicked.set(id, false);
+        }
+    }
+    getButton(id) {
+        let e = this.elements.get(id);
+        if (!e) {
+            const btn = document.createElement("button");
+            btn.style.display = "block";
+            btn.style.marginBottom = "6px";
+            btn.style.width = "100%";
+            btn.style.padding = "6px";
+            btn.style.background = "#444";
+            btn.style.color = "white";
+            btn.style.border = "none";
+            btn.style.cursor = "pointer";
+            this.panel.appendChild(btn);
+            e = { el: btn, type: "button" };
+            this.elements.set(id, e);
+        }
+        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);
+        const btn = this.getButton(id);
+        btn.textContent = label;
+        // wichtig: nur EIN handler (kein stacking!)
+        btn.onclick = () => {
+            this.clicked.set(id, true);
+        };
+        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);
+        let e = this.elements.get(id);
+        if (!e) {
+            const div = document.createElement("div");
+            div.style.marginBottom = "6px";
+            this.panel.appendChild(div);
+            e = { el: div, type: "text" };
+            this.elements.set(id, e);
+        }
+        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);
+        // initial state only once
+        if (!this.valueMap.has(id)) {
+            this.valueMap.set(id, defaultValue);
+        }
+        const current = this.valueMap.get(id);
+        let e = this.elements.get(id);
+        if (!e) {
+            const wrapper = document.createElement("label");
+            wrapper.style.display = "flex";
+            wrapper.style.alignItems = "center";
+            wrapper.style.gap = "8px";
+            wrapper.style.marginBottom = "6px";
+            wrapper.style.cursor = "pointer";
+            const input = document.createElement("input");
+            input.type = "checkbox";
+            const text = document.createElement("span");
+            wrapper.appendChild(input);
+            wrapper.appendChild(text);
+            this.panel.appendChild(wrapper);
+            e = { el: wrapper, type: "checkbox" };
+            this.elements.set(id, e);
+        }
+        const wrapper = e.el;
+        const input = wrapper.querySelector("input");
+        const text = wrapper.querySelector("span");
+        text.textContent = label;
+        input.checked = current;
+        input.onchange = () => {
+            this.valueMap.set(id, input.checked);
+        };
+        return current;
+    }
+}

package/dist/save.d.ts

@@ -1,6 +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,5 +1,15 @@
 // 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) {
     try {
         const json = JSON.stringify(data);
@@ -10,6 +20,11 @@ export function saveGame(data) {
         console.error("Save failed:", err);
     }
 }
+/**
+ * Loads and parses JSON save data from `SAVE_KEY`.
+ *
+ * @deprecated Use samengine/storage instead
+ */
 export function loadGame() {
     try {
         const json = localStorage.getItem(SAVE_KEY);
@@ -22,10 +37,20 @@ export function loadGame() {
         return null;
     }
 }
+/**
+ * Removes the current save entry from localStorage.
+ *
+ * @deprecated Use samengine/storage instead
+ */
 export function clearSave() {
     localStorage.removeItem(SAVE_KEY);
     console.log("Save cleared!");
 }
+/**
+ * Downloads the current save data as `savegame.json`.
+ *
+ * @deprecated Use samengine/storage instead
+ */
 export function exportSave() {
     try {
         const json = localStorage.getItem(SAVE_KEY);

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

@@ -0,0 +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;
+    /**
+     * 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;
+    /**
+     * 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

@@ -0,0 +1,89 @@
+/**
+ * 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) {
+            return null;
+        }
+        try {
+            return JSON.parse(item);
+        }
+        catch {
+            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;
+    }
+    /**
+     * 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 = {};
+        for (let i = 0; i < localStorage.length; i++) {
+            const key = localStorage.key(i);
+            if (!key)
+                continue;
+            const value = localStorage.getItem(key);
+            try {
+                data[key] = value ? JSON.parse(value) : null;
+            }
+            catch {
+                data[key] = value;
+            }
+        }
+        return JSON.stringify(data, null, pretty ? 2 : 0);
+    }
+    /**
+     * 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);
+        for (const [key, value] of Object.entries(data)) {
+            if (!overwrite && localStorage.getItem(key) !== null) {
+                continue;
+            }
+            localStorage.setItem(key, JSON.stringify(value));
+        }
+    }
+}

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;
+        }
+    }
+}