samengine 1.9.1 → 1.10.1

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;

package/dist/texture.js

@@ -3,7 +3,17 @@ const textures = {};
 function getresourcepath(path) {
     return "/resources/" + path;
 }
-// Function to load a Texture Async
+/**
+ * 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 function loadTextureAsync(src) {
     return new Promise((resolve, reject) => {
         // Wenn schon geladen
@@ -32,11 +42,22 @@ export function loadTextureAsync(src) {
         img.src = finalSrc;
     });
 }
-// Function to get the Texture
+/**
+ * Reads a texture from the cache.
+ *
+ * This does not start loading by itself. Call `loadTextureAsync` first or handle
+ * the `undefined` result.
+ */
 export function getTexture(src) {
     return textures[src];
 }
-// Function to draw a texture to the Screen
+/**
+ * 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 function drawTexture(ctx, texture, x, y, options = {}) {
     const { width, height, rotation = 0, flipX = false, flipY = false, scale = 1 } = options;
     if (!texture) {
@@ -56,17 +77,20 @@ export function drawTexture(ctx, texture, x, y, options = {}) {
     ctx.drawImage(texture, -w / 2, -h / 2, w, h);
     ctx.restore();
 }
-// Funtion to load an Atlas
-//
-// JSON Format for the LoadAtlas Function
-//
-// {
-//   "frames": {
-//     "player_idle_0": { "x": 0, "y": 0, "w": 32, "h": 32 },
-//     "player_idle_1": { "x": 32, "y": 0, "w": 32, "h": 32 }
-//   }
-// }
-//
+/**
+ * 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 async function loadAtlas(imageSrc, dataSrc) {
     const [image, data] = await Promise.all([
         loadTextureAsync(imageSrc),
@@ -77,6 +101,11 @@ export async function loadAtlas(imageSrc, dataSrc) {
         frames: data.frames
     };
 }
+/**
+ * Draws one named frame from a texture atlas.
+ *
+ * Missing frame names are logged through `dlog` and skipped.
+ */
 export function drawAtlasFrame(ctx, atlas, frameName, x, y, options = {}) {
     const { width, height, rotation = 0, flipX = false, flipY = false, scale = 1 } = options;
     const frame = atlas.frames[frameName];
@@ -95,40 +124,28 @@ export function drawAtlasFrame(ctx, atlas, frameName, x, y, options = {}) {
     ctx.drawImage(atlas.image, frame.x, frame.y, frame.width, frame.height, -w / 2, -h / 2, w, h);
     ctx.restore();
 }
-//
-//
-// Animation Player
-//
-//
-//
-// // Define Animation
-// const walkAnimation: Animation = {
-//     frames: ["walk_0", "walk_1", "walk_2", "walk_3"],
-//     fps: 8,
-//     loop: true
-// };
-//
-// const player = new AnimationPlayer(walkAnimation);
-//
-// // Game Loop
-// function update(dt: number) {
-//     player.update(dt);
-// }
-//
-// function render(ctx: CanvasRenderingContext2D) {
-//     drawAnimation(ctx, atlas, player, 100, 100, 64, 64);
-// }
-//
-//
-// Animation Player Class
+/**
+ * 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 class AnimationPlayer {
-    // Konstruktor Function
+    /**
+     * Creates a player for the given animation definition.
+     */
     constructor(animation) {
         this.animation = animation;
         this.time = 0;
         this.currentFrameIndex = 0;
         this.finished = false;
     }
+    /**
+     * 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) {
         if (this.finished)
             return;
@@ -148,22 +165,39 @@ export class AnimationPlayer {
             }
         }
     }
+    /**
+     * Returns the frame name that should currently be rendered from the atlas.
+     */
     getCurrentFrame() {
         return this.animation.frames[this.currentFrameIndex];
     }
+    /**
+     * Restarts the animation from the first frame.
+     */
     reset() {
         this.time = 0;
         this.currentFrameIndex = 0;
         this.finished = false;
     }
+    /**
+     * Returns whether a non-looping animation reached its final frame.
+     */
     isFinished() {
         return this.finished;
     }
 }
+/**
+ * Draws the current frame of an `AnimationPlayer`.
+ */
 export function drawAnimation(ctx, atlas, player, x, y, options = {}) {
     const frame = player.getCurrentFrame();
     drawAtlasFrame(ctx, atlas, frame, x, y, options);
 }
+/**
+ * Helper for side-view sprites.
+ *
+ * Returns `true` when a negative direction should flip a sprite horizontally.
+ */
 export function getFlipFromDirection(dir) {
     return dir < 0; // links = true
 }

package/dist/types/button.d.ts

@@ -1,9 +1,34 @@
 import { Rect } from "./rectangle.js";
 import { Mouse } from "../input.js";
+/**
+ * Simple canvas button model.
+ *
+ * The button is not a DOM element. It is drawn on the canvas and checked with
+ * mouse hit testing.
+ */
 export type Button = {
+    /** Rectangle that defines the button position and size. */
     form: Rect;
+    /** Text label drawn in the button center. */
     text: string;
 };
+/**
+ * Creates a canvas button description.
+ */
 export declare function makeButton(form: Rect, text: string): Button;
+/**
+ * Returns true when the button rectangle was clicked during the current frame.
+ */
 export declare function clickedButton(btn: Button, mouse: Mouse): boolean;
+/**
+ * Draws a simple filled rectangle button with centered text.
+ */
 export declare function drawButton(btn: Button, ctx: CanvasRenderingContext2D, color?: string, textColor?: string, font?: string): void;
+/**
+ * Check if the Button is hovered
+ */
+export declare function isButtonhovered(btn: Button, mouse: Mouse): boolean;
+/**
+ * Check if the Button is pressed!
+ */
+export declare function isButtonpressed(btn: Button, mouse: Mouse): boolean;

package/dist/types/button.js

@@ -1,8 +1,12 @@
 // Button
+import { isMouseInRect } from "./rectangle.js";
 import { isRectClicked } from "./rectangle.js";
 import { drawRect } from "../renderer.js";
 import { renderText } from "../renderer.js";
 // Function to create a new Button Type
+/**
+ * Creates a canvas button description.
+ */
 export function makeButton(form, text) {
     return {
         form: form,
@@ -10,10 +14,16 @@ export function makeButton(form, text) {
     };
 }
 // Prüft, ob der Button geklickt wurde
+/**
+ * Returns true when the button rectangle was clicked during the current frame.
+ */
 export function clickedButton(btn, mouse) {
     return isRectClicked(mouse, btn.form);
 }
 // Zeichnet den Button (Rechteck + Text)
+/**
+ * Draws a simple filled rectangle button with centered text.
+ */
 export function drawButton(btn, ctx, color = "#444", textColor = "white", font = "20px Arial") {
     drawRect(ctx, btn.form, color);
     // Text mittig im Button platzieren
@@ -23,3 +33,15 @@ export function drawButton(btn, ctx, color = "#444", textColor = "white", font =
     ctx.textBaseline = "middle";
     renderText(ctx, btn.text, textX, textY, textColor, font);
 }
+/**
+ * Check if the Button is hovered
+ */
+export function isButtonhovered(btn, mouse) {
+    return isMouseInRect(mouse, btn.form);
+}
+/**
+ * Check if the Button is pressed!
+ */
+export function isButtonpressed(btn, mouse) {
+    return isRectClicked(mouse, btn.form);
+}