@waica/engine 0.3.0

package/dist/component.d.ts

@@ -0,0 +1,58 @@
+import type { Entity } from './entity.js';
+import type { Game } from './game.js';
+import type { Solid } from './components/solid.js';
+/** Metadata for a parameter editable from the inspector. */
+export interface ParamSpec {
+    label?: string;
+    min?: number;
+    max?: number;
+    step?: number;
+    /** Allowed values for a string param; rendered as a dropdown. */
+    options?: string[];
+}
+export interface ComponentClass<T extends Component = Component> {
+    new (): T;
+    /**
+     * Stable component name (survives minification).
+     * Used for `waica.params.json` overrides and the inspector.
+     */
+    componentName: string;
+    /** Friendly name the inspector shows instead of componentName. */
+    displayName?: string;
+    /** Which properties the inspector exposes, with their ranges. */
+    params?: Record<string, ParamSpec>;
+}
+/** Cardinal unit normal pointing away from the contacted Solid surface. */
+export interface ContactNormal {
+    readonly x: -1 | 0 | 1;
+    readonly y: -1 | 0 | 1;
+}
+/** A physical DynamicBody contact, deliberately separate from Hitbox triggers. */
+export interface SolidContact {
+    /** Entity that owns the contacted Solid. */
+    readonly entity: Entity;
+    readonly solid: Solid;
+    readonly axis: 'x' | 'y';
+    readonly normal: ContactNormal;
+}
+/**
+ * A pluggable piece of an entity. User behaviors and engine ones are the
+ * same thing: Component subclasses with public props.
+ */
+export declare abstract class Component {
+    static componentName: string;
+    static displayName?: string;
+    static params?: Record<string, ParamSpec>;
+    entity: Entity;
+    game: Game;
+    /** Runs once the component is mounted on its entity. */
+    onReady?(): void;
+    /** Runs once per frame. */
+    onUpdate?(dt: number): void;
+    /** Runs when this entity's Hitbox overlaps another one's. */
+    onCollide?(other: Entity): void;
+    /** Runs when this entity's DynamicBody physically contacts a Solid. */
+    onContact?(contact: SolidContact): void;
+    /** Runs when the entity is destroyed or the component removed. */
+    onDestroy?(): void;
+}

package/dist/component.js

@@ -0,0 +1,11 @@
+/**
+ * A pluggable piece of an entity. User behaviors and engine ones are the
+ * same thing: Component subclasses with public props.
+ */
+export class Component {
+    static componentName = 'Component';
+    static displayName;
+    static params;
+    entity;
+    game;
+}

package/dist/components/animated-sprite.d.ts

@@ -0,0 +1,80 @@
+import { Component } from '../component.js';
+import { type ClipDef } from '../animation/clip-player.js';
+import { type SheetCell, type SheetDef } from '../animation/sheet.js';
+/**
+ * Sprite animated from one or more spritesheets. The main sheet is the
+ * top-level texture/cols/rows (or explicit cells); extraSheets append after
+ * it, and clip frames index the sheets consecutively (sheet 0 owns 0..n0-1,
+ * sheet 1 the next n1, …). Each instance clones its textures to animate UVs
+ * independently. On sheets with explicit cells the frames vary in pixel size,
+ * so the quad rescales per frame, anchored bottom-center — width/height size
+ * the sheet's largest frame and smaller ones keep their feet planted.
+ */
+export declare class AnimatedSprite extends Component {
+    static componentName: string;
+    static params: {
+        offsetX: {
+            label: string;
+        };
+        offsetY: {
+            label: string;
+        };
+        layer: {
+            label: string;
+            min: number;
+            max: number;
+            step: number;
+        };
+    };
+    /** Spritesheet URL. */
+    texture: string;
+    /** Sheet grid dimensions. */
+    cols: number;
+    rows: number;
+    gridOffsetX: number;
+    gridOffsetY: number;
+    spacingX: number;
+    spacingY: number;
+    cellWidth: number;
+    cellHeight: number;
+    /** Explicit frame rects for the main sheet (packed sheets); wins over the grid. */
+    cells: SheetCell[];
+    /** Additional sheets after the main one; clip frames continue across them. */
+    extraSheets: SheetDef[];
+    private _width;
+    private _height;
+    get width(): number;
+    set width(value: number);
+    get height(): number;
+    set height(value: number);
+    private _offsetX;
+    private _offsetY;
+    get offsetX(): number;
+    set offsetX(value: number);
+    get offsetY(): number;
+    set offsetY(value: number);
+    pixelArt: boolean;
+    private _layer;
+    get layer(): number;
+    set layer(value: number);
+    clips: Record<string, ClipDef>;
+    initialClip?: string;
+    /** Clip currently playing. */
+    current?: string;
+    private readonly player;
+    private sheets;
+    private texs;
+    private mesh?;
+    private frame;
+    private frameScaleX;
+    private frameScaleY;
+    onReady(): void;
+    /** Switches clip; repeating the same name doesn't restart the animation. */
+    play(name: string): void;
+    onUpdate(dt: number): void;
+    onDestroy(): void;
+    private showFrame;
+    /** Repositions/rescales the quad from size, offsets and the frame scale. */
+    private syncQuad;
+    private applyFrame;
+}

