samengine 1.9.0 → 1.9.1

package/README.md

@@ -4,6 +4,41 @@ A lightweight, TypeScript-first web game engine framework for building
 2D games *and maybe 3D Games in the Future*.
 
 
+<!--$$MD_INDEX_START$$-->
+<!-- 
+    Index by Automatic MD Index
+    a simple Tool to Index your Markdown files like this
+
+    More Infos:
+    https://github.com/ShadowDara/automatic-md-index
+
+    DO NOT REMOVE THIS CREDIT !!!
+
+    Last Update Time of the Index: 
+-->
+
+## Index
+  - [Features](#features)
+  - [Info](#info)
+  - [Quick Start](#quick-start)
+    - [Basic Game Loop](#basic-game-loop)
+  - [Development & Building](#development-building)
+    - [Using Bun (local development)](#using-bun-local-development)
+  - [Config](#config)
+  - [API Reference](#api-reference)
+    - [Core Engine](#core-engine)
+    - [Rendering](#rendering)
+    - [Input System](#input-system)
+    - [Types](#types)
+    - [Utilities](#utilities)
+  - [License](#license)
+  - [More Addons in the Game Library](#more-addons-in-the-game-library)
+  - [More Tools for samengine and Game Making by me lol](#more-tools-for-samengine-and-game-making-by-me-lol)
+  - [Commit Tags](#commit-tags)
+<!-- Index by Automatic MD Index -->
+<!--$$MD_INDEX_END$$-->
+
+
 ## Features
 
 - 🎯 Simple game loop management

package/dist/index.d.ts

@@ -1,5 +1,6 @@
 export { startEngine } from "./core.js";
-export { renderText, renderBitmapText, drawRect, drawRectOutline, drawCircle, drawCircleOutline, drawTriangle, drawTriangleOutline, } from "./renderer.js";
+export type { CharMap, ParallaxLayer } from "./renderer.js";
+export { renderText, renderBitmapText, drawRect, drawRectOutline, drawCircle, drawCircleOutline, drawTriangle, drawTriangleOutline, renderParallaxBackground, renderParallaxLayers, } from "./renderer.js";
 export type { Mouse } from "./input.js";
 export { setupInput, isKeyPressed, isKeyJustPressed, isKeyJustReleased, resetInput, getMouse } from "./input.js";
 export { dlog } from "./logger.js";

package/dist/index.js

@@ -1,7 +1,6 @@
 // Core Engine Exports
 export { startEngine } from "./core.js";
-// Rendering
-export { renderText, renderBitmapText, drawRect, drawRectOutline, drawCircle, drawCircleOutline, drawTriangle, drawTriangleOutline, } from "./renderer.js";
+export { renderText, renderBitmapText, drawRect, drawRectOutline, drawCircle, drawCircleOutline, drawTriangle, drawTriangleOutline, renderParallaxBackground, renderParallaxLayers, } from "./renderer.js";
 export { setupInput, isKeyPressed, isKeyJustPressed, isKeyJustReleased, resetInput, getMouse } from "./input.js";
 // Logging
 export { dlog } from "./logger.js";

package/dist/renderer.d.ts

@@ -2,7 +2,7 @@ import { type Rect } from "./types/rectangle.js";
 import { type Circle } from "./types/circle.js";
 import { type Triangle } from "./types/triangle.js";
 export declare function renderText(ctx: CanvasRenderingContext2D, text: string, x: number, y: number, color?: string, font?: string): void;
-type CharMap = Record<string, Rect>;
+export type CharMap = Record<string, Rect>;
 export declare function renderBitmapText(ctx: CanvasRenderingContext2D, text: string, x: number, y: number, sprite: HTMLImageElement, charMap: CharMap, scale?: number): void;
 export declare function drawRect(ctx: CanvasRenderingContext2D, rect: Rect, color?: string): void;
 export declare function drawRectOutline(ctx: CanvasRenderingContext2D, rect: Rect, color?: string, lineWidth?: number): void;
@@ -10,4 +10,9 @@ export declare function drawCircle(ctx: CanvasRenderingContext2D, circle: Circle
 export declare function drawCircleOutline(ctx: CanvasRenderingContext2D, circle: Circle, color?: string, lineWidth?: number): void;
 export declare function drawTriangle(ctx: CanvasRenderingContext2D, triangle: Triangle, color?: string): void;
 export declare function drawTriangleOutline(ctx: CanvasRenderingContext2D, triangle: Triangle, color?: string, lineWidth?: number): void;
-export {};
+export declare function renderParallaxBackground(ctx: CanvasRenderingContext2D, image: HTMLImageElement, cameraX: number, speed?: number, canvasWidth?: number, canvasHeight?: number): void;
+export interface ParallaxLayer {
+    image: HTMLImageElement;
+    speed: number;
+}
+export declare function renderParallaxLayers(ctx: CanvasRenderingContext2D, layers: ParallaxLayer[], cameraX: number): void;

package/dist/renderer.js

@@ -79,3 +79,19 @@ export function drawTriangleOutline(ctx, triangle, color = "white", lineWidth =
     ctx.closePath();
     ctx.stroke();
 }
+// Function to render a parallax background layer
+export function renderParallaxBackground(ctx, image, cameraX, speed = 0.5, canvasWidth = ctx.canvas.width, canvasHeight = ctx.canvas.height) {
+    if (!image.complete)
+        return;
+    const offsetX = -(cameraX * speed) % image.width;
+    // Draw enough copies to fill the screen
+    for (let x = offsetX - image.width; x < canvasWidth; x += image.width) {
+        ctx.drawImage(image, x, 0, image.width, canvasHeight);
+    }
+}
+// Render multiple paralax Layers
+export function renderParallaxLayers(ctx, layers, cameraX) {
+    for (const layer of layers) {
+        renderParallaxBackground(ctx, layer.image, cameraX, layer.speed);
+    }
+}

package/dist/samegui/index.d.ts

@@ -0,0 +1,20 @@
+export type UIElementType = "button" | "text" | "checkbox";
+export type UIElement = {
+    el: HTMLElement;
+    type: UIElementType;
+};
+export declare class HtmlUI {
+    private root;
+    private panel;
+    private elements;
+    private clicked;
+    private frameIds;
+    private valueMap;
+    constructor();
+    begin(): void;
+    end(): void;
+    private getButton;
+    button(label: string, idOverride?: string): boolean;
+    text(label: string, idOverride?: string): void;
+    checkbox(label: string, defaultValue: boolean, idOverride?: string): boolean;
+}

package/dist/samegui/index.js

@@ -0,0 +1,111 @@
+// HTML Overlay
+import { hash } from "../utils/index.js";
+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);
+    }
+    begin() {
+        this.frameIds = [];
+    }
+    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;
+    }
+    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;
+    }
+    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;
+    }
+    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,24 @@
+/**
+ * @deprecated Use samengine/storage instead
+ */
 export type SaveData = Record<string, any>;
+/**
+ * @deprecated Use samengine/storage instead
+ */
 export declare let SAVE_KEY: string;
+/**
+ * @deprecated Use samengine/storage instead
+ */
 export declare function saveGame(data: SaveData): void;
+/**
+ * @deprecated Use samengine/storage instead
+ */
 export declare function loadGame(): SaveData | null;
+/**
+ * @deprecated Use samengine/storage instead
+ */
 export declare function clearSave(): void;
+/**
+ * @deprecated Use samengine/storage instead
+ */
 export declare function exportSave(): void;

package/dist/save.js

@@ -1,5 +1,11 @@
 // Please rename the SaveKey
+/**
+ * @deprecated Use samengine/storage instead
+ */
 export let SAVE_KEY = "my_game_save";
+/**
+ * @deprecated Use samengine/storage instead
+ */
 export function saveGame(data) {
     try {
         const json = JSON.stringify(data);
@@ -10,6 +16,9 @@ export function saveGame(data) {
         console.error("Save failed:", err);
     }
 }
+/**
+ * @deprecated Use samengine/storage instead
+ */
 export function loadGame() {
     try {
         const json = localStorage.getItem(SAVE_KEY);
@@ -22,10 +31,16 @@ export function loadGame() {
         return null;
     }
 }
+/**
+ * @deprecated Use samengine/storage instead
+ */
 export function clearSave() {
     localStorage.removeItem(SAVE_KEY);
     console.log("Save cleared!");
 }
+/**
+ * @deprecated Use samengine/storage instead
+ */
 export function exportSave() {
     try {
         const json = localStorage.getItem(SAVE_KEY);

package/dist/storage/index.d.ts

@@ -0,0 +1,19 @@
+export type StoredValue<T> = {
+    value: T;
+    expiresAt?: number;
+};
+export declare class StorageLib {
+    static set<T>(key: string, value: T): void;
+    static get<T>(key: string): T | null;
+    static remove(key: string): void;
+    static clear(): void;
+    static has(key: string): boolean;
+    /**
+     * Gesamten Storage als JSON exportieren
+     */
+    static exportToJson(pretty?: boolean): string;
+    /**
+     * JSON in den Storage importieren
+     */
+    static importFromJson(json: string, overwrite?: boolean): void;
+}

package/dist/storage/index.js

@@ -0,0 +1,58 @@
+// Store Data in the Browser
+export class StorageLib {
+    static set(key, value) {
+        localStorage.setItem(key, JSON.stringify(value));
+    }
+    static get(key) {
+        const item = localStorage.getItem(key);
+        if (!item) {
+            return null;
+        }
+        try {
+            return JSON.parse(item);
+        }
+        catch {
+            return null;
+        }
+    }
+    static remove(key) {
+        localStorage.removeItem(key);
+    }
+    static clear() {
+        localStorage.clear();
+    }
+    static has(key) {
+        return localStorage.getItem(key) !== null;
+    }
+    /**
+     * Gesamten Storage als JSON exportieren
+     */
+    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);
+    }
+    /**
+     * JSON in den Storage importieren
+     */
+    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/types/rectangle.js

@@ -29,6 +29,7 @@ export function isPointInRect(x, y, rect) {
         y >= rect.y &&
         y <= rect.y + rect.height);
 }
+// Is Rectangle Hovered
 export function isMouseInRect(mouse, rect) {
     return (mouse.x >= rect.x &&
         mouse.x <= rect.x + rect.width &&

package/dist/utils/csv/index.d.ts

@@ -0,0 +1,3 @@
+export { CSVParser } from "./parser.js";
+export { CSVStringifier } from "./stringifier.js";
+export type { CSVParserOptions, CSVStringifierOptions, EscapeRules, ParseResult } from "./types.js";

package/dist/utils/csv/index.js

@@ -0,0 +1,2 @@
+export { CSVParser } from "./parser.js";
+export { CSVStringifier } from "./stringifier.js";

package/dist/utils/csv/parser.d.ts

@@ -0,0 +1,25 @@
+import type { CSVParserOptions, ParseResult } from "./types";
+/**
+ * RFC 4180-konformer CSV-Parser mit erweitertem Escaping.
+ *
+ * Unterstützt:
+ *  - Gequotete Felder mit eingebetteten Zeilenumbrüchen, Trennzeichen und Anführungszeichen
+ *  - Doppelt-Anführungszeichen-Escaping: "" → "
+ *  - Optionales Backslash-Escaping: \" → "
+ *  - Konfigurierbare Trennzeichen, Anführungszeichen, Kommentar-Zeilen
+ *  - Warnung bei ungleicher Feldanzahl
+ */
+export declare class CSVParser {
+    private readonly opts;
+    constructor(options?: CSVParserOptions);
+    /**
+     * Parst einen CSV-String und gibt strukturierte Daten zurück.
+     */
+    parse<T = Record<string, string>>(text: string): ParseResult<T>;
+    /**
+     * Parst einen CSV-String und gibt ausschließlich die Records zurück.
+     * Kurzform für einfache Anwendungsfälle.
+     */
+    parseRecords<T = Record<string, string>>(text: string): T[];
+    private tokenize;
+}

package/dist/utils/csv/parser.js

@@ -0,0 +1,212 @@
+const DEFAULT_OPTIONS = {
+    delimiter: ",",
+    quoteChar: '"',
+    escapeChar: "",
+    hasHeader: true,
+    trimFields: false,
+    skipEmptyLines: true,
+    commentChar: "",
+};
+/**
+ * RFC 4180-konformer CSV-Parser mit erweitertem Escaping.
+ *
+ * Unterstützt:
+ *  - Gequotete Felder mit eingebetteten Zeilenumbrüchen, Trennzeichen und Anführungszeichen
+ *  - Doppelt-Anführungszeichen-Escaping: "" → "
+ *  - Optionales Backslash-Escaping: \" → "
+ *  - Konfigurierbare Trennzeichen, Anführungszeichen, Kommentar-Zeilen
+ *  - Warnung bei ungleicher Feldanzahl
+ */
+export class CSVParser {
+    constructor(options = {}) {
+        this.opts = { ...DEFAULT_OPTIONS, ...options };
+        if (this.opts.delimiter.length !== 1) {
+            throw new Error("delimiter muss genau ein Zeichen lang sein.");
+        }
+        if (this.opts.quoteChar.length !== 1) {
+            throw new Error("quoteChar muss genau ein Zeichen lang sein.");
+        }
+        if (this.opts.escapeChar && this.opts.escapeChar.length !== 1) {
+            throw new Error("escapeChar muss genau ein Zeichen lang sein.");
+        }
+    }
+    /**
+     * Parst einen CSV-String und gibt strukturierte Daten zurück.
+     */
+    parse(text) {
+        const rawRows = this.tokenize(text);
+        const warnings = [];
+        if (rawRows.length === 0) {
+            return { records: [], headers: [], rawRows: [], warnings };
+        }
+        let headers = [];
+        let dataRows;
+        if (this.opts.hasHeader) {
+            headers = rawRows[0].map((h) => this.opts.trimFields ? h.trim() : h);
+            dataRows = rawRows.slice(1);
+        }
+        else {
+            // Numerische Header generieren: "0", "1", "2", ...
+            const width = rawRows[0].length;
+            headers = Array.from({ length: width }, (_, i) => String(i));
+            dataRows = rawRows;
+        }
+        const records = [];
+        for (let i = 0; i < dataRows.length; i++) {
+            const row = dataRows[i];
+            if (row.length !== headers.length) {
+                warnings.push({
+                    row: i + (this.opts.hasHeader ? 2 : 1),
+                    message: `Zeile hat ${row.length} Felder, erwartet ${headers.length}.`,
+                });
+            }
+            const record = {};
+            for (let j = 0; j < headers.length; j++) {
+                let value = row[j] ?? "";
+                if (this.opts.trimFields)
+                    value = value.trim();
+                record[headers[j]] = value;
+            }
+            records.push(record);
+        }
+        return { records, headers, rawRows, warnings };
+    }
+    /**
+     * Parst einen CSV-String und gibt ausschließlich die Records zurück.
+     * Kurzform für einfache Anwendungsfälle.
+     */
+    parseRecords(text) {
+        return this.parse(text).records;
+    }
+    // ─────────────────────────────────────────────
+    // Privater Tokenizer (Zustandsmaschine)
+    // ─────────────────────────────────────────────
+    tokenize(text) {
+        const { delimiter, quoteChar, escapeChar, skipEmptyLines, commentChar } = this.opts;
+        const rows = [];
+        let row = [];
+        let field = "";
+        let inQuotes = false;
+        let i = 0;
+        const len = text.length;
+        const pushRow = () => {
+            const isEmpty = row.length === 1 && row[0] === "" && field === "";
+            if (skipEmptyLines && isEmpty)
+                return;
+            if (commentChar && row.length === 0 && field.startsWith(commentChar))
+                return;
+            row.push(field);
+            rows.push(row);
+            row = [];
+            field = "";
+        };
+        while (i < len) {
+            const ch = text[i];
+            const next = i + 1 < len ? text[i + 1] : "";
+            if (inQuotes) {
+                // Backslash-Escape innerhalb von Quotes
+                if (escapeChar && ch === escapeChar && next === quoteChar) {
+                    field += quoteChar;
+                    i += 2;
+                    continue;
+                }
+                // Doppeltes Anführungszeichen → ein literales Anführungszeichen
+                if (ch === quoteChar && next === quoteChar) {
+                    field += quoteChar;
+                    i += 2;
+                    continue;
+                }
+                // Schließendes Anführungszeichen
+                if (ch === quoteChar) {
+                    inQuotes = false;
+                    i++;
+                    continue;
+                }
+                field += ch;
+                i++;
+                continue;
+            }
+            // Außerhalb von Quotes:
+            // Kommentarzeile (nur am Zeilenanfang)
+            if (commentChar && ch === commentChar && row.length === 0 && field === "") {
+                // Rest der Zeile überspringen
+                while (i < len && text[i] !== "\n" && text[i] !== "\r")
+                    i++;
+                continue;
+            }
+            // Öffnendes Anführungszeichen
+            if (ch === quoteChar) {
+                inQuotes = true;
+                i++;
+                continue;
+            }
+            // Backslash-Escape außerhalb von Quotes (optionales Feature)
+            if (escapeChar && ch === escapeChar) {
+                if (next === "n") {
+                    field += "\n";
+                    i += 2;
+                    continue;
+                }
+                if (next === "r") {
+                    field += "\r";
+                    i += 2;
+                    continue;
+                }
+                if (next === "t") {
+                    field += "\t";
+                    i += 2;
+                    continue;
+                }
+                if (next === "0") {
+                    field += "\0";
+                    i += 2;
+                    continue;
+                }
+                if (next === escapeChar) {
+                    field += escapeChar;
+                    i += 2;
+                    continue;
+                }
+                if (next === delimiter) {
+                    field += delimiter;
+                    i += 2;
+                    continue;
+                }
+                // Unbekannte Escape-Sequenz: Backslash literal übernehmen
+                field += ch;
+                i++;
+                continue;
+            }
+            // Trennzeichen
+            if (ch === delimiter) {
+                row.push(field);
+                field = "";
+                i++;
+                continue;
+            }
+            // Zeilenumbruch \r\n
+            if (ch === "\r" && next === "\n") {
+                pushRow();
+                i += 2;
+                continue;
+            }
+            // Zeilenumbruch \r oder \n
+            if (ch === "\n" || ch === "\r") {
+                pushRow();
+                i++;
+                continue;
+            }
+            field += ch;
+            i++;
+        }
+        // Letzte Zeile (kein abschließendes Newline)
+        if (row.length > 0 || field !== "") {
+            row.push(field);
+            const isEmpty = row.length === 1 && row[0] === "";
+            if (!(skipEmptyLines && isEmpty)) {
+                rows.push(row);
+            }
+        }
+        return rows;
+    }
+}

package/dist/utils/csv/stringifier.d.ts

@@ -0,0 +1,30 @@
+import type { CSVStringifierOptions } from "./types";
+/**
+ * Serialisiert JavaScript-Objekte zu einem validen CSV-String.
+ *
+ * Unterstützt:
+ *  - RFC 4180 Doppelquote-Escaping: " → ""
+ *  - Optionales Backslash-Escaping: \ → \\
+ *  - Optionales Null-Byte-Escaping: \0 → \\0
+ *  - Automatisches Quoting bei Sonderzeichen
+ *  - Konfigurierbare Spaltenreihenfolge
+ *  - Wahlweise immer quoten (alwaysQuote)
+ */
+export declare class CSVStringifier {
+    private readonly opts;
+    private readonly escapeRules;
+    constructor(options?: CSVStringifierOptions);
+    /**
+     * Serialisiert ein Array von Objekten zu einem CSV-String.
+     */
+    stringify(records: Record<string, unknown>[]): string;
+    /**
+     * Serialisiert ein einzelnes Feld mit korrektem Escaping.
+     * Öffentlich, damit einzelne Werte unabhängig escaped werden können.
+     */
+    escapeField(raw: string): string;
+    /**
+     * Streamt Records zeilenweise als Generator (speicherschonend für große Dateien).
+     */
+    stream(records: Iterable<Record<string, unknown>>, columns: string[]): Generator<string>;
+}

package/dist/utils/csv/stringifier.js

@@ -0,0 +1,130 @@
+const DEFAULT_ESCAPE_RULES = {
+    quote: true,
+    newline: true,
+    delimiter: true,
+    backslash: false,
+    nullByte: false,
+};
+const DEFAULT_OPTIONS = {
+    delimiter: ",",
+    quoteChar: '"',
+    lineEnding: "\r\n",
+    escapeRules: DEFAULT_ESCAPE_RULES,
+    alwaysQuote: false,
+    columns: [],
+    writeHeader: true,
+    nullAsEmpty: true,
+};
+/**
+ * Serialisiert JavaScript-Objekte zu einem validen CSV-String.
+ *
+ * Unterstützt:
+ *  - RFC 4180 Doppelquote-Escaping: " → ""
+ *  - Optionales Backslash-Escaping: \ → \\
+ *  - Optionales Null-Byte-Escaping: \0 → \\0
+ *  - Automatisches Quoting bei Sonderzeichen
+ *  - Konfigurierbare Spaltenreihenfolge
+ *  - Wahlweise immer quoten (alwaysQuote)
+ */
+export class CSVStringifier {
+    constructor(options = {}) {
+        this.opts = {
+            ...DEFAULT_OPTIONS,
+            ...options,
+            escapeRules: {
+                ...DEFAULT_ESCAPE_RULES,
+                ...(options.escapeRules ?? {}),
+            },
+        };
+        this.escapeRules = this.opts.escapeRules;
+        if (this.opts.delimiter.length !== 1) {
+            throw new Error("delimiter muss genau ein Zeichen lang sein.");
+        }
+        if (this.opts.quoteChar.length !== 1) {
+            throw new Error("quoteChar muss genau ein Zeichen lang sein.");
+        }
+    }
+    /**
+     * Serialisiert ein Array von Objekten zu einem CSV-String.
+     */
+    stringify(records) {
+        if (records.length === 0)
+            return "";
+        const columns = this.opts.columns.length > 0
+            ? this.opts.columns
+            : Object.keys(records[0]);
+        const lines = [];
+        if (this.opts.writeHeader) {
+            lines.push(columns.map((h) => this.escapeField(h)).join(this.opts.delimiter));
+        }
+        for (const record of records) {
+            const row = columns.map((col) => {
+                const value = record[col];
+                if ((value === null || value === undefined) && this.opts.nullAsEmpty) {
+                    return "";
+                }
+                return this.escapeField(String(value ?? ""));
+            });
+            lines.push(row.join(this.opts.delimiter));
+        }
+        return lines.join(this.opts.lineEnding);
+    }
+    /**
+     * Serialisiert ein einzelnes Feld mit korrektem Escaping.
+     * Öffentlich, damit einzelne Werte unabhängig escaped werden können.
+     */
+    escapeField(raw) {
+        const { delimiter, quoteChar, alwaysQuote } = this.opts;
+        const rules = this.escapeRules;
+        let value = raw;
+        let needsQuoting = alwaysQuote;
+        // 1. Backslash escapen (muss vor allen anderen stehen)
+        if (rules.backslash && value.includes("\\")) {
+            value = value.replace(/\\/g, "\\\\");
+            needsQuoting = true;
+        }
+        // 2. Null-Byte escapen
+        if (rules.nullByte && value.includes("\0")) {
+            value = value.replace(/\0/g, "\\0");
+            needsQuoting = true;
+        }
+        // 3. Anführungszeichen escapen (RFC 4180: "" Verdopplung)
+        if (rules.quote && value.includes(quoteChar)) {
+            // Needs ES2021
+            // value = value.replaceAll(quoteChar, quoteChar + quoteChar);
+            value = value.split(quoteChar).join(quoteChar + quoteChar);
+            needsQuoting = true;
+        }
+        // 4. Zeilenumbrüche → brauchen Quoting
+        if (rules.newline && (value.includes("\n") || value.includes("\r"))) {
+            needsQuoting = true;
+        }
+        // 5. Trennzeichen im Wert → braucht Quoting
+        if (rules.delimiter && value.includes(delimiter)) {
+            needsQuoting = true;
+        }
+        if (needsQuoting) {
+            return `${quoteChar}${value}${quoteChar}`;
+        }
+        return value;
+    }
+    /**
+     * Streamt Records zeilenweise als Generator (speicherschonend für große Dateien).
+     */
+    *stream(records, columns) {
+        const { delimiter, lineEnding, writeHeader } = this.opts;
+        if (writeHeader) {
+            yield columns.map((h) => this.escapeField(h)).join(delimiter) + lineEnding;
+        }
+        for (const record of records) {
+            const row = columns.map((col) => {
+                const value = record[col];
+                if ((value === null || value === undefined) && this.opts.nullAsEmpty) {
+                    return "";
+                }
+                return this.escapeField(String(value ?? ""));
+            });
+            yield row.join(delimiter) + lineEnding;
+        }
+    }
+}

package/dist/utils/csv/types.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Regeln, welche Zeichen escaped werden sollen.
+ */
+export interface EscapeRules {
+    /** Verdoppelt Anführungszeichen innerhalb von Feldern: " → "" */
+    quote?: boolean;
+    /** Felder mit Zeilenumbrüchen werden gequotet */
+    newline?: boolean;
+    /** Felder, die das Trennzeichen enthalten, werden gequotet */
+    delimiter?: boolean;
+    /** Backslashes werden escaped: \ → \\ */
+    backslash?: boolean;
+    /** Null-Bytes werden escaped: \0 → \\0 */
+    nullByte?: boolean;
+}
+export interface CSVParserOptions {
+    /** Trennzeichen (Standard: ",") */
+    delimiter?: string;
+    /** Anführungszeichen-Zeichen (Standard: '"') */
+    quoteChar?: string;
+    /** Escape-Zeichen für Backslash-Escaping (Standard: kein Backslash-Escape) */
+    escapeChar?: string;
+    /** Erste Zeile als Header interpretieren (Standard: true) */
+    hasHeader?: boolean;
+    /** Führende/nachfolgende Leerzeichen in Feldern trimmen (Standard: false) */
+    trimFields?: boolean;
+    /** Leere Zeilen überspringen (Standard: true) */
+    skipEmptyLines?: boolean;
+    /** Kommentare überspringen (z. B. "#") — leer = deaktiviert */
+    commentChar?: string;
+}
+export interface CSVStringifierOptions {
+    /** Trennzeichen (Standard: ",") */
+    delimiter?: string;
+    /** Anführungszeichen-Zeichen (Standard: '"') */
+    quoteChar?: string;
+    /** Zeilenende (Standard: "\r\n" per RFC 4180) */
+    lineEnding?: "\r\n" | "\n" | "\r";
+    /** Escape-Regeln */
+    escapeRules?: EscapeRules;
+    /** Alle Felder immer quoten, unabhängig vom Inhalt (Standard: false) */
+    alwaysQuote?: boolean;
+    /** Spaltenreihenfolge (Standard: Reihenfolge der Keys im ersten Objekt) */
+    columns?: string[];
+    /** Header-Zeile schreiben (Standard: true) */
+    writeHeader?: boolean;
+    /** Null / undefined als leeres Feld ausgeben (Standard: true) */
+    nullAsEmpty?: boolean;
+}
+export interface ParseResult<T = Record<string, string>> {
+    /** Geparste Datensätze als Array von Objekten */
+    records: T[];
+    /** Header-Zeile (falls hasHeader = true) */
+    headers: string[];
+    /** Rohe Zeilen als String-Arrays (inkl. Header) */
+    rawRows: string[][];
+    /** Warnungen (z. B. ungleich viele Felder) */
+    warnings: ParseWarning[];
+}
+export interface ParseWarning {
+    row: number;
+    message: string;
+}

package/dist/utils/csv/types.js

@@ -0,0 +1 @@
+export {};

package/dist/utils/index.d.ts

@@ -3,3 +3,5 @@ export type { ParseOptions as MarkdownParseOptions } from "./markdown.js";
 export { parse as parseMarkdown, parseToDocument as parseMarkdownToDocument, exportcss as exportMarkdownCSS } from "./markdown.js";
 export type { JSONValue } from "./jsonc-parser.js";
 export { parseJSONC } from "./jsonc-parser.js";
+export declare function hash(str: string): number;
+export declare function shuffle<T>(array: T[]): T[];

package/dist/utils/index.js

@@ -3,3 +3,20 @@
 export { clamp, lerp, map, scale } from "./math.js";
 export { parse as parseMarkdown, parseToDocument as parseMarkdownToDocument, exportcss as exportMarkdownCSS } from "./markdown.js";
 export { parseJSONC } from "./jsonc-parser.js";
+// Tiny Hash function
+export function hash(str) {
+    let h = 0;
+    for (let i = 0; i < str.length; i++) {
+        h = (h << 5) - h + str.charCodeAt(i);
+        h |= 0; // 32bit int
+    }
+    return h;
+}
+// Make an array random
+export function shuffle(array) {
+    for (let i = array.length - 1; i > 0; i--) {
+        const j = Math.floor(Math.random() * (i + 1));
+        [array[i], array[j]] = [array[j], array[i]];
+    }
+    return array;
+}

package/package.json

@@ -1,14 +1,15 @@
 {
   "name": "samengine",
-  "version": "1.9.0",
+  "version": "1.9.1",
   "description": "A TypeScript game library to make HTML Games",
   "sideEffects": false,
   "files": [
     "dist"
   ],
   "scripts": {
+    "dev": "npx samengine-build",
     "build": "tsc",
-    "pack": "node scripts/clean.js && npm run build && npm pack && git push --follow-tags",
+    "pack": "node ../../scripts/clean.js && npm run build && npm pack && git push --follow-tags && npm run up",
     "test": "bun test"
   },
   "exports": {
@@ -16,8 +17,11 @@
     "./types": "./dist/types/index.js",
     "./sound": "./dist/sound/index.js",
     "./utils": "./dist/utils/index.js",
+    "./utils/csv": "./dist/utils/csv/index.js",
     "./build": "./dist/build/index.js",
-    "./physics": "./dist/physics/index.js"
+    "./physics": "./dist/physics/index.js",
+    "./samegui": "./dist/samegui/index.js",
+    "./storage": "./dist/storage/index.js"
   },
   "keywords": [
     "game",
@@ -27,8 +31,9 @@
   "license": "MIT",
   "devDependencies": {
     "chalk": "^5.6.2",
-    "@types/node": "^25.5.2",
-    "typescript": "^6.0.2"
+    "@types/node": "^25.6.0",
+    "typescript": "^6.0.3",
+    "automatic-md-index": "^1.3.6"
   },
   "repository": {
     "type": "git",