@haiyue/extensions 0.1.0 → 0.2.0

package/dist/chunks/{AnimationStateMachineController-BIcAh-sT.js → AnimationStateMachineController-4sKaqh9E.js}

@@ -1434,5 +1434,5 @@ function resolveTransactionalPort(port) {
     return candidate;
 }
 
-export { Animation3DStateMachineController as A, AnimationStateMachineValidationError as a, compileAnimation3DStateMachineDefinition as b, compileAnimationStateMachineDefinition as c, validateAnimation3DStateMachineDefinition as d, runAnimationStateMachineControllerUpdateTransaction as r, validateAnimationStateMachineDefinition as v };
-//# sourceMappingURL=AnimationStateMachineController-BIcAh-sT.js.map
+export { Animation3DStateMachineController as A, compileAnimationStateMachineDefinition as a, AnimationStateMachineValidationError as b, compileAnimation3DStateMachineDefinition as c, validateAnimationStateMachineDefinition as d, runAnimationStateMachineControllerUpdateTransaction as r, validateAnimation3DStateMachineDefinition as v };
+//# sourceMappingURL=AnimationStateMachineController-4sKaqh9E.js.map

package/dist/chunks/AnimationVisual2D-8y3qp0_U.js

@@ -0,0 +1,230 @@
+import { Component } from '@haiyue/engine';
+import { UniqueCheckType } from '@haiyue/engine/ecs';
+
+/** Runtime-private render item consumed by Animation2DRenderSystem. */
+class AnimationVisual2D extends Component {
+    static UniqueCheckType = UniqueCheckType.SYMBOL | UniqueCheckType.REPLACE;
+    static UniqueSymbol = Symbol.for('AnimationVisual2D');
+    geometry;
+    instanceId;
+    nodeId;
+    nodeKey;
+    order;
+    blendMode;
+    textureAlphaMode;
+    culling;
+    uvs;
+    sourceOnly;
+    compositeLayers;
+    compositeKeys;
+    /** Compatibility accessors for single-layer renderer diagnostics. */
+    compositeSource;
+    compositeKey;
+    compositeMode;
+    uvRect;
+    color;
+    multiplyColor;
+    screenColor;
+    texture;
+    textureHandle;
+    textMaterial;
+    requiresTexture;
+    gradient;
+    effects;
+    revision = 0;
+    constructor(options) {
+        super('AnimationVisual2D');
+        this.geometry = options.geometry;
+        this.instanceId = options.instanceId;
+        this.nodeId = options.nodeId;
+        this.nodeKey = `${options.instanceId}:${options.nodeId}`;
+        this.order = options.order;
+        this.blendMode = options.blendMode ?? 'normal';
+        this.textureAlphaMode = options.textureAlphaMode ?? 'straight';
+        if (options.culling !== undefined && typeof options.culling !== 'boolean') {
+            throw new AnimationVisual2DConfigurationError('E_ANIMATION_2D_CULLING_INVALID', 'AnimationVisual2D culling must be boolean when present.', '$.culling');
+        }
+        this.culling = options.culling ?? false;
+        if (options.uvs && options.uvs.length !== options.geometry.positions.length) {
+            throw new RangeError('AnimationVisual2D explicit UV count must match geometry positions.');
+        }
+        this.uvs = options.uvs ?? null;
+        this.sourceOnly = options.sourceOnly ?? false;
+        this.compositeLayers = Object.freeze(options.composite
+            ? ('layers' in options.composite
+                ? options.composite.layers.map(layer => ({ ...layer }))
+                : [{ ...options.composite }])
+            : []);
+        this.compositeKeys = Object.freeze(this.compositeLayers.map(layer => `${options.instanceId}:${layer.source}`));
+        this.compositeSource = this.compositeLayers[0]?.source;
+        this.compositeKey = this.compositeKeys[0];
+        this.compositeMode = this.compositeLayers[0]?.mode;
+        this.uvRect = [...(options.uvRect ?? [0, 0, 1, 1])];
+        this.color = [...options.color];
+        this.multiplyColor = drawableColor(options.multiplyColor ?? [1, 1, 1, 1], 'multiplyColor');
+        this.screenColor = drawableColor(options.screenColor ?? [0, 0, 0, 0], 'screenColor');
+        this.texture = options.texture ?? null;
+        this.textureHandle = options.textureHandle ?? null;
+        this.textMaterial = options.textMaterial ?? null;
+        this.requiresTexture = options.requiresTexture ?? false;
+        this.gradient = options.gradient ?? null;
+        this.effects = Object.freeze(options.effects ? [...options.effects] : []);
+    }
+    setTexture(texture) {
+        if (this.texture === texture)
+            return;
+        this.texture = texture;
+        this.revision++;
+    }
+    setOrder(order) {
+        if (!Number.isSafeInteger(order))
+            throw new RangeError('AnimationVisual2D order must be a safe integer.');
+        this.order = order;
+    }
+    setTextureHandle(handle) {
+        if (this.textureHandle === handle)
+            return;
+        this.textureHandle = handle;
+        this.revision++;
+    }
+    setUvRect(value) {
+        if (this.uvRect.every((current, index) => current === value[index]))
+            return;
+        this.uvRect[0] = value[0];
+        this.uvRect[1] = value[1];
+        this.uvRect[2] = value[2];
+        this.uvRect[3] = value[3];
+        this.revision++;
+    }
+    /** Updates caller-owned drawable color state without replacing visual or GPU owners. */
+    setDrawableColors(multiplyColor, screenColor) {
+        assertDrawableColor(multiplyColor, 'multiplyColor');
+        assertDrawableColor(screenColor, 'screenColor');
+        let changed = false;
+        for (let index = 0; index < 4; index++) {
+            if (this.multiplyColor[index] !== multiplyColor[index]) {
+                this.multiplyColor[index] = multiplyColor[index];
+                changed = true;
+            }
+            if (this.screenColor[index] !== screenColor[index]) {
+                this.screenColor[index] = screenColor[index];
+                changed = true;
+            }
+        }
+        if (changed)
+            this.revision++;
+    }
+    setCompositeExpansion(index, value) {
+        const layer = this.compositeLayers[index];
+        if (!layer || layer.expansion === value)
+            return;
+        layer.expansion = value;
+        this.revision++;
+    }
+    resolveTexture() {
+        if (!this.textureHandle)
+            return this.texture;
+        try {
+            return this.textureHandle.value;
+        }
+        catch {
+            return null;
+        }
+    }
+    clone() {
+        return new AnimationVisual2D({
+            geometry: this.geometry,
+            color: this.color,
+            multiplyColor: this.multiplyColor,
+            screenColor: this.screenColor,
+            instanceId: this.instanceId,
+            nodeId: this.nodeId,
+            order: this.order,
+            blendMode: this.blendMode,
+            textureAlphaMode: this.textureAlphaMode,
+            culling: this.culling,
+            ...(this.uvs ? { uvs: this.uvs } : {}),
+            sourceOnly: this.sourceOnly,
+            ...(this.compositeLayers.length === 0 ? {} : { composite: { layers: this.compositeLayers } }),
+            texture: this.texture,
+            textureHandle: this.textureHandle,
+            textMaterial: this.textMaterial,
+            requiresTexture: this.requiresTexture,
+            uvRect: this.uvRect,
+            gradient: this.gradient ? {
+                kind: this.gradient.kind,
+                start: [...this.gradient.start],
+                end: [...this.gradient.end],
+                stops: new Float32Array(this.gradient.stops),
+                opacity: this.gradient.opacity,
+            } : null,
+            effects: this.effects.map(effect => ({ kind: effect.kind, values: new Float32Array(effect.values) })),
+        });
+    }
+}
+class AnimationVisual2DConfigurationError extends TypeError {
+    code;
+    path;
+    constructor(code, message, path) {
+        super(message);
+        this.code = code;
+        this.path = path;
+        this.name = 'AnimationVisual2DConfigurationError';
+    }
+}
+function drawableColor(value, kind) {
+    assertDrawableColor(value, kind);
+    return [value[0], value[1], value[2], value[3]];
+}
+function assertDrawableColor(value, kind) {
+    let valid = value.length === 4;
+    for (let index = 0; valid && index < 4; index++) {
+        const channel = value[index];
+        valid = Number.isFinite(channel) && channel >= 0 && channel <= 1;
+    }
+    if (valid)
+        return;
+    if (kind === 'multiplyColor' || kind === 'screenColor') {
+        throw new AnimationVisual2DConfigurationError(kind === 'multiplyColor' ? 'E_ANIMATION_2D_MULTIPLY_COLOR_INVALID' : 'E_ANIMATION_2D_SCREEN_COLOR_INVALID', `AnimationVisual2D ${kind} must contain four finite values within [0, 1].`, `$.${kind}`);
+    }
+    throw new RangeError(`Animation drawable ${kind} must contain four finite values within [0, 1].`);
+}
+class Animation2DPipelineCreationError extends Error {
+    pipelineKey;
+    cause;
+    code = 'E_ANIMATION_2D_PIPELINE_CREATION_FAILED';
+    path = '$runtime.animation2D.pipeline';
+    constructor(pipelineKey, cause) {
+        super(`Animation2D render pipeline creation failed for ${pipelineKey}.`);
+        this.pipelineKey = pipelineKey;
+        this.cause = cause;
+        this.name = 'Animation2DPipelineCreationError';
+    }
+}
+function createAnimation2DPipeline(pipelineKey, create) {
+    try {
+        return create();
+    }
+    catch (cause) {
+        throw new Animation2DPipelineCreationError(pipelineKey, cause);
+    }
+}
+/**
+ * Source-neutral 2D front faces are CCW in clip space. WebGPU normalizes the
+ * viewport convention for front-face classification; callers must not add an
+ * extra framebuffer-Y inversion. Real model/world reflections still reverse it.
+ */
+const ANIMATION_2D_WEBGPU_FRONT_FACE = 'ccw';
+function animation2DCullingPrimitive(culling) {
+    return {
+        topology: 'triangle-list',
+        frontFace: ANIMATION_2D_WEBGPU_FRONT_FACE,
+        cullMode: culling ? 'back' : 'none',
+    };
+}
+function animation2DCullingPipelineKey(culling) {
+    return culling ? `back:${ANIMATION_2D_WEBGPU_FRONT_FACE}` : `none:${ANIMATION_2D_WEBGPU_FRONT_FACE}`;
+}
+
+export { AnimationVisual2D as A, animation2DCullingPipelineKey as a, animation2DCullingPrimitive as b, createAnimation2DPipeline as c };
+//# sourceMappingURL=AnimationVisual2D-8y3qp0_U.js.map