package/dist/components/animated-sprite.js

@@ -0,0 +1,210 @@
+import * as THREE from 'three';
+import { Component } from '../component.js';
+import { ClipPlayer } from '../animation/clip-player.js';
+import { locateFrame, sheetCell } from '../animation/sheet.js';
+const loader = new THREE.TextureLoader();
+/**
+ * Sprite animated from one or more spritesheets. The main sheet is the
+ * top-level texture/cols/rows (or explicit cells); extraSheets append after
+ * it, and clip frames index the sheets consecutively (sheet 0 owns 0..n0-1,
+ * sheet 1 the next n1, …). Each instance clones its textures to animate UVs
+ * independently. On sheets with explicit cells the frames vary in pixel size,
+ * so the quad rescales per frame, anchored bottom-center — width/height size
+ * the sheet's largest frame and smaller ones keep their feet planted.
+ */
+export class AnimatedSprite extends Component {
+    static componentName = 'AnimatedSprite';
+    static params = {
+        offsetX: { label: 'x offset' },
+        offsetY: { label: 'y offset' },
+        layer: { label: 'layer', min: -5, max: 5, step: 1 },
+    };
+    /** Spritesheet URL. */
+    texture = '';
+    /** Sheet grid dimensions. */
+    cols = 1;
+    rows = 1;
+    // Slicing params for sheets whose frames don't fill the image (margins,
+    // gaps, fixed cell size). In image pixels; 0 = default uniform grid.
+    gridOffsetX = 0;
+    gridOffsetY = 0;
+    spacingX = 0;
+    spacingY = 0;
+    cellWidth = 0;
+    cellHeight = 0;
+    /** Explicit frame rects for the main sheet (packed sheets); wins over the grid. */
+    cells = [];
+    /** Additional sheets after the main one; clip frames continue across them. */
+    extraSheets = [];
+    // Size in world units. Reactive like Sprite's: assigning rescales the unit
+    // quad, even outside the simulation loop (the editor drags them live).
+    _width = 1;
+    _height = 1;
+    get width() {
+        return this._width;
+    }
+    set width(value) {
+        this._width = value;
+        this.syncQuad();
+    }
+    get height() {
+        return this._height;
+    }
+    set height(value) {
+        this._height = value;
+        this.syncQuad();
+    }
+    _offsetX = 0;
+    _offsetY = 0;
+    get offsetX() {
+        return this._offsetX;
+    }
+    set offsetX(value) {
+        this._offsetX = value;
+        this.syncQuad();
+    }
+    get offsetY() {
+        return this._offsetY;
+    }
+    set offsetY(value) {
+        this._offsetY = value;
+        this.syncQuad();
+    }
+    pixelArt = true;
+    // Draw order among sprites: higher layers render in front. Same-layer
+    // sprites fall back to spawn order, so give overlap an explicit layer.
+    _layer = 0;
+    get layer() {
+        return this._layer;
+    }
+    set layer(value) {
+        this._layer = value;
+        if (this.mesh)
+            this.mesh.position.z = value * 0.01;
+    }
+    clips = {};
+    initialClip;
+    /** Clip currently playing. */
+    current;
+    player = new ClipPlayer();
+    sheets = [];
+    texs = [];
+    mesh;
+    frame = 0;
+    // Current frame's quad scale relative to the sheet's largest cell: always
+    // 1 on grid sheets, per-frame on cell sheets (frames vary in pixel size).
+    frameScaleX = 1;
+    frameScaleY = 1;
+    onReady() {
+        const main = {
+            texture: this.texture,
+            cols: this.cols,
+            rows: this.rows,
+            gridOffsetX: this.gridOffsetX,
+            gridOffsetY: this.gridOffsetY,
+            spacingX: this.spacingX,
+            spacingY: this.spacingY,
+            cellWidth: this.cellWidth,
+            cellHeight: this.cellHeight,
+        };
+        if (this.cells.length)
+            main.cells = this.cells;
+        this.sheets = [main, ...this.extraSheets];
+        this.texs = this.sheets.map((sheet) => {
+            // Non-uniform slicing needs the image's pixel size, so re-apply the
+            // current frame once each texture is in.
+            const tex = loader.load(sheet.texture, () => this.applyFrame());
+            tex.colorSpace = THREE.SRGBColorSpace;
+            if (this.pixelArt) {
+                tex.magFilter = THREE.NearestFilter;
+                tex.minFilter = THREE.NearestFilter;
+            }
+            tex.repeat.set(1 / Math.max(1, sheet.cols), 1 / Math.max(1, sheet.rows));
+            return tex;
+        });
+        const material = new THREE.MeshBasicMaterial({ map: this.texs[0], transparent: true });
+        this.mesh = new THREE.Mesh(new THREE.PlaneGeometry(1, 1), material);
+        this.mesh.position.z = this.layer * 0.01;
+        this.syncQuad();
+        this.entity.node.add(this.mesh);
+        if (this.initialClip)
+            this.play(this.initialClip);
+    }
+    /** Switches clip; repeating the same name doesn't restart the animation. */
+    play(name) {
+        if (this.current === name)
+            return;
+        const clip = this.clips[name];
+        if (!clip)
+            return;
+        this.player.set(clip);
+        this.current = name;
+    }
+    onUpdate(dt) {
+        if (this.texs.length === 0 || !this.current)
+            return;
+        this.showFrame(this.player.advance(dt));
+    }
+    onDestroy() {
+        this.mesh?.removeFromParent();
+        this.mesh?.geometry.dispose();
+        this.mesh?.material.dispose();
+        for (const tex of this.texs)
+            tex.dispose();
+    }
+    showFrame(index) {
+        this.frame = index;
+        this.applyFrame();
+    }
+    /** Repositions/rescales the quad from size, offsets and the frame scale. */
+    syncQuad() {
+        if (!this.mesh)
+            return;
+        this.mesh.scale.set(this._width * this.frameScaleX, this._height * this.frameScaleY, 1);
+        // Bottom-center anchor: a shrunk frame keeps its feet on the quad's floor.
+        this.mesh.position.x = this._offsetX;
+        this.mesh.position.y = this._offsetY - (this._height * (1 - this.frameScaleY)) / 2;
+    }
+    applyFrame() {
+        const located = locateFrame(this.sheets, this.frame);
+        const sheet = this.sheets[located.sheet];
+        const tex = this.texs[located.sheet];
+        if (!sheet || !tex)
+            return;
+        if (this.mesh && this.mesh.material.map !== tex) {
+            this.mesh.material.map = tex;
+            this.mesh.material.needsUpdate = true;
+        }
+        const cells = sheet.cells;
+        if (cells?.length) {
+            const cell = sheetCell(0, 0, sheet.cols, sheet.rows, located.frame, sheet);
+            const maxW = Math.max(...cells.map((c) => c.width));
+            const maxH = Math.max(...cells.map((c) => c.height));
+            this.frameScaleX = maxW > 0 ? cell.width / maxW : 1;
+            this.frameScaleY = maxH > 0 ? cell.height / maxH : 1;
+            this.syncQuad();
+            const image = tex.image;
+            if (image?.width && image?.height) {
+                tex.repeat.set(cell.width / image.width, cell.height / image.height);
+                tex.offset.set(cell.x / image.width, 1 - (cell.y + cell.height) / image.height);
+            }
+            return;
+        }
+        if (this.frameScaleX !== 1 || this.frameScaleY !== 1) {
+            this.frameScaleX = 1;
+            this.frameScaleY = 1;
+            this.syncQuad();
+        }
+        const image = tex.image;
+        if (image?.width && image?.height) {
+            const cell = sheetCell(image.width, image.height, sheet.cols, sheet.rows, located.frame, sheet);
+            tex.repeat.set(cell.width / image.width, cell.height / image.height);
+            tex.offset.set(cell.x / image.width, 1 - (cell.y + cell.height) / image.height);
+            return;
+        }
+        // Image not loaded yet: uniform-grid math needs no pixel size.
+        const cols = Math.max(1, sheet.cols);
+        const rows = Math.max(1, sheet.rows);
+        tex.offset.set((located.frame % cols) / cols, 1 - (Math.floor(located.frame / cols) + 1) / rows);
+    }
+}

