samengine 1.9.1 → 1.10.0

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

@@ -0,0 +1,81 @@
+import inquirer from "inquirer";
+import path from "path";
+import fs from "fs-extra";
+import { downloadAndExtract, flattenGitHubZip } from "./downloadZip.js";
+const USERNAME = "Shadowdara";
+const REPO = "samengine-project-templates";
+export async function run() {
+    const answers = await inquirer.prompt([
+        {
+            name: "projectName",
+            message: "Project name?",
+            default: "my-game"
+        }
+    ]);
+    const targetDir = path.join(process.cwd(), answers.projectName);
+    console.log("📦 Downloading template repo...");
+    await downloadAndExtract(`https://codeload.github.com/${USERNAME}/${REPO}/zip/refs/heads/main`, targetDir);
+    await flattenGitHubZip(targetDir);
+    // -------------------------
+    // 1. VERSIONEN LADEN
+    // -------------------------
+    const versions = (await fs.readdir(targetDir))
+        .filter(v => fs.statSync(path.join(targetDir, v)).isDirectory());
+    const { version } = await inquirer.prompt([
+        {
+            name: "version",
+            message: "Choose version",
+            type: "select",
+            choices: versions
+        }
+    ]);
+    const versionPath = path.join(targetDir, version);
+    // -------------------------
+    // 2. STARTER LADEN
+    // -------------------------
+    const starters = (await fs.readdir(versionPath))
+        .filter(s => fs.statSync(path.join(versionPath, s)).isDirectory());
+    const { starter } = await inquirer.prompt([
+        {
+            name: "starter",
+            message: "Choose starter",
+            type: "select",
+            choices: starters
+        }
+    ]);
+    // -------------------------
+    // 3. CLEANUP (KEEP ONLY SELECTED)
+    // -------------------------
+    for (const v of await fs.readdir(targetDir)) {
+        const vPath = path.join(targetDir, v);
+        if (!(await fs.stat(vPath)).isDirectory())
+            continue;
+        if (v !== version) {
+            await fs.remove(vPath);
+            continue;
+        }
+        // remove other starters inside selected version
+        for (const s of await fs.readdir(vPath)) {
+            const sPath = path.join(vPath, s);
+            if (!(await fs.stat(sPath)).isDirectory())
+                continue;
+            if (s !== starter) {
+                await fs.remove(sPath);
+            }
+        }
+    }
+    // -------------------------
+    // 4. MOVE STARTER TO ROOT
+    // -------------------------
+    const starterPath = path.join(targetDir, version, starter);
+    const files = await fs.readdir(starterPath);
+    for (const file of files) {
+        await fs.move(path.join(starterPath, file), path.join(targetDir, file), { overwrite: true });
+    }
+    // -------------------------
+    // 5. FINAL CLEANUP
+    // -------------------------
+    await fs.remove(path.join(targetDir, version));
+    console.log("✅ Done!");
+    console.log(`👉 cd ${answers.projectName} && npm install`);
+}

package/dist/nonbrowser/utils.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Minifies generated HTML for release builds.
+ *
+ * The minifier also processes inline CSS and JavaScript, which matters for
+ * single-file builds because they can place the whole game shell into one
+ * `index.html`.
+ */
+export declare function compressHTML(html: string): Promise<string>;

package/dist/nonbrowser/utils.js

@@ -0,0 +1,18 @@
+import { minify } from "html-minifier-terser";
+/**
+ * Minifies generated HTML for release builds.
+ *
+ * The minifier also processes inline CSS and JavaScript, which matters for
+ * single-file builds because they can place the whole game shell into one
+ * `index.html`.
+ */
+export async function compressHTML(html) {
+    return await minify(html, {
+        collapseWhitespace: true,
+        removeComments: true,
+        removeRedundantAttributes: true,
+        removeEmptyAttributes: true,
+        minifyCSS: true,
+        minifyJS: true,
+    });
+}

package/dist/physics/collision.d.ts

@@ -1,5 +1,11 @@
 import { Vector2d } from "../types/vector2d.js";
 import { PhysicsObject } from "./physicsObject.js";
