@waica/engine 0.3.0

package/dist/components/solid.d.ts

@@ -0,0 +1,32 @@
+import { Component } from '../component.js';
+import { type CollisionPoint, type CollisionShape } from '../collision-shape.js';
+/**
+ * Static collider. Character motors (e.g. PlatformerMotor) collide against
+ * every Solid in the scene.
+ *
+ * TODO(H1): general dynamic bodies via Rapier; genre character controllers
+ * stay hand-rolled so their game feel remains deterministic.
+ */
+export declare class Solid 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[];
+    private get bounds();
+    get left(): number;
+    get right(): number;
+    get top(): number;
+    get bottom(): number;
+}

package/dist/components/solid.js

@@ -0,0 +1,45 @@
+import { Component } from '../component.js';
+import { collisionBounds, resolveCollisionPoints, } from '../collision-shape.js';
+/**
+ * Static collider. Character motors (e.g. PlatformerMotor) collide against
+ * every Solid in the scene.
+ *
+ * TODO(H1): general dynamic bodies via Rapier; genre character controllers
+ * stay hand-rolled so their game feel remains deterministic.
+ */
+export class Solid extends Component {
+    static componentName = 'Solid';
+    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);
+    get bounds() {
+        return collisionBounds({
+            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,
+        });
+    }
+    get left() {
+        return this.bounds.left;
+    }
+    get right() {
+        return this.bounds.right;
+    }
+    get top() {
+        return this.bounds.top;
+    }
+    get bottom() {
+        return this.bounds.bottom;
+    }
+}

package/dist/components/sprite.d.ts

@@ -0,0 +1,51 @@
+import { Component } from '../component.js';
+export type SpriteShape = 'rectangle' | 'circle';
+/**
+ * Textured or flat-color quad. In the unified pipeline, a 2D sprite is a
+ * plane in front of the orthographic camera (see DESIGN.md §6, decision 2).
+ */
+export declare class Sprite extends Component {
+    static componentName: string;
+    static params: {
+        offsetX: {
+            label: string;
+        };
+        offsetY: {
+            label: string;
+        };
+        layer: {
+            label: string;
+            min: number;
+            max: number;
+            step: number;
+        };
+    };
+    private _width;
+    private _height;
+    get width(): number;
+    set width(value: number);
+    get height(): number;
+    set height(value: number);
+    private _color;
+    get color(): number;
+    set color(value: number);
+    private _offsetX;
+    private _offsetY;
+    get offsetX(): number;
+    set offsetX(value: number);
+    get offsetY(): number;
+    set offsetY(value: number);
+    /** Optional texture URL; with pixelArt on it filters in nearest. */
+    texture?: string;
+    pixelArt: boolean;
+    private _layer;
+    get layer(): number;
+    set layer(value: number);
+    private _shape;
+    get shape(): SpriteShape;
+    set shape(value: SpriteShape);
+    private mesh?;
+    onReady(): void;
+    onDestroy(): void;
+    private createGeometry;
+}

package/dist/components/sprite.js