package/dist/components/dynamic-body.d.ts

@@ -0,0 +1,68 @@
+import { type CollisionPoint, type CollisionShape } from '../collision-shape.js';
+import { Component } from '../component.js';
+/**
+ * Reusable linear body: integrates its public velocity and resolves only
+ * against static Solid geometry. Hitbox trigger overlaps remain independent.
+ */
+export declare class DynamicBody extends Component {
+    static componentName: string;
+    static params: {
+        vx: {
+            label: string;
+            step: number;
+        };
+        vy: {
+            label: string;
+            step: number;
+        };
+        shape: {
+            label: string;
+            options: CollisionShape[];
+        };
+        width: {
+            label: string;
+            min: number;
+            step: number;
+        };
+        height: {
+            label: string;
+            min: number;
+            step: number;
+        };
+        offsetX: {
+            label: string;
+            step: number;
+        };
+        offsetY: {
+            label: string;
+            step: number;
+        };
+        points: {
+            label: string;
+        };
+    };
+    vx: number;
+    vy: number;
+    shape: CollisionShape;
+    width: number;
+    height: number;
+    offsetX: number;
+    offsetY: number;
+    /** Polygon vertices normalized against width/height. */
+    points: CollisionPoint[];
+    onUpdate(dt: number): void;
+    private moveAxis;
+    /**
+     * Finds the shortest cardinal translation that clears every Solid.
+     * Equal distances keep RECOVERY_DIRECTIONS order: -X, +X, -Y, +Y.
+     */
+    private recoverInitialOverlap;
+    private setShift;
+    private resetPosition;
+    private overlapsAny;
+    private deliver;
+    private contact;
+    private solids;
+    private collisionBody;
+    private solidBody;
+}