+/**
+ * Collision shape used by `PhysicsObject`.
+ *
+ * Circle and box colliders are centered on `body.position`. Box width and height
+ * are full extents, not half extents.
+ */
 export type Collider = {
     type: "circle";
     radius: number;
@@ -8,17 +14,44 @@ export type Collider = {
     width: number;
     height: number;
 };
+/**
+ * Tests two axis-aligned box colliders for overlap.
+ *
+ * @returns Collision normal and penetration depth, or `null` when separated.
+ */
 export declare function aabbCollision(a: PhysicsObject, b: PhysicsObject): {
     normal: Vector2d;
     penetration: number;
 } | null;
+/**
+ * Tests two circle colliders for overlap.
+ *
+ * @returns Collision normal from `a` to `b` and penetration depth, or `null`.
+ */
 export declare function circleCollision(a: PhysicsObject, b: PhysicsObject): {
     normal: Vector2d;
     penetration: number;
 } | null;
+/**
+ * Tests a circle collider against a box collider.
+ *
+ * The returned normal points from the closest box point toward the circle.
+ */
 export declare function circleBoxCollision(circleObj: PhysicsObject, boxObj: PhysicsObject): {
     normal: Vector2d;
     penetration: number;
 } | null;
+/**
+ * Applies an impulse to two bodies so their velocities respond to a collision.
+ *
+ * Static bodies are treated as having inverse mass `0`, so only dynamic bodies
+ * receive velocity changes.
+ */
 export declare function resolveCollision(a: PhysicsObject, b: PhysicsObject, normal: Vector2d): void;
+/**
+ * Moves overlapping bodies apart to remove visible penetration.
+ *
+ * The correction is distributed by inverse mass, so lighter dynamic bodies move
+ * more than heavier ones and static bodies do not move.
+ */
 export declare function positionalCorrection(a: PhysicsObject, b: PhysicsObject, normal: Vector2d, penetration: number): void;

package/dist/physics/collision.js

@@ -1,5 +1,10 @@
 import { add2d, dot2d, length2d, makeVector2d, normalize2d, scale2d, subtract2d } from "../types/vector2d.js";
 import { clamp } from "../utils/math.js";
+/**
+ * Tests two axis-aligned box colliders for overlap.
+ *
+ * @returns Collision normal and penetration depth, or `null` when separated.
+ */
 export function aabbCollision(a, b) {
     const posA = a.body.position;
     const posB = b.body.position;
@@ -27,6 +32,11 @@ export function aabbCollision(a, b) {
     }
     return null;
 }
+/**
+ * Tests two circle colliders for overlap.
+ *
+ * @returns Collision normal from `a` to `b` and penetration depth, or `null`.
+ */
 export function circleCollision(a, b) {
     const posA = a.body.position;
     const posB = b.body.position;
@@ -42,6 +52,11 @@ export function circleCollision(a, b) {
     }
     return null;
 }
+/**
+ * Tests a circle collider against a box collider.
+ *
+ * The returned normal points from the closest box point toward the circle.
+ */
 export function circleBoxCollision(circleObj, boxObj) {
     const circle = circleObj.collider;
     const box = boxObj.collider;
@@ -65,6 +80,12 @@ export function circleBoxCollision(circleObj, boxObj) {
     }
     return null;
 }
+/**
+ * Applies an impulse to two bodies so their velocities respond to a collision.
+ *
+ * Static bodies are treated as having inverse mass `0`, so only dynamic bodies
+ * receive velocity changes.
+ */
 export function resolveCollision(a, b, normal) {
     const rv = subtract2d(b.body.velocity, a.body.velocity);
     let velAlongNormal = dot2d(rv, normal);
@@ -83,6 +104,12 @@ export function resolveCollision(a, b, normal) {
     if (!b.body.isStatic)
         b.body.velocity = add2d(b.body.velocity, scale2d(impulse, invMassB));
 }
+/**
+ * Moves overlapping bodies apart to remove visible penetration.
+ *
+ * The correction is distributed by inverse mass, so lighter dynamic bodies move
+ * more than heavier ones and static bodies do not move.
+ */
 export function positionalCorrection(a, b, normal, penetration) {
     const percent = 1.0; // vorher 0.8
     const slop = 0.001; // vorher 0.01

package/dist/physics/physicsEngine.d.ts

@@ -1,8 +1,26 @@
 import { Vector2d } from "../types/vector2d.js";
 import { PhysicsObject } from "./physicsObject.js";
+/**
+ * Simple 2D physics simulation.
+ *
+ * `step(dt)` applies gravity, integrates positions, checks all object pairs, and
+ * resolves circle/box collisions. The implementation is intentionally small and
+ * best suited for arcade-style games rather than physically exact simulation.
+ */
 export declare class PhysicsWorld {
     objects: PhysicsObject[];
     gravity: Vector2d;
+    /**
+     * Advances the simulation by `dt` seconds.
+     *
+     * Use the delta time from `startEngine` for frame-rate independent motion.
+     */
     step(dt: number): void;
 }
+/**
+ * Sets gravity by direction and strength.
+ *
+ * `x` and `y` describe the direction vector and do not need to be normalized.
+ * `strength` becomes the final acceleration magnitude.
+ */
 export declare function setGravityDirection(world: PhysicsWorld, x: number, y: number, strength: number): void;

package/dist/physics/physicsEngine.js

@@ -15,11 +15,23 @@ import { aabbCollision, circleBoxCollision, circleCollision, positionalCorrectio
 // function update(dt: number) {
 //   world.step(dt);
 // }
+/**
+ * Simple 2D physics simulation.
+ *
+ * `step(dt)` applies gravity, integrates positions, checks all object pairs, and
+ * resolves circle/box collisions. The implementation is intentionally small and
+ * best suited for arcade-style games rather than physically exact simulation.
+ */
 export class PhysicsWorld {
     constructor() {
         this.objects = [];
         this.gravity = makeVector2d(0, 500); // px/s²
     }
+    /**
+     * Advances the simulation by `dt` seconds.
+     *
+     * Use the delta time from `startEngine` for frame-rate independent motion.
+     */
     step(dt) {
         // Bewegung
         for (const obj of this.objects) {
@@ -74,6 +86,12 @@ export class PhysicsWorld {
         }
     }
 }
+/**
+ * Sets gravity by direction and strength.
+ *
+ * `x` and `y` describe the direction vector and do not need to be normalized.
+ * `strength` becomes the final acceleration magnitude.
+ */
 export function setGravityDirection(world, x, y, strength) {
     const len = Math.sqrt(x * x + y * y);
     if (len === 0)

package/dist/physics/physicsObject.d.ts

@@ -1,15 +1,35 @@
 import { Vector2d } from "../types/vector2d.js";
 import { Collider } from "./collision.js";
+/**
+ * Physical body state used by the simple physics world.
+ *
+ * Positions and velocities use canvas-style 2D coordinates. Static bodies get
+ * infinite mass and are not moved by gravity or collision impulses.
+ */
 export declare class RigidBody {
     position: Vector2d;
     velocity: Vector2d;
     mass: number;
     restitution: number;
     isStatic: boolean;
+    /**
+     * Creates a rigid body.
+     *
+     * @param pos Initial center position.
+     * @param mass Body mass. Ignored for static bodies.
+     * @param restitution Bounciness factor used during collision resolution.
+     * @param isStatic Whether the body should behave like an immovable object.
+     */
     constructor(pos: Vector2d, mass?: number, restitution?: number, isStatic?: boolean);
 }
+/**
+ * Combines physical state with a collision shape.
+ */
 export declare class PhysicsObject {
     body: RigidBody;
     collider: Collider;
+    /**
+     * Creates a physics object from a body and collider.
+     */
     constructor(body: RigidBody, collider: Collider);
 }

package/dist/physics/physicsObject.js

@@ -1,5 +1,19 @@
 import { makeVector2d } from "../types/vector2d.js";
+/**
+ * Physical body state used by the simple physics world.
+ *
+ * Positions and velocities use canvas-style 2D coordinates. Static bodies get
+ * infinite mass and are not moved by gravity or collision impulses.
+ */
 export class RigidBody {
+    /**
+     * Creates a rigid body.
+     *
+     * @param pos Initial center position.
+     * @param mass Body mass. Ignored for static bodies.
+     * @param restitution Bounciness factor used during collision resolution.
+     * @param isStatic Whether the body should behave like an immovable object.
+     */
     constructor(pos, mass = 1, restitution = 0.8, isStatic = false) {
         this.position = pos;
         this.velocity = makeVector2d(0, 0);
@@ -8,7 +22,13 @@ export class RigidBody {
         this.isStatic = isStatic;
     }
 }
+/**
+ * Combines physical state with a collision shape.
+ */
 export class PhysicsObject {
+    /**
+     * Creates a physics object from a body and collider.
+     */
     constructor(body, collider) {
         this.body = body;
         this.collider = collider;

package/dist/renderer.d.ts

@@ -1,18 +1,96 @@
 import { type Rect } from "./types/rectangle.js";
 import { type Circle } from "./types/circle.js";
 import { type Triangle } from "./types/triangle.js";
+/**
+ * Draws normal browser/canvas text at the given position.
+ *
+ * The text baseline is set to `"top"`, so `x` and `y` describe the upper-left
+ * corner of the text area rather than the alphabetic baseline.
+ *
+ * @param ctx Canvas 2D rendering context to draw into.
+ * @param text Text that should be rendered.
+ * @param x Horizontal canvas coordinate.
+ * @param y Vertical canvas coordinate.
+ * @param color Fill color used for the text. Defaults to white.
+ * @param font Canvas font string, for example `"20px Arial"`.
+ * @deprecated Use samengine/text instead!
+ */
 export declare function renderText(ctx: CanvasRenderingContext2D, text: string, x: number, y: number, color?: string, font?: string): void;
+/**
+ * Maps a character to the rectangle where that character is located inside a
+ * bitmap font spritesheet.
+ */
 export type CharMap = Record<string, Rect>;
+/**
+ * Renders text from a bitmap font spritesheet.
+ *
+ * Every character in `text` is looked up in `charMap`. Characters that are not
+ * present in the map are skipped. Each source rectangle is drawn next to the
+ * previous one, so this is best suited for fixed-height bitmap fonts.
+ *
+ * @param ctx Canvas 2D rendering context to draw into.
+ * @param text Text to render.
+ * @param x Start x coordinate.
+ * @param y Start y coordinate.
+ * @param sprite Image containing all bitmap font glyphs.
+ * @param charMap Mapping from character to source rectangle in `sprite`.
+ * @param scale Size multiplier for rendered glyphs.
+ */
 export declare function renderBitmapText(ctx: CanvasRenderingContext2D, text: string, x: number, y: number, sprite: HTMLImageElement, charMap: CharMap, scale?: number): void;
+/**
+ * Draws a filled rectangle.
+ *
+ * If `rect.borderRadius` is greater than `0` and the browser supports
+ * `CanvasRenderingContext2D.roundRect`, a rounded rectangle is drawn.
+ * Otherwise the function falls back to `fillRect`.
+ */
 export declare function drawRect(ctx: CanvasRenderingContext2D, rect: Rect, color?: string): void;
+/**
+ * Draws the outline of a rectangle.
+ *
+ * Supports `rect.borderRadius` in the same way as `drawRect`.
+ *
+ * @param lineWidth Stroke width in canvas pixels.
+ */
 export declare function drawRectOutline(ctx: CanvasRenderingContext2D, rect: Rect, color?: string, lineWidth?: number): void;
+/**
+ * Draws a filled circle using the circle center and radius.
+ */
 export declare function drawCircle(ctx: CanvasRenderingContext2D, circle: Circle, color?: string): void;
+/**
+ * Draws the outline of a circle using the circle center and radius.
+ *
+ * @param lineWidth Stroke width in canvas pixels.
+ */
 export declare function drawCircleOutline(ctx: CanvasRenderingContext2D, circle: Circle, color?: string, lineWidth?: number): void;
+/**
+ * Draws a filled triangle from three points.
+ */
 export declare function drawTriangle(ctx: CanvasRenderingContext2D, triangle: Triangle, color?: string): void;
+/**
+ * Draws the outline of a triangle from three points.
+ *
+ * @param lineWidth Stroke width in canvas pixels.
+ */
 export declare function drawTriangleOutline(ctx: CanvasRenderingContext2D, triangle: Triangle, color?: string, lineWidth?: number): void;
+/**
+ * Renders one horizontally repeating parallax background layer.
+ *
+ * `cameraX` is multiplied by `speed` to create the parallax offset. Lower speed
+ * values make the layer move more slowly and feel farther away. The image is
+ * repeated horizontally until the full canvas width is covered.
+ */
 export declare function renderParallaxBackground(ctx: CanvasRenderingContext2D, image: HTMLImageElement, cameraX: number, speed?: number, canvasWidth?: number, canvasHeight?: number): void;
 export interface ParallaxLayer {
+    /** Image used for this layer. It must be loaded before it can be rendered. */
     image: HTMLImageElement;
+    /** Movement multiplier relative to `cameraX`. */
     speed: number;
 }
+/**
+ * Renders multiple parallax layers in array order.
+ *
+ * Place distant background layers first and foreground layers later so they draw
+ * on top of earlier layers.
+ */
 export declare function renderParallaxLayers(ctx: CanvasRenderingContext2D, layers: ParallaxLayer[], cameraX: number): void;

package/dist/renderer.js

@@ -1,10 +1,38 @@
-// Function to render Text
+/**
+ * Draws normal browser/canvas text at the given position.
+ *
+ * The text baseline is set to `"top"`, so `x` and `y` describe the upper-left
+ * corner of the text area rather than the alphabetic baseline.
+ *
+ * @param ctx Canvas 2D rendering context to draw into.
+ * @param text Text that should be rendered.
+ * @param x Horizontal canvas coordinate.
+ * @param y Vertical canvas coordinate.
+ * @param color Fill color used for the text. Defaults to white.
+ * @param font Canvas font string, for example `"20px Arial"`.
+ * @deprecated Use samengine/text instead!
+ */
 export function renderText(ctx, text, x, y, color = "white", font = "20px Arial") {
     ctx.fillStyle = color;
     ctx.font = font;
     ctx.textBaseline = "top";
     ctx.fillText(text, x, y);
 }
+/**
+ * Renders text from a bitmap font spritesheet.
+ *
+ * Every character in `text` is looked up in `charMap`. Characters that are not
+ * present in the map are skipped. Each source rectangle is drawn next to the
+ * previous one, so this is best suited for fixed-height bitmap fonts.
+ *
+ * @param ctx Canvas 2D rendering context to draw into.
+ * @param text Text to render.
+ * @param x Start x coordinate.
+ * @param y Start y coordinate.
+ * @param sprite Image containing all bitmap font glyphs.
+ * @param charMap Mapping from character to source rectangle in `sprite`.
+ * @param scale Size multiplier for rendered glyphs.
+ */
 export function renderBitmapText(ctx, text, x, y, sprite, charMap, scale = 1) {
     let offsetX = 0;
     for (const c of text) {
@@ -16,7 +44,13 @@ export function renderBitmapText(ctx, text, x, y, sprite, charMap, scale = 1) {
     }
 }
 // ===== SHAPE DRAWING =====
-// Function to draw a filled Rectangle
+/**
+ * Draws a filled rectangle.
+ *
+ * If `rect.borderRadius` is greater than `0` and the browser supports
+ * `CanvasRenderingContext2D.roundRect`, a rounded rectangle is drawn.
+ * Otherwise the function falls back to `fillRect`.
+ */
 export function drawRect(ctx, rect, color = "white") {
     ctx.fillStyle = color;
     const radius = rect.borderRadius ?? 0;
@@ -29,7 +63,13 @@ export function drawRect(ctx, rect, color = "white") {
         ctx.fillRect(rect.x, rect.y, rect.width, rect.height);
     }
 }
-// Function to draw a Rectangle outline
+/**
+ * Draws the outline of a rectangle.
+ *
+ * Supports `rect.borderRadius` in the same way as `drawRect`.
+ *
+ * @param lineWidth Stroke width in canvas pixels.
+ */
 export function drawRectOutline(ctx, rect, color = "white", lineWidth = 1) {
     ctx.strokeStyle = color;
     ctx.lineWidth = lineWidth;
@@ -43,14 +83,20 @@ export function drawRectOutline(ctx, rect, color = "white", lineWidth = 1) {
         ctx.strokeRect(rect.x, rect.y, rect.width, rect.height);
     }
 }
-// Function to draw a filled Circle
+/**
+ * Draws a filled circle using the circle center and radius.
+ */
 export function drawCircle(ctx, circle, color = "white") {
     ctx.fillStyle = color;
     ctx.beginPath();
     ctx.arc(circle.x, circle.y, circle.radius, 0, Math.PI * 2);
     ctx.fill();
 }
-// Function to draw a Circle outline
+/**
+ * Draws the outline of a circle using the circle center and radius.
+ *
+ * @param lineWidth Stroke width in canvas pixels.
+ */
 export function drawCircleOutline(ctx, circle, color = "white", lineWidth = 1) {
     ctx.strokeStyle = color;
     ctx.lineWidth = lineWidth;
@@ -58,7 +104,9 @@ export function drawCircleOutline(ctx, circle, color = "white", lineWidth = 1) {
     ctx.arc(circle.x, circle.y, circle.radius, 0, Math.PI * 2);
     ctx.stroke();
 }
-// Function to draw a filled Triangle
+/**
+ * Draws a filled triangle from three points.
+ */
 export function drawTriangle(ctx, triangle, color = "white") {
     ctx.fillStyle = color;
     ctx.beginPath();
@@ -68,7 +116,11 @@ export function drawTriangle(ctx, triangle, color = "white") {
     ctx.closePath();
     ctx.fill();
 }
-// Function to draw a Triangle outline
+/**
+ * Draws the outline of a triangle from three points.
+ *
+ * @param lineWidth Stroke width in canvas pixels.
+ */
 export function drawTriangleOutline(ctx, triangle, color = "white", lineWidth = 1) {
     ctx.strokeStyle = color;
     ctx.lineWidth = lineWidth;
@@ -79,7 +131,13 @@ export function drawTriangleOutline(ctx, triangle, color = "white", lineWidth =
     ctx.closePath();
     ctx.stroke();
 }
-// Function to render a parallax background layer
+/**
+ * Renders one horizontally repeating parallax background layer.
+ *
+ * `cameraX` is multiplied by `speed` to create the parallax offset. Lower speed
+ * values make the layer move more slowly and feel farther away. The image is
+ * repeated horizontally until the full canvas width is covered.
+ */
 export function renderParallaxBackground(ctx, image, cameraX, speed = 0.5, canvasWidth = ctx.canvas.width, canvasHeight = ctx.canvas.height) {
     if (!image.complete)
         return;
@@ -89,7 +147,12 @@ export function renderParallaxBackground(ctx, image, cameraX, speed = 0.5, canva
         ctx.drawImage(image, x, 0, image.width, canvasHeight);
     }
 }
-// Render multiple paralax Layers
+/**
+ * Renders multiple parallax layers in array order.
+ *
+ * Place distant background layers first and foreground layers later so they draw
+ * on top of earlier 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

@@ -1,8 +1,18 @@
 export type UIElementType = "button" | "text" | "checkbox";
+/**
+ * Stored DOM node for one immediate-mode UI element.
+ */
 export type UIElement = {
     el: HTMLElement;
     type: UIElementType;
 };
+/**
+ * Tiny immediate-mode HTML overlay for debug tools and simple in-game menus.
+ *
+ * Call `begin()` before emitting UI for the frame, then call `button`, `text`,
+ * and `checkbox` in a stable order, and finally call `end()`. Elements are
+ * backed by real DOM nodes but identified by hashed labels or explicit ids.
+ */
 export declare class HtmlUI {
     private root;
     private panel;
@@ -11,10 +21,29 @@ export declare class HtmlUI {
     private frameIds;
     private valueMap;
     constructor();
+    /**
+     * Starts a new UI frame and records which controls are used this frame.
+     */
     begin(): void;
+    /**
+     * Ends the UI frame and clears one-frame button click states.
+     */
     end(): void;
     private getButton;
+    /**
+     * Creates or updates a button.
+     *
+     * @returns `true` during the frame after the DOM button was clicked.
+     */
     button(label: string, idOverride?: string): boolean;
+    /**
+     * Creates or updates a text label in the overlay panel.
+     */
     text(label: string, idOverride?: string): void;
+    /**
+     * Creates or updates a checkbox and returns its current value.
+     *
+     * `defaultValue` is only used the first time the checkbox id appears.
+     */
     checkbox(label: string, defaultValue: boolean, idOverride?: string): boolean;
 }