@@ -0,0 +1,112 @@
+import * as THREE from 'three';
+import { Component } from '../component.js';
+const loader = new THREE.TextureLoader();
+/**
+ * Textured or flat-color quad. In the unified pipeline, a 2D sprite is a
+ * plane in front of the orthographic camera (see DESIGN.md §6, decision 2).
+ */
+export class Sprite extends Component {
+    static componentName = 'Sprite';
+    static params = {
+        offsetX: { label: 'x offset' },
+        offsetY: { label: 'y offset' },
+        layer: { label: 'layer', min: -5, max: 5, step: 1 },
+    };
+    // Size, color and offset are reactive so inspector edits update the live quad.
+    // Texture still needs a rebuild. TODO(H1): fully reactive props.
+    _width = 1;
+    _height = 1;
+    get width() {
+        return this._width;
+    }
+    set width(value) {
+        this._width = value;
+        this.mesh?.scale.set(this._width, this._height, 1);
+    }
+    get height() {
+        return this._height;
+    }
+    set height(value) {
+        this._height = value;
+        this.mesh?.scale.set(this._width, this._height, 1);
+    }
+    _color = 0xffffff;
+    get color() {
+        return this._color;
+    }
+    set color(value) {
+        this._color = value;
+        this.mesh?.material.color.setHex(value);
+    }
+    _offsetX = 0;
+    _offsetY = 0;
+    get offsetX() {
+        return this._offsetX;
+    }
+    set offsetX(value) {
+        this._offsetX = value;
+        if (this.mesh)
+            this.mesh.position.x = value;
+    }
+    get offsetY() {
+        return this._offsetY;
+    }
+    set offsetY(value) {
+        this._offsetY = value;
+        if (this.mesh)
+            this.mesh.position.y = value;
+    }
+    /** Optional texture URL; with pixelArt on it filters in nearest. */
+    texture;
+    pixelArt = false;
+    // 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;
+    }
+    _shape = 'rectangle';
+    get shape() {
+        return this._shape;
+    }
+    set shape(value) {
+        this._shape = value === 'circle' ? 'circle' : 'rectangle';
+        if (!this.mesh)
+            return;
+        this.mesh.geometry.dispose();
+        this.mesh.geometry = this.createGeometry();
+    }
+    mesh;
+    onReady() {
+        const material = new THREE.MeshBasicMaterial({ color: this.color, transparent: true });
+        if (this.texture) {
+            const tex = loader.load(this.texture);
+            if (this.pixelArt) {
+                tex.magFilter = THREE.NearestFilter;
+                tex.minFilter = THREE.NearestFilter;
+            }
+            tex.colorSpace = THREE.SRGBColorSpace;
+            material.map = tex;
+            material.color.set(0xffffff);
+        }
+        this.mesh = new THREE.Mesh(this.createGeometry(), material);
+        this.mesh.scale.set(this._width, this._height, 1);
+        this.mesh.position.set(this._offsetX, this._offsetY, this.layer * 0.01);
+        this.entity.node.add(this.mesh);
+    }
+    onDestroy() {
+        this.mesh?.removeFromParent();
+        this.mesh?.geometry.dispose();
+        this.mesh?.material.dispose();
+    }
+    createGeometry() {
+        return this._shape === 'circle'
+            ? new THREE.CircleGeometry(0.5, 32)
+            : new THREE.PlaneGeometry(1, 1);
+    }
+}

package/dist/entity.d.ts

@@ -0,0 +1,22 @@
+import * as THREE from 'three';
+import type { Component, ComponentClass } from './component.js';
+import type { Game } from './game.js';
+/**
+ * A live scene node: a transform (three Group) + components.
+ * Created with `game.spawn(name)`.
+ */
+export declare class Entity {
+    readonly game: Game;
+    readonly name: string;
+    readonly node: THREE.Group<THREE.Object3DEventMap>;
+    readonly components: Component[];
+    private destroyed;
+    get alive(): boolean;
+    constructor(game: Game, name: string);
+    get position(): THREE.Vector3;
+    get scale(): THREE.Vector3;
+    add<T extends Component>(Class: ComponentClass<T>, props?: Partial<T>): T;
+    get<T extends Component>(Class: ComponentClass<T>): T | undefined;
+    has<T extends Component>(Class: ComponentClass<T>): boolean;
+    destroy(): void;
+}

package/dist/entity.js

@@ -0,0 +1,52 @@
+import * as THREE from 'three';
+/**
+ * A live scene node: a transform (three Group) + components.
+ * Created with `game.spawn(name)`.
+ */
+export class Entity {
+    game;
+    name;
+    node = new THREE.Group();
+    components = [];
+    destroyed = false;
+    get alive() {
+        return !this.destroyed;
+    }
+    constructor(game, name) {
+        this.game = game;
+        this.name = name;
+    }
+    get position() {
+        return this.node.position;
+    }
+    get scale() {
+        return this.node.scale;
+    }
+    add(Class, props) {
+        const component = new Class();
+        component.entity = this;
+        component.game = this.game;
+        if (props)
+            Object.assign(component, props);
+        this.game.applyParamOverrides(this, component);
+        this.components.push(component);
+        component.onReady?.();
+        return component;
+    }
+    get(Class) {
+        return this.components.find((c) => c instanceof Class);
+    }
+    has(Class) {
+        return this.components.some((c) => c instanceof Class);
+    }
+    destroy() {
+        if (this.destroyed)
+            return;
+        this.destroyed = true;
+        for (const c of [...this.components])
+            c.onDestroy?.();
+        this.components.length = 0;
+        this.node.removeFromParent();
+        this.game.removeEntity(this);
+    }
+}

package/dist/events.d.ts

@@ -0,0 +1,8 @@
+type Handler = (...args: unknown[]) => void;
+/** The game's minimal event bus (e.g. 'collect' when picking up a coin). */
+export declare class Emitter {
+    private readonly handlers;
+    on(event: string, handler: Handler): () => void;
+    emit(event: string, ...args: unknown[]): void;
+}
+export {};

package/dist/events.js