package/dist/components/dynamic-body.js

@@ -0,0 +1,189 @@
+import { COLLISION_SHAPES, collisionBounds, collisionOverlap, resolveCollisionPoints, } from '../collision-shape.js';
+import { Component } from '../component.js';
+import { resolveSolidAxis } from '../solid-axis.js';
+import { Solid } from './solid.js';
+/** Stable tie order for equal-distance initial-overlap recovery. */
+const RECOVERY_DIRECTIONS = [
+    { axis: 'x', sign: -1, normal: { x: -1, y: 0 } },
+    { axis: 'x', sign: 1, normal: { x: 1, y: 0 } },
+    { axis: 'y', sign: -1, normal: { x: 0, y: -1 } },
+    { axis: 'y', sign: 1, normal: { x: 0, y: 1 } },
+];
+const RECOVERY_ITERATIONS = 24;
+/**
+ * Reusable linear body: integrates its public velocity and resolves only
+ * against static Solid geometry. Hitbox trigger overlaps remain independent.
+ */
+export class DynamicBody extends Component {
+    static componentName = 'DynamicBody';
+    static params = {
+        vx: { label: 'x velocity', step: 0.1 },
+        vy: { label: 'y velocity', step: 0.1 },
+        shape: { label: 'shape', options: [...COLLISION_SHAPES] },
+        width: { label: 'width', min: 0, step: 0.1 },
+        height: { label: 'height', min: 0, step: 0.1 },
+        offsetX: { label: 'x offset', step: 0.1 },
+        offsetY: { label: 'y offset', step: 0.1 },
+        points: { label: 'polygon points' },
+    };
+    vx = 0;
+    vy = 0;
+    shape = 'rectangle';
+    width = 1;
+    height = 1;
+    offsetX = 0;
+    offsetY = 0;
+    /** Polygon vertices normalized against width/height. */
+    points = resolveCollisionPoints(undefined);
+    onUpdate(dt) {
+        const delivered = new Map();
+        const recovery = this.recoverInitialOverlap();
+        if (recovery && !this.deliver(recovery.contacts, delivered))
+            return;
+        if (!this.moveAxis('x', this.vx * dt, delivered))
+            return;
+        this.moveAxis('y', this.vy * dt, delivered);
+    }
+    moveAxis(axis, displacement, delivered) {
+        if (displacement === 0)
+            return this.entity.alive;
+        const previous = this.entity.position[axis];
+        this.entity.position[axis] += displacement;
+        const solids = [];
+        const blocked = resolveSolidAxis({
+            entity: this.entity,
+            axis,
+            previous,
+            body: () => this.collisionBody(),
+            onContact: (solid) => solids.push(solid),
+        });
+        if (!blocked)
+            return this.entity.alive;
+        if (axis === 'x')
+            this.vx = 0;
+        else
+            this.vy = 0;
+        const normal = axis === 'x'
+            ? { x: displacement > 0 ? -1 : 1, y: 0 }
+            : { x: 0, y: displacement > 0 ? -1 : 1 };
+        return this.deliver(solids.map((solid) => this.contact(solid, axis, normal)), delivered);
+    }
+    /**
+     * Finds the shortest cardinal translation that clears every Solid.
+     * Equal distances keep RECOVERY_DIRECTIONS order: -X, +X, -Y, +Y.
+     */
+    recoverInitialOverlap() {
+        const solids = this.solids();
+        const overlapping = solids.filter((solid) => collisionOverlap(this.collisionBody(), this.solidBody(solid)));
+        if (overlapping.length === 0)
+            return null;
+        const original = { x: this.entity.position.x, y: this.entity.position.y };
+        const bodyBounds = collisionBounds(this.collisionBody());
+        let best = null;
+        for (const direction of RECOVERY_DIRECTIONS) {
+            const shifts = solids
+                .map((solid) => {
+                const bounds = collisionBounds(this.solidBody(solid));
+                if (direction.axis === 'x') {
+                    return direction.sign < 0
+                        ? bounds.left - bodyBounds.right
+                        : bounds.right - bodyBounds.left;
+                }
+                return direction.sign < 0
+                    ? bounds.bottom - bodyBounds.top
+                    : bounds.top - bodyBounds.bottom;
+            })
+                .filter((shift) => shift * direction.sign > 0)
+                .sort((a, b) => Math.abs(a) - Math.abs(b));
+            let clear = null;
+            for (const shift of shifts) {
+                this.setShift(original, direction.axis, shift);
+                if (!this.overlapsAny(solids)) {
+                    clear = shift;
+                    break;
+                }
+            }
+            this.resetPosition(original);
+            if (clear === null)
+                continue;
+            let blockedShift = 0;
+            let clearShift = clear;
+            for (let iteration = 0; iteration < RECOVERY_ITERATIONS; iteration++) {
+                const middle = (blockedShift + clearShift) / 2;
+                this.setShift(original, direction.axis, middle);
+                if (this.overlapsAny(solids))
+                    blockedShift = middle;
+                else
+                    clearShift = middle;
+            }
+            this.resetPosition(original);
+            if (best && Math.abs(clearShift) >= Math.abs(best.shift))
+                continue;
+            best = {
+                direction,
+                shift: clearShift,
+                contacts: overlapping.map((solid) => this.contact(solid, direction.axis, direction.normal)),
+            };
+        }
+        if (!best)
+            return null;
+        this.setShift(original, best.direction.axis, best.shift);
+        return best;
+    }
+    setShift(original, axis, shift) {
+        this.entity.position[axis] = original[axis] + shift;
+    }
+    resetPosition(original) {
+        this.entity.position.x = original.x;
+        this.entity.position.y = original.y;
+    }
+    overlapsAny(solids) {
+        const body = this.collisionBody();
+        return solids.some((solid) => collisionOverlap(body, this.solidBody(solid)));
+    }
+    deliver(contacts, delivered) {
+        for (const contact of contacts) {
+            const direction = `${contact.axis}:${contact.normal.x}:${contact.normal.y}`;
+            const directions = delivered.get(contact.solid) ?? new Set();
+            if (directions.has(direction))
+                continue;
+            directions.add(direction);
+            delivered.set(contact.solid, directions);
+            for (const component of [...this.entity.components]) {
+                if (!this.entity.alive)
+                    return false;
+                component.onContact?.(contact);
+            }
+        }
+        return this.entity.alive;
+    }
+    contact(solid, axis, normal) {
+        return { entity: solid.entity, solid, axis, normal };
+    }
+    solids() {
+        return this.game.entities
+            .filter((entity) => entity !== this.entity)
+            .map((entity) => entity.get(Solid))
+            .filter((solid) => solid !== undefined);
+    }
+    collisionBody() {
+        return {
+            x: this.entity.position.x + this.offsetX,
+            y: this.entity.position.y + this.offsetY,
+            width: this.width,
+            height: this.height,
+            shape: this.shape,
+            points: this.points,
+        };
+    }
+    solidBody(solid) {
+        return {
+            x: solid.entity.position.x + solid.offsetX,
+            y: solid.entity.position.y + solid.offsetY,
+            width: solid.width,
+            height: solid.height,
+            shape: solid.shape,
+            points: solid.points,
+        };
+    }
+}