package/dist/chunks/{RenderSystem2DBase-DDT61dAu.js → RenderSystem2DBase-CF2s00vg.js}

@@ -26,7 +26,7 @@ mat4.identity();
 
 function createCamera2DLayout(device) {
     return device.createBindGroupLayout({
-        entries: [{ binding: 0, visibility: GPUShaderStage.VERTEX, buffer: { type: 'uniform' } }],
+        entries: [{ binding: 0, visibility: GPUShaderStage.VERTEX | GPUShaderStage.FRAGMENT, buffer: { type: 'uniform' } }],
     });
 }
 function createCamera2DGpu(device, tracker, layout = createCamera2DLayout(device)) {
@@ -224,4 +224,4 @@ class RenderSystem2DBase extends System {
 }
 
 export { RenderSystem2DBase as R, destroyTexture2DGpu as a, createObject2DLayout as b, createCamera2DGpu as c, destroyCamera2DGpu as d, createTexture2DGpu as e, writeFloatBuffer as f, createObject2DGpu as g, destroyObject2DGpu as h, createCamera2DLayout as i, writeObjectMatrixIfChanged as w };
-//# sourceMappingURL=RenderSystem2DBase-DDT61dAu.js.map
+//# sourceMappingURL=RenderSystem2DBase-CF2s00vg.js.map

package/dist/controls/VirtualJoystickControls.d.ts

@@ -0,0 +1,46 @@
+import { System, type World } from '@haiyue/engine/ecs';
+import { EventEmitter } from '@haiyue/engine/core';
+import type { VirtualJoystickEventMap, VirtualJoystickOptions, VirtualJoystickState, VirtualJoystickSurface } from './contracts';
+/**
+ * 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.
+ */
+export declare class VirtualJoystickControls extends System {
+    readonly events: EventEmitter<VirtualJoystickEventMap>;
+    private readonly surface;
+    private readonly document;
+    private readonly window;
+    private options;
+    private view;
+    private pointerId;
+    private center;
+    private point;
+    private bounds;
+    private disposed;
+    constructor(surface: VirtualJoystickSurface, options?: VirtualJoystickOptions);
+    get disabled(): boolean;
+    set disabled(value: boolean);
+    /** Retainable immutable snapshot; caller mutation cannot alter future movement. */
+    get state(): VirtualJoystickState;
+    /** Atomic parameter update. A valid update cancels the current gesture. */
+    configure(options: VirtualJoystickOptions): this;
+    /** Cancel from native suspend/unload hooks; idempotent, returns thumb to center. */
+    cancel(): this;
+    /** Delta is milliseconds, matching World.update(). No internal RAF or timer. */
+    step(deltaMilliseconds: number): this;
+    update(_world: World, _time: number, delta: number): this;
+    destroy(): this;
+    private refreshLayout;
+    private createView;
+    private updateView;
+    private local;
+    private readonly onDown;
+    private readonly onMove;
+    private readonly onUp;
+    private readonly onCancel;
+    private readonly onBlur;
+    private readonly onVisibility;
+    private finish;
+    private moveTarget;
+}

package/dist/controls/contracts.d.ts

@@ -0,0 +1,91 @@
+import type { Entity } from '@haiyue/engine/ecs';
+import type { GuiRoot, GuiStyle } from '@haiyue/engine/gui';
+export interface JoystickPoint {
+    readonly x: number;
+    readonly y: number;
+}
+export interface JoystickViewport {
+    readonly width: number;
+    readonly height: number;
+}
+export interface JoystickRegion extends JoystickPoint, JoystickViewport {
+}
+/** Coordinates and radii use surface-local CSS/logical pixels, never framebuffer pixels. */
+export interface VirtualJoystickSurface extends EventTarget {
+    getBoundingClientRect(): {
+        left: number;
+        top: number;
+        width: number;
+        height: number;
+    };
+    setPointerCapture?(pointerId: number): void;
+    releasePointerCapture?(pointerId: number): void;
+    readonly ownerDocument?: Document | null;
+}
+export interface VirtualJoystickOptions {
+    /** Fixed center, or the initial press becomes the center. Default: floating. */
+    mode?: 'fixed' | 'floating';
+    /** Fixed mode center. Default: near the bottom-left corner. */
+    center?: JoystickPoint | ((viewport: JoystickViewport) => JoystickPoint);
+    /** Activation region in both modes. Default: the bottom-left quarter. */
+    region?: JoystickRegion | ((viewport: JoystickViewport) => JoystickRegion);
+    /** Maximum thumb travel from center, in logical pixels. Default: 64. */
+    maxDistance?: number;
+    /** Fixed mode hit radius; null uses maxDistance + knobRadius. Default: null. */
+    activationRadius?: number | null;
+    /** Fraction of maxDistance with zero output, in [0, 1). Default: 0.1. */
+    deadZone?: number;
+    /** Optional Entity with CartesianTransform3D (xz) or Transform2D (xy). */
+    target?: Entity | null;
+    /** Parent-local movement plane. Default: xz; up on screen maps to -Z or +Y. */
+    plane?: 'xz' | 'xy';
+    /** World/parent units per second at full strength. Default: 4. */
+    moveSpeed?: number;
+    /** Scale speed by dead-zone-adjusted strength. Default: true. */
+    analog?: boolean;
+    rotateToDirection?: boolean;
+    /** Maximum turning radians per second; Infinity snaps. Default: Infinity. */
+    turnSpeed?: number;
+    /** Heading correction for the model. Default forward: -Z (xz), +X (xy). */
+    rotationOffset?: number;
+    /** Rotate the movement basis around +Y (xz) or +Z (xy), in radians. Default: 0. */
+    movementRotation?: number;
+    /** Cap only built-in movement integration after stalls. Frame events retain actual dt. Default: 100. */
+    maxDeltaMilliseconds?: number;
+    /** Optional shared, full-surface Engine GUI root. Omit for input-only/custom rendering. */
+    guiRoot?: GuiRoot | null;
+    knobRadius?: number;
+    /** Show the fixed joystick while idle. Floating mode always hides while idle. */
+    showIdle?: boolean;
+    baseStyle?: GuiStyle;
+    knobStyle?: GuiStyle;
+    /** Optional HUD/input arbitration. Returning false leaves this pointer untouched. */
+    shouldActivate?: (point: JoystickPoint, event: PointerEvent) => boolean;
+}
+export interface VirtualJoystickState {
+    readonly active: boolean;
+    readonly pointerId: number | null;
+    readonly center: JoystickPoint;
+    /** Unit screen direction: +X right, +Y down. Zero inside the dead zone. */
+    readonly direction: JoystickPoint;
+    /** Clamped thumb displacement, including displacement within the dead zone. */
+    readonly offset: JoystickPoint;
+    readonly rawDistance: number;
+    readonly distance: number;
+    /** [0, 1], rescaled continuously after the dead zone. */
+    readonly strength: number;
+    /** Screen radians from +X clockwise, or zero inside the dead zone. */
+    readonly angle: number;
+}
+export interface VirtualJoystickFrame extends VirtualJoystickState {
+    readonly deltaMilliseconds: number;
+    readonly deltaSeconds: number;
+    readonly movementDeltaSeconds: number;
+}
+export interface VirtualJoystickEventMap {
+    start: VirtualJoystickState;
+    end: VirtualJoystickState;
+    cancel: VirtualJoystickState;
+    /** One event per enabled step, including idle frames and held stationary input. */
+    frame: VirtualJoystickFrame;
+}

package/dist/controls.d.ts

@@ -0,0 +1,2 @@
+export { VirtualJoystickControls } from './controls/VirtualJoystickControls';
+export type { JoystickPoint, JoystickViewport, JoystickRegion, VirtualJoystickSurface, VirtualJoystickOptions, VirtualJoystickState, VirtualJoystickFrame, VirtualJoystickEventMap, } from './controls/contracts';