samengine 1.9.0 → 1.10.0

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, empty: 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 {};

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

@@ -0,0 +1,262 @@
+#!/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.
+ */
+import { build as esbuild } from "esbuild";
+import { createServer } from "http";
+import { readFile, writeFile, mkdir, rm } from "fs/promises";
+import { watch, watchFile } from "fs";
+import path from "path";
+import { WebSocketServer } from "ws";
+import { copyFolder, flog, getContentType, scanResourcesAsDataURIs, filterResourcesByUsage } from "./../buildhelper.js";
+import { GetDefaultHTML, GetSingleFileHTML, getVersion } from "../exporthtml.js";
+import { loadUserConfig } from "./../config.js";
+import { compressHTML } from "../../index.js";
+import { parseArgs } from "./argparser.js";
+import { run as runCreateProject } from "../projcreator/main.js";
+// ================= HELP ============
+/**
+ * Function to print Help
+ */
+function showHelp() {
+    console.log(`
+███████╗ █████╗ ███╗   ███╗███████╗███╗   ██╗ ██████╗ ██╗███╗   ██╗███████╗
+██╔════╝██╔══██╗████╗ ████║██╔════╝████╗  ██║██╔════╝ ██║████╗  ██║██╔════╝
+███████╗███████║██╔████╔██║█████╗  ██╔██╗ ██║██║  ███╗██║██╔██╗ ██║█████╗  
+╚════██║██╔══██║██║╚██╔╝██║██╔══╝  ██║╚██╗██║██║   ██║██║██║╚██╗██║██╔══╝  
+███████║██║  ██║██║ ╚═╝ ██║███████╗██║ ╚████║╚██████╔╝██║██║ ╚████║███████╗
+╚══════╝╚═╝  ╚═╝╚═╝     ╚═╝╚══════╝╚═╝  ╚═══╝ ╚═════╝ ╚═╝╚═╝  ╚═══╝╚══════╝
+
+CLI Tool for samengine
+
+Usage:
+  -r, --release         build the project in Release Mode
+  create                create a new project
+  help                  Show this menu
+
+More: samfile
+use with @shadowdara/samtool
+Install: npm i @shadowdara/samtool
+`);
+}
+// ================= BUILD =================
+/**
+ * Creates a build runner for one config object and one build mode.
+ *
+ * The returned `build` function owns the esbuild call, generated HTML, resource
+ * copying or embedding, release minification, and metadata comments. Dev builds
+ * keep source maps; release builds clean the output directory first.
+ */
+function createBuilder(config, isRelease) {
+    // Ensure that the Directories are created
+    mkdir("resources", { recursive: true });
+    mkdir("game", { recursive: true });
+    async function build() {
+        try {
+            flog("🔄 Building project...");
+            if (isRelease)
+                await rm(`./${config.outdir}`, { recursive: true, force: true });
+            await esbuild({
+                entryPoints: [`./game/${config.entryname}`],
+                outdir: `./${config.outdir}`,
+                bundle: true,
+                platform: "browser",
+                minify: isRelease,
+                sourcemap: !isRelease,
+                define: { "import.meta.env.DEV": JSON.stringify(!isRelease) },
+            });
+            if (isRelease && config.releaseMode.singlefile || !isRelease && config.devMode.singlefile) {
+                // Single-file export
+                const bundledJsPath = path.join(".", config.outdir, `${config.entryname.replace(/\.[^.]*$/, "")}.js`);
+                const bundledJsContent = await readFile(bundledJsPath, "utf-8");
+                // Scan resources and convert to data URIs
+                let resourcesMap = await scanResourcesAsDataURIs("./resources");
+                // Filter resources by usage in the bundled code
+                resourcesMap = filterResourcesByUsage(bundledJsContent, resourcesMap);
+                let html = GetSingleFileHTML(config, bundledJsContent, resourcesMap);
+                if (isRelease)
+                    html = await compressHTML(html);
+                // Add comment at the beginning after minification
+                const htmlComment = `<!-- Game made with samengine v${getVersion()} - https://github.com/Shadowdara/samengine ${config.gameauthor} (Game Author) -->\n`;
+                html = htmlComment + html;
+                await writeFile(`./${config.outdir}/index.html`, html);
+                // Delete the JS File
+                await rm(`./${config.outdir}/main.js`, { recursive: true, force: true });
+                flog("✅ Single-file export created!");
+            }
+            else {
+                // Multi-file export (original behavior)
+                let html = GetDefaultHTML(config, isRelease);
+                if (isRelease)
+                    html = await compressHTML(html);
+                // Add HTML comment at the beginning after minification
+                const htmlComment = `<!-- Game made with samengine v${getVersion()} - https://www.npmjs.com/samengine ${config.gameauthor} (Game Author) -->\n`;
+                html = htmlComment + html;
+                await writeFile(`./${config.outdir}/index.html`, html);
+                // Add JS comment at the beginning of JS files
+                const jsComment = `// Game made with samengine v${getVersion()} - https://www.npmjs.com/samengine by ${config.gameauthor} (Game Author)\n`;
+                const jsPath = path.join(".", config.outdir, `${config.entryname.replace(/\.[^.]*$/, "")}.js`);
+                let jsContent = await readFile(jsPath, "utf-8");
+                jsContent = jsComment + jsContent;
+                await writeFile(jsPath, jsContent);
+                await copyFolder("./resources", `./${config.outdir}/resources`);
+                flog("✅ Build finished!");
+            }
+        }
+        catch (error) {
+            flog(`❌ Build failed: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    return { build };
+}
+// ================= SERVER & RELOAD =================
+/**
+ * Starts the local development server for the configured output directory.
+ *
+ * Static files are served from `config.outdir`. A WebSocket server is attached
+ * to the same HTTP server so future rebuilds can notify connected browsers.
+ */
+function createDevServer(config) {
+    const sockets = new Set();
+    const server = createServer(async (req, res) => {
+        const url = req.url || "/";
+        const filePath = path.join(process.cwd(), `${config.outdir}`, url === "/" ? "index.html" : url);
+        try {
+            const file = await readFile(filePath);
+            res.writeHead(200, { "Content-Type": getContentType(filePath) });
+            res.end(file);
+        }
+        catch {
+            res.writeHead(404);
+            res.end("Not Found");
+        }
+    });
+    const wss = new WebSocketServer({ server });
+    wss.on("connection", (ws) => {
+        sockets.add(ws);
+        ws.on("close", () => sockets.delete(ws));
+    });
+    function startListening(port) {
+        server.listen(port);
+        server.on("listening", () => {
+            flog(`🚀 Dev Server running on http://localhost:${port}`);
+        });
+        server.on("error", (err) => {
+            if (err.code === "EADDRINUSE") {
+                flog(`⚠️ Port ${port} is already in use, trying ${port + 1}...`);
+                startListening(port + 1);
+            }
+            else {
+                throw err;
+            }
+        });
+    }
+    startListening(config.dev_server_port);
+    function reloadClients() {
+        flog("🔄 Browser reload...");
+        sockets.forEach((ws) => ws.send("reload"));
+    }
+    function stop() {
+        flog("🛑 Stopping dev server...");
+        sockets.forEach(ws => ws.close());
+        wss.close();
+        server.close();
+    }
+    return { reloadClients, stop };
+}
+// ================= WATCHER =================
+/**
+ * Watches the `resources` and `game` folders recursively.
+ *
+ * The watcher delegates rebuild scheduling to `onChange`. The main function
+ * serializes rebuilds so multiple file-system events do not run overlapping
+ * builds.
+ */
+async function startWatcher(onChange) {
+    await mkdir("resources", { recursive: true });
+    await mkdir("game", { recursive: true });
+    ["resources", "game"].forEach((dir) => {
+        watch(dir, { recursive: true }, async () => {
+            flog(`📁 Change noticed in ${dir}`);
+            await onChange();
+        });
+    });
+    flog("👀 Watcher active...");
+}
+// ================= CLI APP =================
+/**
+ * Runs the CLI application.
+ *
+ * Development mode starts with one build, then creates a server and watchers.
+ * Config changes trigger a full restart because output folder, port, menu, or
+ * other generated HTML settings may have changed.
+ */
+async function main() {
+    const args = parseArgs();
+    if (args.newProject) {
+        await runCreateProject();
+        process.exit(0);
+    }
+    if (args.help) {
+        showHelp();
+        process.exit(0);
+    }
+    const config = await loadUserConfig();
+    let builder = createBuilder(config, args.release);
+    let isBuilding = false;
+    let pendingRestart = false;
+    async function restart() {
+        if (isBuilding) {
+            pendingRestart = true;
+            return;
+        }
+        isBuilding = true;
+        do {
+            pendingRestart = false;
+            try {
+                // Load the New Config
+                const newConfig = await loadUserConfig();
+                // Dev Server Stoppen
+                devServer?.stop();
+                // Create new Dev Server
+                devServer = createDevServer(newConfig);
+                // New Builder (use the new Config)
+                builder = createBuilder(newConfig, args.release);
+                await builder.build();
+                devServer?.reloadClients();
+            }
+            catch (error) {
+                flog(`❌ Rebuild failed: ${error instanceof Error ? error.message : String(error)}`);
+            }
+        } while (pendingRestart);
+        isBuilding = false;
+    }
+    try {
+        await builder.build();
+    }
+    catch (error) {
+        flog(`❌ Initial build failed: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    let devServer = null;
+    // Only start the Dev Server in Release Mode
+    if (!args.release) {
+        devServer = createDevServer(config);
+        // Watch the config separately because changing it can require a server restart.
+        watchFile("samengine.config.ts", { interval: 300 }, async () => {
+            flog("⚙️ Config file changed → full restart");
+            await restart();
+        });
+        await startWatcher(restart);
+    }
+    // Dev or Release Mode
+    flog(`Build finished! Mode: ${args.release ? "Release" : "Dev"}`);
+}
+main();

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

@@ -0,0 +1,9 @@
+/**
+ * Loads `samengine.config.ts` from the current project directory.
+ *
+ * Node cannot import TypeScript config files directly, so the file is bundled to
+ * `.samengine/config.mjs` with esbuild first. The generated file is then loaded
+ * through a dynamic ESM import. A timestamp query parameter bypasses Node's
+ * import cache, which lets the watch mode see changed config values immediately.
+ */
+export declare function loadUserConfig(): Promise<any>;

package/dist/nonbrowser/internal/config.js

@@ -0,0 +1,40 @@
+import { build } from "esbuild";
+import path from "path";
+import { pathToFileURL } from "url";
+import fs from "fs/promises";
+/**
+ * Loads `samengine.config.ts` from the current project directory.
+ *
+ * Node cannot import TypeScript config files directly, so the file is bundled to
+ * `.samengine/config.mjs` with esbuild first. The generated file is then loaded
+ * through a dynamic ESM import. A timestamp query parameter bypasses Node's
+ * import cache, which lets the watch mode see changed config values immediately.
+ */
+export async function loadUserConfig() {
+    const root = process.cwd();
+    const configPath = path.resolve(root, "samengine.config.ts");
+    const outDir = path.resolve(root, ".samengine");
+    const outfile = path.join(outDir, "config.mjs");
+    try {
+        // ensure folder exists
+        await fs.mkdir(outDir, { recursive: true });
+        // 🔥 bundle TS → JS
+        await build({
+            entryPoints: [configPath],
+            outfile,
+            bundle: true,
+            platform: "node",
+            format: "esm",
+        });
+        // 🔥 import compiled file
+        const mod = await import(pathToFileURL(outfile).href + `?t=${Date.now()}`);
+        const config = typeof mod.default === "function"
+            ? await mod.default()
+            : mod.default;
+        return config;
+    }
+    catch (e) {
+        console.error(e);
+        throw new Error("❌ Could not load samengine.config.ts: " + configPath);
+    }
+}

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

@@ -0,0 +1,37 @@
+/**
+ * HTML generation for samengine-build.
+ *
+ * This module creates the complete `index.html` written into the output folder.
+ * There are two build shapes:
+ *
+ * - `GetDefaultHTML` creates a normal multi-file page that imports the bundled
+ *   game JavaScript after the player clicks the start button.
+ * - `GetSingleFileHTML` embeds the bundled JavaScript and optional resource
+ *   Data URIs directly into one HTML document.
+ */
+import type { buildconfig } from "../../config/buildconfig.js";
+/**
+ * Function to get the samengine Version
+ *
+ * @deprecated WARN Function should not be used outside samengine. Use getPackageVersion instead!
+ */
+export declare function getVersion(): string;
+/**
+ * Creates a complete single-file HTML document.
+ *
+ * `bundledJsContent` is the already bundled game code from esbuild.
+ * `resourcesMap` contains optional Data URIs that are exposed through
+ * `window.__resources`, `window.__getResource`, and `window.__loadResource`.
+ *
+ * The bundled game is wrapped in `window.__initializeGame` so it does not run
+ * until the player clicks the start button. This allows the generated page to
+ * show the start screen, unlock audio, and remove temporary UI first.
+ */
+export declare function GetSingleFileHTML(config: buildconfig, bundledJsContent: string, resourcesMap?: Record<string, string>): string;
+/**
+ * Creates the normal multi-file HTML document.
+ *
+ * This page contains the generated start screen and optional menu UI. The game
+ * bundle is loaded with a dynamic import only after the start button is clicked.
+ */
+export declare function GetDefaultHTML(config: buildconfig, releasemode: boolean): string;