package/dist/components/hitbox.d.ts

@@ -0,0 +1,25 @@
+import { Component } from '../component.js';
+import { type CollisionPoint, type CollisionShape } from '../collision-shape.js';
+/**
+ * Trigger collider: the Game detects overlaps between Hitboxes and calls
+ * onCollide(other) on both entities' components. For static physical
+ * collision see Solid.
+ */
+export declare class Hitbox extends Component {
+    static componentName: string;
+    static params: {
+        offsetX: {
+            label: string;
+        };
+        offsetY: {
+            label: string;
+        };
+    };
+    shape: CollisionShape;
+    width: number;
+    height: number;
+    offsetX: number;
+    offsetY: number;
+    /** Polygon vertices normalized against width/height. */
+    points: CollisionPoint[];
+}

package/dist/components/hitbox.js

@@ -0,0 +1,21 @@
+import { Component } from '../component.js';
+import { resolveCollisionPoints, } from '../collision-shape.js';
+/**
+ * Trigger collider: the Game detects overlaps between Hitboxes and calls
+ * onCollide(other) on both entities' components. For static physical
+ * collision see Solid.
+ */
+export class Hitbox extends Component {
+    static componentName = 'Hitbox';
+    static params = {
+        offsetX: { label: 'x offset' },
+        offsetY: { label: 'y offset' },
+    };
+    shape = 'rectangle';
+    width = 1;
+    height = 1;
+    offsetX = 0;
+    offsetY = 0;
+    /** Polygon vertices normalized against width/height. */
+    points = resolveCollisionPoints(undefined);
+}