@waica/engine 0.9.1 → 0.11.0

package/dist/game.d.ts

@@ -4,6 +4,7 @@ import type { Component } from './component.js';
 import { Entity } from './entity.js';
 import { Emitter } from './events.js';
 import { Input, type InputBindings } from './input.js';
+import { Pointer } from './pointer.js';
 import { type SceneRegistry, type SceneRenderJson } from './scene.js';
 import { Stats, type StatValue } from './stats.js';
 import { GameUi } from './ui.js';
@@ -41,6 +42,7 @@ export declare class Game {
     readonly scene: THREE.Scene<THREE.Object3DEventMap>;
     readonly camera: THREE.OrthographicCamera;
     readonly input: Input;
+    readonly pointer: Pointer;
     readonly entities: Entity[];
     readonly events: Emitter;
     readonly stats: Stats;

package/dist/game.js

@@ -6,6 +6,7 @@ import { Hitbox } from './components/hitbox.js';
 import { Entity } from './entity.js';
 import { Emitter } from './events.js';
 import { Input } from './input.js';
+import { Pointer } from './pointer.js';
 import { activeRuntimeBridgeHook, EngineRuntimeBridge, } from './runtime-bridge.js';
 import { RuntimeInspector } from './runtime-inspection.js';
 import { projectIsometric } from './projection.js';
@@ -21,6 +22,7 @@ export class Game {
     scene = new THREE.Scene();
     camera;
     input;
+    pointer;
     entities = [];
     events = new Emitter();
     stats;
@@ -58,6 +60,12 @@ export class Game {
         this.scene.background = new THREE.Color(background);
         this.camera = new THREE.OrthographicCamera();
         this.camera.position.z = 10;
+        this.pointer = new Pointer(canvas, {
+            camera: this.camera,
+            resolution: this.resolution,
+            projection: () => this.sceneProjection,
+            entities: this.entities,
+        });
         this.resize();
         this.resizeObserver = new ResizeObserver(() => this.resize());
         this.resizeObserver.observe(canvas);
@@ -162,6 +170,9 @@ export class Game {
                     availableActions: () => this.input.availableActions(),
                     heldActions: () => this.input.heldActions(),
                     inspect: (metadata, filters) => inspector.snapshot(metadata, filters),
+                    click: (x, y) => {
+                        this.pointer.injectClick(x, y);
+                    },
                 });
                 activation.register(this.runtimeBridge);
                 window.addEventListener('pagehide', this.unregisterRuntimeBridge);
@@ -197,6 +208,7 @@ export class Game {
         this.stop();
         this.unregisterRuntimeBridge();
         this.input.dispose();
+        this.pointer.dispose();
         this.resizeObserver.disconnect();
         this.ui.dispose();
         for (const entity of [...this.entities])

package/dist/index.d.ts

@@ -20,7 +20,9 @@ export { resolveComponentUpdateSchedule } from './component-update-schedule.js';
 export type { ComponentUpdateCycleIssue, ComponentUpdateRegistry, ComponentUpdateScheduleIssue, ComponentUpdateScheduleResult, DuplicateComponentUpdateIssue, InvalidComponentUpdateConstraintIssue, InvalidComponentUpdateSchedule, InvalidUpdateConstraintReason, ValidComponentUpdateSchedule, } from './component-update-schedule.js';
 export { Input, DEFAULT_BINDINGS } from './input.js';
 export type { ActionName, InjectedActionOperation, InputBindings } from './input.js';
-export { RUNTIME_BRIDGE_PROTOCOL_VERSION, RUNTIME_BRIDGE_SYMBOL, RuntimeBridgeOperationError, } from './runtime-bridge.js';
+export { Pointer } from './pointer.js';
+export type { PointerCamera, PointerDeps, PointerPick, PointerResolution } from './pointer.js';
+export { RUNTIME_BRIDGE_CAPABILITIES, RUNTIME_BRIDGE_PROTOCOL_VERSION, RUNTIME_BRIDGE_SYMBOL, RuntimeBridgeOperationError, } from './runtime-bridge.js';
 export type { RuntimeBridge, RuntimeBridgeActivation, RuntimeControlRequest, RuntimeControlResult, RuntimeMetadata, RuntimeMode, } from './runtime-bridge.js';
 export { RUNTIME_PROJECTION_LIMITS } from './runtime-inspection.js';
 export type { ProjectedValue, ProjectionIssue, ProjectionMarker, ProjectionMarkerKind, RuntimeComponentSnapshot, RuntimeEntitySnapshot, RuntimeSnapshot, RuntimeSnapshotFilters, RuntimeTransformSnapshot, } from './runtime-inspection.js';

package/dist/index.js

@@ -10,7 +10,8 @@ export { authoringDefaults } from './authoring-defaults.js';
 export { collectModuleComponents, mergeRegistryComponents } from './component-registry.js';
 export { resolveComponentUpdateSchedule } from './component-update-schedule.js';
 export { Input, DEFAULT_BINDINGS } from './input.js';
-export { RUNTIME_BRIDGE_PROTOCOL_VERSION, RUNTIME_BRIDGE_SYMBOL, RuntimeBridgeOperationError, } from './runtime-bridge.js';
+export { Pointer } from './pointer.js';
+export { RUNTIME_BRIDGE_CAPABILITIES, RUNTIME_BRIDGE_PROTOCOL_VERSION, RUNTIME_BRIDGE_SYMBOL, RuntimeBridgeOperationError, } from './runtime-bridge.js';
 export { RUNTIME_PROJECTION_LIMITS } from './runtime-inspection.js';
 export { Stats } from './stats.js';
 export { GameUi } from './ui.js';

package/dist/pointer.d.ts

@@ -0,0 +1,71 @@
+import type { Entity } from './entity.js';
+import { type ProjectedPoint } from './projection.js';
+/** Fixed-resolution letterbox target; a duck-typed subset of GameResolution. */
+export interface PointerResolution {
+    width: number;
+    height: number;
+}
+/** The orthographic camera state a Pointer needs; a duck-typed THREE.OrthographicCamera. */
+export interface PointerCamera {
+    position: {
+        x: number;
+        y: number;
+    };
+    left: number;
+    right: number;
+    top: number;
+    bottom: number;
+}
+export interface PointerDeps {
+    camera: PointerCamera;
+    /** Fixed resolution (letterbox target), or null to fill the canvas. */
+    resolution: PointerResolution | null;
+    /** The scene's active render projection, read live. */
+    projection: () => 'isometric' | null;
+    /** Live entity list — read at pick time, so later spawns are visible. */
+    entities: readonly Entity[];
+}
+/** One resolved click: the logical-space point, plus the entity picked there (if any). */
+export interface PointerPick {
+    readonly point: ProjectedPoint;
+    readonly entity: Entity | null;
+}
+/**
+ * Engine-owned pointer primitive (ADR-0010): the only place a click/tap on
+ * the game canvas is read. Converts a real `pointerdown` into a logical-space
+ * point (camera, letterbox, isometric unprojection) plus the entity picked
+ * there — resolved against declared sprite bounds (width/height/offset/anchor
+ * at the entity's projected position), y-sort breaking ties front-most wins —
+ * and queues it as one pending click for a consumer (ClickToMove) to drain.
+ * The Runtime Bridge injects a click through the same resolution, in logical
+ * coordinates, via injectClick.
+ */
+export declare class Pointer {
+    private readonly canvas;
+    private readonly deps;
+    private pending;
+    constructor(canvas: HTMLCanvasElement, deps: PointerDeps);
+    dispose(): void;
+    /**
+     * Consumes and clears the pending click, if any. A consumer (the grid
+     * player role's update) drains this once per simulated frame, so a click
+     * queued while paused takes effect on the next stepped frame.
+     */
+    takePending(): PointerPick | null;
+    /**
+     * Programmatic click injection (Runtime Bridge CA-10), in logical
+     * coordinates — resolved through the exact same picking a real click uses.
+     */
+    injectClick(x: number, y: number): PointerPick;
+    private handlePointerDown;
+    private letterboxRect;
+    private toRenderPoint;
+    private resolveRenderPoint;
+    /**
+     * The entity whose projected sprite bounds contain the render-space point,
+     * front-most under y-sort winning ties (ADR-0010, CA-1). Ignores current
+     * animation frame and mirroring: picking is scoped to the declared
+     * width/height/offset/anchor box, not the momentary displayed frame.
+     */
+    private pickEntity;
+}

package/dist/pointer.js

@@ -0,0 +1,162 @@
+import { projectIsometric, unprojectIsometric } from './projection.js';
+import { ySortZ } from './render-sort.js';
+import { AnimatedSprite } from './components/animated-sprite.js';
+import { Sprite } from './components/sprite.js';
+import { spritePlacement } from './sprite-placement.js';
+function spriteBoxOf(component) {
+    if (!(component instanceof Sprite) && !(component instanceof AnimatedSprite))
+        return null;
+    return {
+        width: component.width,
+        height: component.height,
+        offsetX: component.offsetX,
+        offsetY: component.offsetY,
+        anchorX: component.anchorX,
+        anchorY: component.anchorY,
+        layer: component.layer,
+    };
+}
+/**
+ * Engine-owned pointer primitive (ADR-0010): the only place a click/tap on
+ * the game canvas is read. Converts a real `pointerdown` into a logical-space
+ * point (camera, letterbox, isometric unprojection) plus the entity picked
+ * there — resolved against declared sprite bounds (width/height/offset/anchor
+ * at the entity's projected position), y-sort breaking ties front-most wins —
+ * and queues it as one pending click for a consumer (ClickToMove) to drain.
+ * The Runtime Bridge injects a click through the same resolution, in logical
+ * coordinates, via injectClick.
+ */
+export class Pointer {
+    canvas;
+    deps;
+    pending = null;
+    constructor(canvas, deps) {
+        this.canvas = canvas;
+        this.deps = deps;
+        this.canvas.addEventListener('pointerdown', this.handlePointerDown);
+    }
+    dispose() {
+        this.canvas.removeEventListener('pointerdown', this.handlePointerDown);
+        this.pending = null;
+    }
+    /**
+     * Consumes and clears the pending click, if any. A consumer (the grid
+     * player role's update) drains this once per simulated frame, so a click
+     * queued while paused takes effect on the next stepped frame.
+     */
+    takePending() {
+        const pick = this.pending;
+        this.pending = null;
+        return pick;
+    }
+    /**
+     * Programmatic click injection (Runtime Bridge CA-10), in logical
+     * coordinates — resolved through the exact same picking a real click uses.
+     */
+    injectClick(x, y) {
+        const renderPoint = this.toRenderPoint(x, y);
+        const pick = this.resolveRenderPoint(renderPoint.x, renderPoint.y);
+        this.pending = pick;
+        return pick;
+    }
+    handlePointerDown = (event) => {
+        // Primary button only; a touch tap reports the same button (ADR-0010).
+        if (event.button !== 0)
+            return;
+        const w = this.canvas.clientWidth;
+        const h = this.canvas.clientHeight;
+        if (w <= 0 || h <= 0)
+            return;
+        const { vx, vy, vw, vh } = this.letterboxRect(w, h);
+        if (vw <= 0 || vh <= 0)
+            return;
+        const rect = this.canvas.getBoundingClientRect();
+        const px = event.clientX - rect.left;
+        const py = event.clientY - rect.top;
+        const nx = (px - vx) / vw;
+        const ny = (py - vy) / vh;
+        // Outside the visible viewport (a letterbox bar): not a click on the world.
+        if (nx < 0 || nx > 1 || ny < 0 || ny > 1)
+            return;
+        const camera = this.deps.camera;
+        const renderX = camera.position.x + camera.left + nx * (camera.right - camera.left);
+        const renderY = camera.position.y + camera.top - ny * (camera.top - camera.bottom);
+        this.pending = this.resolveRenderPoint(renderX, renderY);
+    };
+    letterboxRect(w, h) {
+        const resolution = this.deps.resolution;
+        if (!resolution)
+            return { vx: 0, vy: 0, vw: w, vh: h };
+        const aspect = resolution.width / resolution.height;
+        const vw = Math.min(w, h * aspect);
+        const vh = vw / aspect;
+        return { vx: (w - vw) / 2, vy: (h - vh) / 2, vw, vh };
+    }
+    toRenderPoint(logicalX, logicalY) {
+        return this.deps.projection() === 'isometric'
+            ? projectIsometric(logicalX, logicalY)
+            : { x: logicalX, y: logicalY };
+    }
+    resolveRenderPoint(renderX, renderY) {
+        const point = this.deps.projection() === 'isometric'
+            ? unprojectIsometric(renderX, renderY)
+            : { x: renderX, y: renderY };
+        return { point, entity: this.pickEntity(renderX, renderY) };
+    }
+    /**
+     * The entity whose projected sprite bounds contain the render-space point,
+     * front-most under y-sort winning ties (ADR-0010, CA-1). Ignores current
+     * animation frame and mirroring: picking is scoped to the declared
+     * width/height/offset/anchor box, not the momentary displayed frame.
+     */
+    pickEntity(renderX, renderY) {
+        const hits = [];
+        for (const entity of this.deps.entities) {
+            if (!entity.alive)
+                continue;
+            for (const component of entity.components) {
+                const box = spriteBoxOf(component);
+                if (!box)
+                    continue;
+                const anchor = this.deps.projection() === 'isometric'
+                    ? projectIsometric(entity.position.x, entity.position.y)
+                    : { x: entity.position.x, y: entity.position.y };
+                const placement = spritePlacement({
+                    width: box.width,
+                    height: box.height,
+                    offsetX: box.offsetX,
+                    offsetY: box.offsetY,
+                    anchorX: box.anchorX,
+                    anchorY: box.anchorY,
+                    flipX: false,
+                    frameScaleX: 1,
+                    frameScaleY: 1,
+                });
+                const halfW = Math.abs(placement.scaleX) / 2;
+                const halfH = Math.abs(placement.scaleY) / 2;
+                const centerX = anchor.x + placement.x;
+                const centerY = anchor.y + placement.y;
+                if (renderX >= centerX - halfW &&
+                    renderX <= centerX + halfW &&
+                    renderY >= centerY - halfH &&
+                    renderY <= centerY + halfH) {
+                    // Matches Game.applyYSort's key exactly: the entity's node
+                    // position, which for an isometric scene is the projected Y (the
+                    // same `anchor.y` just used to place this box), not the logical one.
+                    hits.push({ entity, layer: box.layer, y: anchor.y });
+                    break;
+                }
+            }
+        }
+        if (hits.length === 0)
+            return null;
+        if (hits.length === 1)
+            return hits[0].entity;
+        const z = ySortZ(hits.map((h) => ({ layer: h.layer, y: h.y })));
+        let bestIndex = 0;
+        for (let i = 1; i < hits.length; i += 1)
+            if (z[i] > z[bestIndex])
+                bestIndex = i;
+        return hits[bestIndex].entity;
+    }
+}

package/dist/runtime-bridge.d.ts

@@ -2,12 +2,23 @@ import type { RuntimeSnapshot, RuntimeSnapshotFilters } from './runtime-inspecti
 export declare const RUNTIME_BRIDGE_PROTOCOL_VERSION: 1;
 export declare const RUNTIME_BRIDGE_SYMBOL: unique symbol;
 export type RuntimeMode = 'paused' | 'real-time';
+/**
+ * Operations this build's control() actually implements, beyond the
+ * baseline protocol 1 set (press/hold/release/pause/resume/step) every
+ * bridge has always supported. Additive metadata, not a protocol bump: a
+ * pre-CA-10 engine simply lacks this field, which is exactly what callers
+ * gating on capabilities check for (review finding #4) — protocol 1 alone
+ * doesn't distinguish an engine that silently no-ops an unknown operation
+ * from one that runs it.
+ */
+export declare const RUNTIME_BRIDGE_CAPABILITIES: readonly ['click'];
 export interface RuntimeMetadata {
     bridgeVersion: typeof RUNTIME_BRIDGE_PROTOCOL_VERSION;
     engineVersion: string;
     mode: RuntimeMode;
     frame: number;
     simulationTime: number;
+    capabilities: readonly string[];
 }
 export type RuntimeControlRequest = {
     operation: 'press' | 'hold' | 'release';
@@ -18,6 +29,10 @@ export type RuntimeControlRequest = {
     operation: 'step';
     dt?: number;
     frames?: number;
+} | {
+    operation: 'click';
+    x: number;
+    y: number;
 };
 export interface RuntimeControlResult extends RuntimeMetadata {
     heldActions: string[];
@@ -50,6 +65,7 @@ export interface RuntimeBridgeHost {
     availableActions(): string[];
     heldActions(): string[];
     inspect(metadata: RuntimeMetadata, filters?: RuntimeSnapshotFilters): RuntimeSnapshot;
+    click(x: number, y: number): void;
 }
 export declare class EngineRuntimeBridge implements RuntimeBridge {
     readonly surface: HTMLCanvasElement;

package/dist/runtime-bridge.js

@@ -1,6 +1,16 @@
 import enginePackage from '../package.json' with { type: 'json' };
 export const RUNTIME_BRIDGE_PROTOCOL_VERSION = 1;
 export const RUNTIME_BRIDGE_SYMBOL = Symbol.for('@waica/runtime-bridge/v1');
+/**
+ * Operations this build's control() actually implements, beyond the
+ * baseline protocol 1 set (press/hold/release/pause/resume/step) every
+ * bridge has always supported. Additive metadata, not a protocol bump: a
+ * pre-CA-10 engine simply lacks this field, which is exactly what callers
+ * gating on capabilities check for (review finding #4) — protocol 1 alone
+ * doesn't distinguish an engine that silently no-ops an unknown operation
+ * from one that runs it.
+ */
+export const RUNTIME_BRIDGE_CAPABILITIES = ['click'];
 export class RuntimeBridgeOperationError extends Error {
     code;
     availableActions;
@@ -45,6 +55,7 @@ export class EngineRuntimeBridge {
             mode: this.mode,
             frame: this.frame,
             simulationTime: this.simulationTime,
+            capabilities: RUNTIME_BRIDGE_CAPABILITIES,
         };
     }
     inspect(filters = {}) {
@@ -88,6 +99,17 @@ export class EngineRuntimeBridge {
                     this.advance(dt);
                 break;
             }
+            case 'click': {
+                if (!Number.isFinite(request.x) || !Number.isFinite(request.y)) {
+                    throw new RuntimeBridgeOperationError('runtime-operation-failed', 'x and y must be finite numbers.');
+                }
+                this.host.click(request.x, request.y);
+                break;
+            }
+            default: {
+                const unsupported = request;
+                throw new RuntimeBridgeOperationError('runtime-operation-failed', `Unsupported runtime control operation "${unsupported.operation}".`);
+            }
         }
         return { ...this.metadata(), heldActions: this.host.heldActions() };
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@waica/engine",
-  "version": "0.9.1",
+  "version": "0.11.0",
   "description": "Waica game engine core — archetype-driven, web-first, 2D & 3D",
   "license": "MIT",
   "type": "module",