@haiyue/extensions 0.1.0 → 0.2.0

package/dist/controls.js

@@ -0,0 +1,358 @@
+import { System } from '@haiyue/engine/ecs';
+import { CartesianTransform3D, Transform2D } from '@haiyue/engine/components';
+import { EventEmitter } from '@haiyue/engine/core';
+import { GuiElement } from '@haiyue/engine/gui';
+
+class Disc extends GuiElement {
+    constructor(style) { super({ disabled: true, style }); }
+    layout() { }
+    place(x, y, radius) {
+        if (this.rect.x === x - radius && this.rect.y === y - radius && this.rect.width === radius * 2)
+            return;
+        this.rect = { x: x - radius, y: y - radius, width: radius * 2, height: radius * 2 };
+        this.markDirty(2 /* GuiDirtyFlags.Visual */);
+    }
+}
+/** Presentation only: never intercepts pointers or creates another render loop. */
+class JoystickView {
+    base;
+    knob;
+    constructor(root, baseStyle, knobStyle) {
+        this.base = root.add(new Disc({ backgroundColor: '#18334b99', borderColor: '#6aadd5aa', ...baseStyle }));
+        this.knob = root.add(new Disc({ backgroundColor: '#82d9f4dd', borderColor: '#d9f6ff', ...knobStyle }));
+    }
+    update(state, maxDistance, knobRadius, visible) {
+        this.base.setVisible(visible);
+        this.knob.setVisible(visible);
+        this.base.style.radius = maxDistance + knobRadius;
+        this.knob.style.radius = knobRadius;
+        this.base.place(state.center.x, state.center.y, maxDistance + knobRadius);
+        this.knob.place(state.center.x + state.offset.x, state.center.y + state.offset.y, knobRadius);
+    }
+    destroy() {
+        this.base.parent?.remove(this.base);
+        this.knob.parent?.remove(this.knob);
+    }
+}
+
+const DEFAULT_CENTER = ({ width, height }) => ({
+    x: Math.min(110, width / 4), y: height - Math.min(110, height / 4),
+});
+const DEFAULT_REGION = ({ width, height }) => ({
+    x: 0, y: height / 2, width: width / 2, height: height / 2,
+});
+/**
+ * Single-owner multitouch joystick. Add as a non-render System, or call step(dtMs)
+ * exactly once per frame. Set touch-action:none on the browser input surface.
+ * The supplied target is moved in parent-local coordinates without collision solving.
+ */
+class VirtualJoystickControls extends System {
+    events = new EventEmitter();
+    surface;
+    document;
+    window;
+    options;
+    view = null;
+    pointerId = null;
+    center = { x: 0, y: 0 };
+    point = { x: 0, y: 0 };
+    bounds = '';
+    disposed = false;
+    constructor(surface, options = {}) {
+        super(() => false);
+        this.name = 'VirtualJoystickControls';
+        this.priority = -100;
+        this.surface = surface;
+        this.document = surface.ownerDocument ?? null;
+        this.window = this.document?.defaultView ?? null;
+        this.options = normalize(options);
+        this.refreshLayout();
+        this.createView();
+        surface.addEventListener('pointerdown', this.onDown, { passive: false });
+        surface.addEventListener('pointermove', this.onMove, { passive: false });
+        surface.addEventListener('pointerup', this.onUp);
+        surface.addEventListener('pointercancel', this.onCancel);
+        surface.addEventListener('lostpointercapture', this.onCancel);
+        this.window?.addEventListener('blur', this.onBlur);
+        // Also handles a release outside a surface without native pointer capture.
+        this.window?.addEventListener('pointerup', this.onUp);
+        this.window?.addEventListener('pointercancel', this.onCancel);
+        this.document?.addEventListener('visibilitychange', this.onVisibility);
+    }
+    get disabled() { return super.disabled; }
+    set disabled(value) {
+        super.disabled = value;
+        // System's constructor invokes this setter before subclass fields exist.
+        if (this.surface) {
+            if (value)
+                this.cancel();
+            this.updateView();
+        }
+    }
+    /** Retainable immutable snapshot; caller mutation cannot alter future movement. */
+    get state() {
+        const active = this.pointerId !== null;
+        const dx = active ? this.point.x - this.center.x : 0;
+        const dy = active ? this.point.y - this.center.y : 0;
+        const rawDistance = Math.hypot(dx, dy);
+        const distance = Math.min(rawDistance, this.options.maxDistance);
+        const ratio = distance / this.options.maxDistance;
+        const strength = Math.max(0, (ratio - this.options.deadZone) / (1 - this.options.deadZone));
+        const unitX = rawDistance > 0 ? dx / rawDistance : 0;
+        const unitY = rawDistance > 0 ? dy / rawDistance : 0;
+        return Object.freeze({
+            active, pointerId: this.pointerId, center: Object.freeze({ ...this.center }),
+            direction: Object.freeze({ x: strength > 0 ? unitX : 0, y: strength > 0 ? unitY : 0 }),
+            offset: Object.freeze({ x: unitX * distance, y: unitY * distance }),
+            rawDistance, distance, strength, angle: strength > 0 ? Math.atan2(dy, dx) : 0,
+        });
+    }
+    /** Atomic parameter update. A valid update cancels the current gesture. */
+    configure(options) {
+        if (this.disposed)
+            return this;
+        const next = normalize({ ...this.options, ...options });
+        const viewport = this.surface.getBoundingClientRect();
+        resolvePoint(next.center, viewport);
+        resolveRegion(next.region, viewport);
+        this.cancel();
+        this.options = next;
+        this.refreshLayout();
+        this.createView();
+        return this;
+    }
+    /** Cancel from native suspend/unload hooks; idempotent, returns thumb to center. */
+    cancel() { this.finish('cancel'); return this; }
+    /** Delta is milliseconds, matching World.update(). No internal RAF or timer. */
+    step(deltaMilliseconds) {
+        nonNegative(deltaMilliseconds, 'deltaMilliseconds');
+        if (this.disposed || this.disabled)
+            return this;
+        this.refreshLayout();
+        const state = this.state;
+        const deltaSeconds = deltaMilliseconds / 1000;
+        const movementDeltaSeconds = Math.min(deltaMilliseconds, this.options.maxDeltaMilliseconds) / 1000;
+        this.moveTarget(state, movementDeltaSeconds);
+        this.updateView(state);
+        this.events.emit('frame', { detail: Object.freeze({ ...state, deltaMilliseconds, deltaSeconds, movementDeltaSeconds }) });
+        return this;
+    }
+    update(_world, _time, delta) {
+        // The first RAF timestamp can precede FrameLoop.start()'s performance.now().
+        // A clock-origin adjustment must never abort rendering or move a character backwards.
+        return this.step(Math.max(0, delta));
+    }
+    destroy() {
+        if (this.disposed)
+            return this;
+        this.disposed = true;
+        // Teardown is completed even if a consumer's cancel callback throws.
+        try {
+            this.cancel();
+        }
+        finally {
+            this.surface.removeEventListener('pointerdown', this.onDown);
+            this.surface.removeEventListener('pointermove', this.onMove);
+            this.surface.removeEventListener('pointerup', this.onUp);
+            this.surface.removeEventListener('pointercancel', this.onCancel);
+            this.surface.removeEventListener('lostpointercapture', this.onCancel);
+            this.window?.removeEventListener('blur', this.onBlur);
+            this.window?.removeEventListener('pointerup', this.onUp);
+            this.window?.removeEventListener('pointercancel', this.onCancel);
+            this.document?.removeEventListener('visibilitychange', this.onVisibility);
+            this.view?.destroy();
+            this.view = null;
+            this.events.removeAllListeners();
+            super.destroy();
+        }
+        return this;
+    }
+    refreshLayout() {
+        const rect = this.surface.getBoundingClientRect();
+        const key = `${rect.left}:${rect.top}:${rect.width}:${rect.height}`;
+        if (this.bounds && this.bounds !== key)
+            this.cancel();
+        this.bounds = key;
+        if (this.pointerId === null) {
+            const viewport = { width: rect.width, height: rect.height };
+            this.center = resolvePoint(this.options.center, viewport);
+        }
+    }
+    createView() {
+        this.view?.destroy();
+        this.view = this.options.guiRoot
+            ? new JoystickView(this.options.guiRoot, this.options.baseStyle, this.options.knobStyle) : null;
+        this.updateView();
+    }
+    updateView(state = this.state) {
+        this.view?.update(state, this.options.maxDistance, this.options.knobRadius, !this.disabled && !this.disposed && (state.active || (this.options.mode === 'fixed' && this.options.showIdle)));
+    }
+    local(event) {
+        if (!Number.isFinite(event.clientX) || !Number.isFinite(event.clientY))
+            return null;
+        const rect = this.surface.getBoundingClientRect();
+        return { x: event.clientX - rect.left, y: event.clientY - rect.top };
+    }
+    onDown = (native) => {
+        const event = native;
+        // GuiSystem prevents browser scrolling on all canvas pointers. That is not an
+        // input-ownership claim: use region/shouldActivate to arbitrate game input.
+        if (this.disposed || this.disabled || this.pointerId !== null
+            || (event.button !== undefined && event.button !== 0))
+            return;
+        this.refreshLayout();
+        const point = this.local(event);
+        if (!point || !Number.isFinite(event.pointerId))
+            return;
+        const rect = this.surface.getBoundingClientRect();
+        const region = resolveRegion(this.options.region, rect);
+        if (point.x < 0 || point.y < 0 || point.x > rect.width || point.y > rect.height
+            || point.x < region.x || point.y < region.y || point.x > region.x + region.width || point.y > region.y + region.height)
+            return;
+        if (this.options.mode === 'fixed' && Math.hypot(point.x - this.center.x, point.y - this.center.y)
+            > (this.options.activationRadius ?? this.options.maxDistance + this.options.knobRadius))
+            return;
+        if (this.options.shouldActivate?.(point, event) === false)
+            return;
+        if (this.options.mode === 'floating')
+            this.center = { ...point };
+        this.point = point;
+        this.pointerId = event.pointerId;
+        try {
+            this.surface.setPointerCapture?.(event.pointerId);
+        }
+        catch { /* Synthetic/host pointers may not support capture. */ }
+        event.preventDefault();
+        this.updateView();
+        this.events.emit('start', { detail: this.state });
+    };
+    onMove = (native) => {
+        const event = native;
+        if (this.pointerId === null || event.pointerId !== this.pointerId)
+            return;
+        this.refreshLayout();
+        if (this.pointerId === null)
+            return;
+        const point = this.local(event);
+        if (point)
+            this.point = point;
+        event.preventDefault();
+    };
+    onUp = (event) => {
+        if (this.pointerId !== null && event.pointerId === this.pointerId)
+            this.finish('end');
+    };
+    onCancel = (event) => {
+        if (this.pointerId !== null && event.pointerId === this.pointerId)
+            this.cancel();
+    };
+    onBlur = () => { this.cancel(); };
+    onVisibility = () => { if (this.document?.hidden)
+        this.cancel(); };
+    finish(type) {
+        const id = this.pointerId;
+        if (id === null)
+            return;
+        this.pointerId = null;
+        this.point = { ...this.center };
+        try {
+            this.surface.releasePointerCapture?.(id);
+        }
+        catch { /* Capture may already be lost. */ }
+        this.updateView();
+        this.events.emit(type, { detail: this.state });
+    }
+    moveTarget(state, dt) {
+        const { target, plane, moveSpeed, analog, rotateToDirection, rotationOffset, turnSpeed, movementRotation } = this.options;
+        if (!target || target.destroyed || target.disabled || state.strength === 0 || dt === 0)
+            return;
+        const c = Math.cos(movementRotation), s = Math.sin(movementRotation);
+        const dx = state.direction.x, dy = state.direction.y;
+        const amount = moveSpeed * dt * (analog ? state.strength : 1);
+        if (plane === 'xz') {
+            const transform = target.getComponent(CartesianTransform3D);
+            if (!transform || transform.disabled)
+                return;
+            const x = c * dx + s * dy, z = -s * dx + c * dy;
+            const p = transform.position, r = transform.rotation;
+            transform.setPosition(p[0] + x * amount, p[1], p[2] + z * amount);
+            if (rotateToDirection)
+                transform.setRotation(r[0], turn(r[1], Math.atan2(-x, -z) + rotationOffset, turnSpeed * dt), r[2]);
+        }
+        else {
+            const transform = target.getComponent(Transform2D);
+            if (!transform || transform.disabled)
+                return;
+            const x = c * dx + s * dy, y = s * dx - c * dy;
+            transform.setPosition(transform.x + x * amount, transform.y + y * amount);
+            if (rotateToDirection)
+                transform.rotation = turn(transform.rotation, Math.atan2(y, x) + rotationOffset, turnSpeed * dt);
+        }
+    }
+}
+function turn(current, desired, max) {
+    const difference = Math.atan2(Math.sin(desired - current), Math.cos(desired - current));
+    return current + Math.max(-max, Math.min(max, difference));
+}
+function nonNegative(value, name) {
+    if (!Number.isFinite(value) || value < 0)
+        throw new RangeError(`VirtualJoystickControls ${name} must be finite and non-negative.`);
+    return value;
+}
+function positive(value, name) {
+    nonNegative(value, name);
+    if (value === 0)
+        throw new RangeError(`VirtualJoystickControls ${name} must be positive.`);
+    return value;
+}
+function finite(value, name) {
+    if (!Number.isFinite(value))
+        throw new RangeError(`VirtualJoystickControls ${name} must be finite.`);
+    return value;
+}
+function resolvePoint(value, viewport) {
+    const p = typeof value === 'function' ? value(viewport) : value;
+    return { x: finite(p.x, 'center.x'), y: finite(p.y, 'center.y') };
+}
+function resolveRegion(value, viewport) {
+    const r = typeof value === 'function' ? value(viewport) : value;
+    return { x: finite(r.x, 'region.x'), y: finite(r.y, 'region.y'),
+        width: nonNegative(r.width, 'region.width'), height: nonNegative(r.height, 'region.height') };
+}
+function normalize(input) {
+    const mode = input.mode ?? 'floating', plane = input.plane ?? 'xz';
+    if (mode !== 'fixed' && mode !== 'floating')
+        throw new RangeError('VirtualJoystickControls invalid mode.');
+    if (plane !== 'xz' && plane !== 'xy')
+        throw new RangeError('VirtualJoystickControls invalid plane.');
+    const deadZone = nonNegative(input.deadZone ?? 0.1, 'deadZone');
+    if (deadZone >= 1)
+        throw new RangeError('VirtualJoystickControls deadZone must be less than 1.');
+    const target = input.target ?? null;
+    if (target && (target.destroyed || !(plane === 'xz' ? target.getComponent(CartesianTransform3D) : target.getComponent(Transform2D)))) {
+        throw new TypeError(`VirtualJoystickControls target requires a live ${plane === 'xz' ? 'CartesianTransform3D' : 'Transform2D'}.`);
+    }
+    const center = input.center ?? DEFAULT_CENTER, region = input.region ?? DEFAULT_REGION;
+    if (typeof center !== 'function')
+        resolvePoint(center, { width: 0, height: 0 });
+    if (typeof region !== 'function')
+        resolveRegion(region, { width: 0, height: 0 });
+    return {
+        mode, plane, target, center: typeof center === 'function' ? center : { ...center },
+        region: typeof region === 'function' ? region : { ...region }, deadZone,
+        maxDistance: positive(input.maxDistance ?? 64, 'maxDistance'),
+        activationRadius: input.activationRadius == null ? null : positive(input.activationRadius, 'activationRadius'),
+        moveSpeed: nonNegative(input.moveSpeed ?? 4, 'moveSpeed'), analog: input.analog ?? true,
+        rotateToDirection: input.rotateToDirection ?? true,
+        turnSpeed: input.turnSpeed === Infinity || input.turnSpeed === undefined ? Infinity : nonNegative(input.turnSpeed, 'turnSpeed'),
+        rotationOffset: finite(input.rotationOffset ?? 0, 'rotationOffset'),
+        movementRotation: finite(input.movementRotation ?? 0, 'movementRotation'),
+        maxDeltaMilliseconds: positive(input.maxDeltaMilliseconds ?? 100, 'maxDeltaMilliseconds'),
+        guiRoot: input.guiRoot ?? null, knobRadius: positive(input.knobRadius ?? 24, 'knobRadius'),
+        showIdle: input.showIdle ?? true, baseStyle: { ...input.baseStyle }, knobStyle: { ...input.knobStyle },
+        ...(input.shouldActivate ? { shouldActivate: input.shouldActivate } : {}),
+    };
+}
+
+export { VirtualJoystickControls };
+//# sourceMappingURL=controls.js.map