@@ -0,0 +1,20 @@
+/** The game's minimal event bus (e.g. 'collect' when picking up a coin). */
+export class Emitter {
+    handlers = new Map();
+    on(event, handler) {
+        let set = this.handlers.get(event);
+        if (!set) {
+            set = new Set();
+            this.handlers.set(event, set);
+        }
+        set.add(handler);
+        return () => set.delete(handler);
+    }
+    emit(event, ...args) {
+        const set = this.handlers.get(event);
+        if (!set)
+            return;
+        for (const handler of [...set])
+            handler(...args);
+    }
+}

package/dist/game.d.ts

@@ -0,0 +1,95 @@
+import * as THREE from 'three';
+import { type SceneCameraJson } from './camera.js';
+import type { Component } from './component.js';
+import { Entity } from './entity.js';
+import { Emitter } from './events.js';
+import { Input, type InputBindings } from './input.js';
+import { type SceneRegistry } from './scene.js';
+import { Stats, type StatValue } from './stats.js';
+import { GameUi } from './ui.js';
+/** Fixed game resolution: the view keeps this aspect, letterboxed. */
+export interface GameResolution {
+    width: number;
+    height: number;
+}
+export interface GameOptions {
+    /** Canvas the game draws into. */
+    canvas: HTMLCanvasElement;
+    /** Scene background color. */
+    background?: THREE.ColorRepresentation;
+    /** Visible world height in units; the 2D camera frames this. */
+    viewHeight?: number;
+    /** Fixed resolution (from the project's game.json); absent = fill the canvas. */
+    resolution?: GameResolution;
+    /** Control overrides (action → key codes) on top of the defaults. */
+    bindings?: InputBindings;
+    /** Initial stat values (points, lives…) from the project's stats.json. */
+    stats?: Record<string, StatValue>;
+}
+export type UpdateFn = (dt: number) => void;
+export interface SpawnPrefabOptions {
+    name?: string;
+    position?: [number, number];
+}
+/** Persisted overrides: entity → componentName → prop → value. */
+export type ParamOverrides = Record<string, Record<string, Record<string, number | boolean | string>>>;
+/**
+ * Engine core: loop, unified 2D/3D three scene, orthographic camera,
+ * entities with components, and input. See DESIGN.md.
+ */
+export declare class Game {
+    readonly scene: THREE.Scene<THREE.Object3DEventMap>;
+    readonly camera: THREE.OrthographicCamera;
+    readonly input: Input;
+    readonly entities: Entity[];
+    readonly events: Emitter;
+    readonly stats: Stats;
+    /** The HTML UI layer: presentation-only pieces toggled from code. */
+    readonly ui: GameUi;
+    /** Registry retained by loadScene for runtime prefab spawning. */
+    registry: SceneRegistry | null;
+    paramOverrides: ParamOverrides;
+    /**
+     * With false, the loop keeps rendering but runs no component updates
+     * or collisions — the editor's edit mode.
+     */
+    simulate: boolean;
+    private readonly renderer;
+    private readonly resizeObserver;
+    private readonly updateFns;
+    private readonly resolution;
+    private viewHeight;
+    private sceneCamera;
+    private lastTime;
+    constructor(options: GameOptions);
+    /** Creates a live entity in the scene. */
+    spawn(name: string): Entity;
+    /** Instantiates a registered prefab after a scene has supplied the registry. */
+    spawnPrefab(prefab: string, options?: SpawnPrefabOptions): Entity | null;
+    /** Finds an entity by name. */
+    find(name: string): Entity | undefined;
+    /** Loads persisted parameter overrides (waica.params.json). */
+    loadParams(url: string): Promise<void>;
+    /** Applies persisted overrides to a freshly added component. */
+    applyParamOverrides(entity: Entity, component: Component): void;
+    /** Registers a function that runs once per frame. Returns the unsubscribe. */
+    onUpdate(fn: UpdateFn): () => void;
+    /**
+     * Adopts a scene's camera block: jumps to its framing and, while
+     * simulating, follows/clamps per its settings. Called by loadScene.
+     */
+    setSceneCamera(json?: SceneCameraJson): void;
+    start(): void;
+    stop(): void;
+    /** Internal: called by Entity.destroy(). */
+    removeEntity(entity: Entity): void;
+    /** Visible world height (2D camera zoom). */
+    get view(): number;
+    setViewHeight(value: number): void;
+    /** Shuts the game down completely (loop, input, GPU). */
+    dispose(): void;
+    private tick;
+    private updateSceneCamera;
+    private dispatchCollisions;
+    private resize;
+}