samengine 1.9.1 → 1.10.1

package/dist/core.js

@@ -1,10 +1,34 @@
 let lastTime = 0;
 let loop;
+/**
+ * Starts the central game loop of samengine.
+ *
+ * The `start` callback is executed once before the first frame. Use it for
+ * setup work such as creating objects, loading initial state, or configuring
+ * input. After that, `gameLoop` is called every animation frame with `dt`, the
+ * elapsed time in seconds since the previous frame.
+ *
+ * `dt` should be used for frame-rate independent movement:
+ *
+ * ```ts
+ * player.x += player.speed * dt;
+ * ```
+ *
+ * @param start Function that runs once before the loop starts.
+ * @param gameLoop Function that runs every frame. Receives delta time in seconds.
+ */
 export function startEngine(start, gameLoop) {
     loop = gameLoop;
     start();
     requestAnimationFrame(run);
 }
+/**
+ * Internal `requestAnimationFrame` callback.
+ *
+ * Converts the browser timestamp from milliseconds to a seconds-based delta and
+ * schedules the next frame. This function is intentionally not exported because
+ * consumers should control the engine through `startEngine`.
+ */
 function run(time) {
     const dt = (time - lastTime) / 1000;
     lastTime = time;

package/dist/html.d.ts

@@ -1,11 +1,27 @@
 export type CanvasConfig = {
+    /** Fixed canvas width when `fullscreen` is false. Defaults to 800. */
     width?: number;
+    /** Fixed canvas height when `fullscreen` is false. Defaults to 800. */
     height?: number;
+    /** If true, the canvas is resized to the browser window. */
     fullscreen?: boolean;
+    /**
+     * Scaling mode. `"fit"` keeps a virtual resolution and letterboxes it into
+     * the real canvas. `"none"` draws directly in canvas pixels.
+     */
     scaling?: "none" | "fit";
+    /** Logical game width used by `"fit"` scaling. Defaults to 800. */
     virtualWidth?: number;
+    /** Logical game height used by `"fit"` scaling. Defaults to 800. */
     virtualHeight?: number;
 };
+/**
+ * Creates a canvas, appends it to `document.body`, and returns its 2D context.
+ *
+ * When `scaling` is `"fit"`, call `applyScaling()` at the beginning of each
+ * frame before drawing game objects. This sets the canvas transform so your game
+ * can render in virtual coordinates independent of the real browser size.
+ */
 export declare function createCanvas(config?: CanvasConfig): {
     canvas: HTMLCanvasElement;
     ctx: CanvasRenderingContext2D;
@@ -13,6 +29,19 @@ export declare function createCanvas(config?: CanvasConfig): {
     virtualWidth: number;
     virtualHeight: number;
 };
+/**
+ * Resizes an existing canvas to the browser window size.
+ */
 export declare function resizeCanvas(canvas: HTMLCanvasElement): void;
+/**
+ * Adds a keyboard shortcut for fullscreen mode.
+ *
+ * Pressing the `f` key toggles fullscreen for the provided canvas.
+ */
 export declare function enableFullscreen(canvas: HTMLCanvasElement): void;
+/**
+ * Connects an existing DOM element with id `fullscreenBtn` to fullscreen mode.
+ *
+ * If no element with that id exists, the function does nothing.
+ */
 export declare function setupFullscreenButton(canvas: HTMLCanvasElement): void;

package/dist/html.js

@@ -1,3 +1,10 @@
+/**
+ * Creates a canvas, appends it to `document.body`, and returns its 2D context.
+ *
+ * When `scaling` is `"fit"`, call `applyScaling()` at the beginning of each
+ * frame before drawing game objects. This sets the canvas transform so your game
+ * can render in virtual coordinates independent of the real browser size.
+ */
 export function createCanvas(config = {}) {
     const canvas = document.createElement("canvas");
     const ctx = canvas.getContext("2d");
@@ -35,10 +42,18 @@ export function createCanvas(config = {}) {
         virtualHeight,
     };
 }
+/**
+ * Resizes an existing canvas to the browser window size.
+ */
 export function resizeCanvas(canvas) {
     canvas.width = window.innerWidth;
     canvas.height = window.innerHeight;
 }
+/**
+ * Adds a keyboard shortcut for fullscreen mode.
+ *
+ * Pressing the `f` key toggles fullscreen for the provided canvas.
+ */
 export function enableFullscreen(canvas) {
     window.addEventListener("keydown", (e) => {
         if (e.key === "f") {
@@ -51,6 +66,11 @@ export function enableFullscreen(canvas) {
         }
     });
 }
+/**
+ * Connects an existing DOM element with id `fullscreenBtn` to fullscreen mode.
+ *
+ * If no element with that id exists, the function does nothing.
+ */
 export function setupFullscreenButton(canvas) {
     const btn = document.getElementById("fullscreenBtn");
     if (!btn)

package/dist/input.d.ts

@@ -1,3 +1,10 @@
+/**
+ * Snapshot of the current mouse state in virtual canvas coordinates.
+ *
+ * The left mouse button uses `pressed`, `justPressed`, and `justReleased`.
+ * The right mouse button uses the matching `right...` fields. `wheelDelta`
+ * stores the most recent wheel event delta and is reset by `resetInput`.
+ */
 export type Mouse = {
     x: number;
     y: number;
@@ -9,9 +16,53 @@ export type Mouse = {
     rightjustReleased: boolean;
     wheelDelta: number;
 };
+/**
+ * Installs keyboard and mouse listeners for the engine.
+ *
+ * Mouse coordinates are converted into the virtual coordinate system used by
+ * `createCanvas({ scaling: "fit" })`. Pass the same virtual width and height
+ * here that you use for canvas scaling, otherwise mouse hit tests will not line
+ * up with rendered objects.
+ *
+ * Call this once during game setup.
+ *
+ * @param canvas Canvas that should receive mouse events.
+ * @param vWidth Width of the virtual game area. Defaults to 800.
+ * @param vHeight Height of the virtual game area. Defaults to 800.
+ */
 export declare function setupInput(canvas: HTMLCanvasElement, vWidth?: number, vHeight?: number): void;
+/**
+ * Returns whether the given keyboard code is currently held down.
+ *
+ * Use values from the `Key` enum for autocomplete-friendly input names.
+ */
 export declare function isKeyPressed(code: string): boolean;
+/**
+ * Returns true only during the frame in which a key became pressed.
+ *
+ * Call `resetInput()` once at the end of each game loop frame so this one-frame
+ * flag can be cleared.
+ */
 export declare function isKeyJustPressed(code: string): boolean;
+/**
+ * Returns true only during the frame in which a key was released.
+ *
+ * Call `resetInput()` once at the end of each game loop frame so this one-frame
+ * flag can be cleared.
+ */
 export declare function isKeyJustReleased(code: string): boolean;
+/**
+ * Returns a read-only copy of the current mouse state.
+ *
+ * A copy is returned so game code cannot accidentally mutate the internal input
+ * state. Use this object for hit tests such as `isMouseInRect` or
+ * `isRectClicked`.
+ */
 export declare function getMouse(): Readonly<Mouse>;
+/**
+ * Clears all one-frame input flags.
+ *
+ * This should usually be called once at the end of each frame, after your game
+ * logic has consumed `justPressed`, `justReleased`, and `wheelDelta`.
+ */
 export declare function resetInput(): void;

package/dist/input.js

@@ -17,6 +17,20 @@ let canvasRef;
 // 👉 optional: für scaling (kannst du später aus deiner engine holen)
 let virtualWidth = 800;
 let virtualHeight = 800;
+/**
+ * Installs keyboard and mouse listeners for the engine.
+ *
+ * Mouse coordinates are converted into the virtual coordinate system used by
+ * `createCanvas({ scaling: "fit" })`. Pass the same virtual width and height
+ * here that you use for canvas scaling, otherwise mouse hit tests will not line
+ * up with rendered objects.
+ *
+ * Call this once during game setup.
+ *
+ * @param canvas Canvas that should receive mouse events.
+ * @param vWidth Width of the virtual game area. Defaults to 800.
+ * @param vHeight Height of the virtual game area. Defaults to 800.
+ */
 export function setupInput(canvas, vWidth = 800, vHeight = 800) {
     canvasRef = canvas;
     virtualWidth = vWidth;
@@ -83,21 +97,48 @@ export function setupInput(canvas, vWidth = 800, vHeight = 800) {
         mouse.rightPressed = false;
     });
 }
-// ===== KEY HELPERS =====
+/**
+ * Returns whether the given keyboard code is currently held down.
+ *
+ * Use values from the `Key` enum for autocomplete-friendly input names.
+ */
 export function isKeyPressed(code) {
     return keys[code]?.pressed || false;
 }
+/**
+ * Returns true only during the frame in which a key became pressed.
+ *
+ * Call `resetInput()` once at the end of each game loop frame so this one-frame
+ * flag can be cleared.
+ */
 export function isKeyJustPressed(code) {
     return keys[code]?.justPressed || false;
 }
+/**
+ * Returns true only during the frame in which a key was released.
+ *
+ * Call `resetInput()` once at the end of each game loop frame so this one-frame
+ * flag can be cleared.
+ */
 export function isKeyJustReleased(code) {
     return keys[code]?.justReleased || false;
 }
-// ===== MOUSE =====
+/**
+ * Returns a read-only copy of the current mouse state.
+ *
+ * A copy is returned so game code cannot accidentally mutate the internal input
+ * state. Use this object for hit tests such as `isMouseInRect` or
+ * `isRectClicked`.
+ */
 export function getMouse() {
     return { ...mouse };
 }
-// ===== RESET =====
+/**
+ * Clears all one-frame input flags.
+ *
+ * This should usually be called once at the end of each frame, after your game
+ * logic has consumed `justPressed`, `justReleased`, and `wheelDelta`.
+ */
 export function resetInput() {
     for (const k in keys) {
         keys[k].justPressed = false;

package/dist/keys.d.ts

@@ -1,3 +1,9 @@
+/**
+ * Common `KeyboardEvent.code` values for autocomplete-friendly input checks.
+ *
+ * Use these values with `isKeyPressed`, `isKeyJustPressed`, and
+ * `isKeyJustReleased`.
+ */
 export declare enum Key {
     ArrowUp = "ArrowUp",
     ArrowDown = "ArrowDown",

package/dist/keys.js

@@ -1,5 +1,9 @@
-// keys.ts
-// to view the Keys easily with the Autocomplete Feature
+/**
+ * Common `KeyboardEvent.code` values for autocomplete-friendly input checks.
+ *
+ * Use these values with `isKeyPressed`, `isKeyJustPressed`, and
+ * `isKeyJustReleased`.
+ */
 export var Key;
 (function (Key) {
     Key["ArrowUp"] = "ArrowUp";

package/dist/logger.d.ts

@@ -1 +1,9 @@
+/**
+ * Debug logger used by samengine internals.
+ *
+ * In the current release build this is intentionally a no-op, so calls can stay
+ * in code without producing console output. The commented implementation above
+ * shows the development logger that can be re-enabled when needed.
+ * @deprecated Use samengine/utils/logger instead!
+ */
 export declare const dlog: (...args: any[]) => void;

package/dist/logger.js

@@ -1,4 +1,11 @@
-// Debug Log Function
+/**
+ * Debug logger used by samengine internals.
+ *
+ * In the current release build this is intentionally a no-op, so calls can stay
+ * in code without producing console output. The commented implementation above
+ * shows the development logger that can be re-enabled when needed.
+ * @deprecated Use samengine/utils/logger instead!
+ */
 export const dlog = 
 // (import.meta.env?.DEV ?? true) // Default true, falls undefined
 // ? (...args: any[]) => {

package/dist/nonbrowser/getversion.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Reads the installed version of an npm package from its `package.json`.
+ *
+ * The CLI uses this to write the installed samengine version into generated
+ * HTML/JS metadata and into `window.__samengine__`. The optional `projectRoot`
+ * parameter makes the lookup reusable for tests or tools that need to inspect a
+ * different project directory.
+ *
+ * @throws If the package cannot be found in `node_modules`.
+ * @throws If the package manifest cannot be parsed as JSON.
+ * @throws If the package manifest does not contain a `version` field.
+ */
+export declare function getPackageVersion(packageName: string, projectRoot?: string): string;

package/dist/nonbrowser/getversion.js

@@ -0,0 +1,35 @@
+import fs from "fs";
+import path from "path";
+/**
+ * Reads the installed version of an npm package from its `package.json`.
+ *
+ * The CLI uses this to write the installed samengine version into generated
+ * HTML/JS metadata and into `window.__samengine__`. The optional `projectRoot`
+ * parameter makes the lookup reusable for tests or tools that need to inspect a
+ * different project directory.
+ *
+ * @throws If the package cannot be found in `node_modules`.
+ * @throws If the package manifest cannot be parsed as JSON.
+ * @throws If the package manifest does not contain a `version` field.
+ */
+export function getPackageVersion(packageName, projectRoot = process.cwd()) {
+    const packageJsonPath = path.join(projectRoot, "node_modules", packageName, "package.json");
+    let raw;
+    try {
+        raw = fs.readFileSync(packageJsonPath, "utf-8");
+    }
+    catch (err) {
+        throw new Error(`Package '${packageName}' was not found in node_modules`);
+    }
+    let packageJson;
+    try {
+        packageJson = JSON.parse(raw);
+    }
+    catch (err) {
+        throw new Error(`Invalid package.json for '${packageName}'`);
+    }
+    if (!packageJson.version) {
+        throw new Error(`No version field found in package.json of '${packageName}'`);
+    }
+    return packageJson.version;
+}

package/dist/nonbrowser/ghresolver.d.ts

@@ -0,0 +1 @@
+export declare function getTemplateZipUrl(version: string, username: string, reponame: string): string;

package/dist/nonbrowser/ghresolver.js

@@ -0,0 +1,7 @@
+export function getTemplateZipUrl(version, username, reponame) {
+    const base = `https://codeload.github.com/${username}/${reponame}/zip`;
+    if (version) {
+        return `${base}/refs/tags/${version}`;
+    }
+    return `${base}/refs/heads/main`;
+}

package/dist/nonbrowser/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Public utility entry point.
+ *
+ * This file exists so consumers can import helper functions from
+ * `sanegine/nonbrowser` without depending on internal source paths.
+ */
+export { compressHTML } from "./utils.js";
+export { getPackageVersion } from "./getversion.js";
+export { getTemplateZipUrl } from "./ghresolver.js";

package/dist/nonbrowser/index.js

@@ -0,0 +1,9 @@
+/**
+ * Public utility entry point.
+ *
+ * This file exists so consumers can import helper functions from
+ * `sanegine/nonbrowser` without depending on internal source paths.
+ */
+export { compressHTML } from "./utils.js";
+export { getPackageVersion } from "./getversion.js";
+export { getTemplateZipUrl } from "./ghresolver.js";

package/dist/nonbrowser/internal/buildhelper.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Logs CLI messages with a timestamp down to milliseconds.
+ *
+ * The build tool can receive several file-system events in quick succession
+ * while watching a project. Timestamped logs make it easier to understand which
+ * rebuild, copy operation, or server action happened first.
+ */
+export declare const flog: (...args: any[]) => void;
+/**
+ * Recursively copies a folder from `src` to `dest`.
+ *
+ * The multi-file build uses this to copy `resources` into the output directory.
+ * Files are copied as raw buffers so binary assets such as images and audio are
+ * preserved exactly.
+ */
+export declare function copyFolder(src: string, dest: string): Promise<void>;
+/**
+ * Scans a resource folder and converts every file into a Base64 Data URI.
+ *
+ * The returned object uses paths relative to `resourceDir`, for example
+ * `sprites/player.png`. Single-file builds embed this map into the generated
+ * HTML so the game can load assets without separate files.
+ */
+export declare function scanResourcesAsDataURIs(resourceDir: string): Promise<Record<string, string>>;
+/** Returns the Content-Type used by the local development server. */
+export declare function getContentType(path: string): string;
+/**
+ * Returns the MIME type used when embedding a resource as a Data URI.
+ *
+ * Unknown file extensions fall back to `application/octet-stream`, which keeps
+ * the resource loadable even when the type is not explicitly listed here.
+ */
+export declare function getMimeType(filename: string): string;
+/**
+ * Removes resources that do not appear to be referenced by the bundled code.
+ *
+ * The check intentionally stays simple: it looks for the full relative resource
+ * path or just the filename inside the JavaScript bundle. This keeps
+ * single-file exports smaller, but it can only detect assets whose names remain
+ * visible as strings in the bundle.
+ */
+export declare function filterResourcesByUsage(bundledJsContent: string, resourcesMap: Record<string, string>): Record<string, string>;

package/dist/nonbrowser/internal/buildhelper.js

@@ -0,0 +1,144 @@
+import { readdirSync, mkdirSync, promises as fsPromises, existsSync } from "fs";
+import { join } from "path";
+/**
+ * Logs CLI messages with a timestamp down to milliseconds.
+ *
+ * The build tool can receive several file-system events in quick succession
+ * while watching a project. Timestamped logs make it easier to understand which
+ * rebuild, copy operation, or server action happened first.
+ */
+export const flog = (...args) => {
+    const now = new Date();
+    const time = `[${now.getHours().toString().padStart(2, "0")}:` +
+        `${now.getMinutes().toString().padStart(2, "0")}:` +
+        `${now.getSeconds().toString().padStart(2, "0")}.` +
+        `${now.getMilliseconds().toString().padStart(3, "0")}]`;
+    console.log(time, ...args);
+};
+/**
+ * Recursively copies a folder from `src` to `dest`.
+ *
+ * The multi-file build uses this to copy `resources` into the output directory.
+ * Files are copied as raw buffers so binary assets such as images and audio are
+ * preserved exactly.
+ */
+export async function copyFolder(src, dest) {
+    // Create the target folder before copying nested entries into it.
+    mkdirSync(dest, { recursive: true });
+    const entries = readdirSync(src, { withFileTypes: true });
+    for (const entry of entries) {
+        const srcPath = join(src, entry.name);
+        const destPath = join(dest, entry.name);
+        if (entry.isDirectory()) {
+            await copyFolder(srcPath, destPath);
+        }
+        else if (entry.isFile()) {
+            // Datei mit Node.js schreiben
+            const data = await fsPromises.readFile(srcPath);
+            await fsPromises.writeFile(destPath, data);
+        }
+    }
+}
+/**
+ * Scans a resource folder and converts every file into a Base64 Data URI.
+ *
+ * The returned object uses paths relative to `resourceDir`, for example
+ * `sprites/player.png`. Single-file builds embed this map into the generated
+ * HTML so the game can load assets without separate files.
+ */
+export async function scanResourcesAsDataURIs(resourceDir) {
+    const resourceMap = {};
+    if (!existsSync(resourceDir)) {
+        return resourceMap;
+    }
+    async function scanDir(dir, basePath = "") {
+        const entries = readdirSync(dir, { withFileTypes: true });
+        for (const entry of entries) {
+            const fullPath = join(dir, entry.name);
+            const resourcePath = basePath ? `${basePath}/${entry.name}` : entry.name;
+            if (entry.isDirectory()) {
+                await scanDir(fullPath, resourcePath);
+            }
+            else if (entry.isFile()) {
+                const fileData = await fsPromises.readFile(fullPath);
+                const base64Data = fileData.toString("base64");
+                const mimeType = getMimeType(entry.name);
+                resourceMap[resourcePath] = `data:${mimeType};base64,${base64Data}`;
+            }
+        }
+    }
+    await scanDir(resourceDir);
+    return resourceMap;
+}
+// === Helper ===
+/** Returns the Content-Type used by the local development server. */
+export function getContentType(path) {
+    if (path.endsWith(".js"))
+        return "application/javascript";
+    if (path.endsWith(".ts"))
+        return "application/typescript";
+    if (path.endsWith(".html"))
+        return "text/html";
+    if (path.endsWith(".css"))
+        return "text/css";
+    if (path.endsWith(".png"))
+        return "image/png";
+    if (path.endsWith(".svg"))
+        return "image/svg+xml";
+    return "text/plain";
+}
+/**
+ * Returns the MIME type used when embedding a resource as a Data URI.
+ *
+ * Unknown file extensions fall back to `application/octet-stream`, which keeps
+ * the resource loadable even when the type is not explicitly listed here.
+ */
+export function getMimeType(filename) {
+    const ext = filename.toLowerCase().split(".").pop() || "";
+    const mimeTypes = {
+        "png": "image/png",
+        "jpg": "image/jpeg",
+        "jpeg": "image/jpeg",
+        "gif": "image/gif",
+        "svg": "image/svg+xml",
+        "webp": "image/webp",
+        "mp3": "audio/mpeg",
+        "wav": "audio/wav",
+        "ogg": "audio/ogg",
+        "m4a": "audio/mp4",
+        "json": "application/json",
+        "txt": "text/plain",
+        "css": "text/css",
+    };
+    return mimeTypes[ext] || "application/octet-stream";
+}
+/**
+ * Removes resources that do not appear to be referenced by the bundled code.
+ *
+ * The check intentionally stays simple: it looks for the full relative resource
+ * path or just the filename inside the JavaScript bundle. This keeps
+ * single-file exports smaller, but it can only detect assets whose names remain
+ * visible as strings in the bundle.
+ */
+export function filterResourcesByUsage(bundledJsContent, resourcesMap) {
+    const filteredResources = {};
+    const unusedResources = [];
+    for (const resourcePath in resourcesMap) {
+        // Extract just the filename (last part after /)
+        const filename = resourcePath.split("/").pop() || resourcePath;
+        // Check if the resource is referenced in the bundled code
+        // Look for string literals containing the resource path or filename
+        if (bundledJsContent.includes(filename) || bundledJsContent.includes(resourcePath)) {
+            filteredResources[resourcePath] = resourcesMap[resourcePath];
+        }
+        else {
+            unusedResources.push(resourcePath);
+        }
+    }
+    // Log unused resources
+    if (unusedResources.length > 0) {
+        flog(`⚠️  ${unusedResources.length} unused resource(s) excluded from single-file build:`);
+        unusedResources.forEach(res => flog(`   - ${res}`));
+    }
+    return filteredResources;
+}

package/dist/nonbrowser/internal/cli/argparser.d.ts

@@ -0,0 +1,18 @@
+/** Parsed command-line options for the `samengine-build` executable. */
+export interface CLIArgs {
+    /** True when the user passed `--release` or `-r`. */
+    release: boolean;
+    /** Reserved for a CLI-level single-file flag. The config currently controls this. */
+    singlefile: boolean;
+    /** Project name passed to `--new` or `--new-empty`; otherwise `null`. */
+    newProject: boolean;
+    /** Show a Help Message */
+    help: boolean;
+}
+/**
+ * Parses CLI arguments from `process.argv`.
+ *
+ * Unknown arguments are reported as warnings instead of crashing the process, so
+ * the CLI stays forgiving while still making mistakes visible.
+ */
+export declare function parseArgs(): CLIArgs;

package/dist/nonbrowser/internal/cli/argparser.js

@@ -0,0 +1,36 @@
+/**
+ * Parses CLI arguments from `process.argv`.
+ *
+ * Unknown arguments are reported as warnings instead of crashing the process, so
+ * the CLI stays forgiving while still making mistakes visible.
+ */
+export function parseArgs() {
+    const args = process.argv.slice(2);
+    const options = { release: false, singlefile: false, newProject: false, help: false };
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        switch (arg) {
+            case "--release":
+            case "-r":
+                options.release = true;
+                break;
+            case "create":
+            case "new":
+            case "--new":
+            case "-n":
+            case "--new-empty":
+                options.newProject = true;
+                break;
+            case "help":
+            case "h":
+            case "-h":
+            case "--help":
+                options.help = true;
+                break;
+            default:
+                console.warn(`⚠️ Unknown Argument: ${arg}`);
+                break;
+        }
+    }
+    return options;
+}

package/dist/nonbrowser/internal/cli/main.d.ts

@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+/**
+ * CLI entry point for `samengine-build`.
+ *
+ * High-level flow:
+ * 1. Parse CLI arguments.
+ * 2. Optionally create a new project.
+ * 3. Load `samengine.config.ts`.
+ * 4. Bundle the game with esbuild.
+ * 5. Generate HTML and handle resources.
+ * 6. In development mode, start a local server and watch for changes.
+ */
+export {};