package/dist/deformable-animation/runtime/DeformableMesh2DRuntimeExtension.d.ts

@@ -0,0 +1,11 @@
+import type { Animation2DExtensionHandler } from '../../animation/Animation2DExtensionRegistry';
+export type DeformableMesh2DRuntimeState = 'loading' | 'ready' | 'error' | 'destroyed';
+export interface DeformableMesh2DRuntimeStatus {
+    readonly state: DeformableMesh2DRuntimeState;
+    readonly drawableCount: number;
+    readonly error?: string;
+}
+export interface DeformableMesh2DRuntimeExtensionOptions {
+    readonly onStatus?: (status: DeformableMesh2DRuntimeStatus) => void;
+}
+export declare function createDeformableMesh2DRuntimeExtension(options?: DeformableMesh2DRuntimeExtensionOptions): Animation2DExtensionHandler;

package/dist/deformable-animation/runtime/DeformableMesh2DSampler.d.ts

@@ -0,0 +1,11 @@
+import type { ParsedDeformableMesh2DDrawable } from '@haiyue/animation-spec/deformable2d';
+export interface DeformableMesh2DSample {
+    readonly opacity: number;
+    readonly renderOrder: number;
+    readonly frame: number;
+    readonly nextFrame: number;
+    readonly progress: number;
+}
+export declare function sampleDeformableMesh2DDrawable(times: Float32Array, drawable: ParsedDeformableMesh2DDrawable, time: number, targetRuntimePositions: Float32Array): DeformableMesh2DSample;
+/** Samples optional HYDM 1.2 RGBA tracks into caller-owned pose storage without allocating. */
+export declare function sampleDeformableMesh2DDrawableColors(drawable: ParsedDeformableMesh2DDrawable, sample: DeformableMesh2DSample, targetMultiplyColors: Float32Array, targetScreenColors: Float32Array, targetOffset?: number): void;

package/dist/deformable-animation.d.ts

@@ -0,0 +1,5 @@
+export { createDeformableMesh2DRuntimeExtension } from './deformable-animation/runtime/DeformableMesh2DRuntimeExtension';
+export type { DeformableMesh2DRuntimeExtensionOptions, DeformableMesh2DRuntimeState, DeformableMesh2DRuntimeStatus, } from './deformable-animation/runtime/DeformableMesh2DRuntimeExtension';
+/** Low-level geometry/opacity sampler; drawable colors are populated by the reusable pose port. */
+export { sampleDeformableMesh2DDrawable } from './deformable-animation/runtime/DeformableMesh2DSampler';
+export type { DeformableMesh2DSample } from './deformable-animation/runtime/DeformableMesh2DSampler';