@zylem/game-lib 0.6.4 → 0.7.0

package/README.md

@@ -39,7 +39,9 @@ npm install @zylem/game-lib
  * the ball can be controlled with the arrow keys or gamepad
  * the ball cannot go outside the boundaries
  */
-import { createGame, createSphere, WorldBoundary2DBehavior } from '@zylem/game-lib';
+import { createGame } from '@zylem/game-lib/core';
+import { createSphere } from '@zylem/game-lib/entity';
+import { WorldBoundary2DBehavior } from '@zylem/game-lib/behavior';
 
 // Creates a sphere (movement capabilities are built-in)
 const ball = createSphere();

package/dist/actions.d.ts

@@ -1,12 +1,259 @@
-import { T as TransformState } from './entity-vj-HTjzU.js';
-export { A as Action, c as createTransformStore, i as getPosition, H as getRotation, j as getVelocity, m as move, h as moveForwardXY, a as moveX, e as moveXY, f as moveXZ, b as moveY, d as moveZ, r as resetTransformStore, g as resetVelocity, t as rotateEuler, p as rotateInDirection, u as rotateX, v as rotateY, q as rotateYEuler, x as rotateZ, s as setPosition, k as setPositionX, l as setPositionY, n as setPositionZ, G as setRotation, C as setRotationDegrees, E as setRotationDegreesX, D as setRotationDegreesY, F as setRotationDegreesZ, z as setRotationX, y as setRotationY, B as setRotationZ, o as wrapAround3D, w as wrapAroundXY } from './entity-vj-HTjzU.js';
-export { c as callFunc, d as delay, m as moveBy, a as moveTo, o as onPress, b as onRelease, p as parallel, e as repeat, f as repeatForever, r as rotateBy, s as sequence, t as throttle } from './composition-BASvMKrW.js';
+import { A as Action, G as GameEntity } from './entity-DNkYKfdp.js';
+export { H as getRotation, t as rotateEuler, r as rotateInDirection, u as rotateX, v as rotateY, s as rotateYEuler, w as rotateZ, F as setRotation, B as setRotationDegrees, D as setRotationDegreesX, C as setRotationDegreesY, E as setRotationDegreesZ, y as setRotationX, x as setRotationY, z as setRotationZ } from './entity-DNkYKfdp.js';
+import { Object3D } from 'three';
+import { TransformState } from '@zylem/behaviors/core';
+export { TransformState, createTransformStore, getPosition, getVelocity, move, moveForwardXY, moveX, moveXY, moveXZ, moveY, moveZ, resetTransformStore, resetVelocity, setPosition, setPositionX, setPositionY, setPositionZ, wrapAround3D, wrapAroundXY } from '@zylem/behaviors/core';
 import { RigidBody } from '@dimforge/rapier3d-compat';
-export { g as globalChange, a as globalChanges, v as variableChange, b as variableChanges } from './global-change-2JvMaz44.js';
-import 'three';
-import 'bitecs';
+import './material-Wz83vTTp.js';
+import 'three/webgpu';
+import './base-node-life-cycle-CnJ-7zX-.js';
+import './events.js';
 import 'mitt';
-import './behavior-descriptor-BXnVR8Ki.js';
+
+/** Minimal entity shape for opacity helpers (avoids GameEntity generic variance). */
+type OpacityEntity = {
+    group?: Object3D | null;
+    mesh?: Object3D | null;
+};
+/**
+ * Sets opacity on every fadeable material under an entity's visual root.
+ */
+declare function resetEntityOpacity(entity: OpacityEntity, opacity?: number, transparent?: boolean): void;
+interface MoveByOptions {
+    /** X displacement (default: 0) */
+    x?: number;
+    /** Y displacement (default: 0) */
+    y?: number;
+    /** Z displacement (default: 0) */
+    z?: number;
+    /** Duration in milliseconds */
+    duration: number;
+}
+/**
+ * Move an entity by a displacement over a duration.
+ * Distributes the movement as velocity each frame so physics stays in sync.
+ *
+ * @example
+ * ```ts
+ * entity.runAction(moveBy({ x: 10, duration: 500 }));
+ * ```
+ */
+declare function moveBy(opts: MoveByOptions): Action;
+interface MoveToOptions {
+    /** Target X position */
+    x: number;
+    /** Target Y position */
+    y: number;
+    /** Target Z position */
+    z: number;
+    /** Duration in milliseconds */
+    duration: number;
+}
+/**
+ * Move an entity to an absolute position over a duration.
+ * Calculates displacement from the entity's position on the first tick.
+ *
+ * @example
+ * ```ts
+ * entity.runAction(moveTo({ x: 0, y: 10, z: 0, duration: 2000 }));
+ * ```
+ */
+declare function moveTo(opts: MoveToOptions): Action;
+interface RotateByOptions {
+    /** X rotation in degrees (default: 0) */
+    x?: number;
+    /** Y rotation in degrees (default: 0) */
+    y?: number;
+    /** Z rotation in degrees (default: 0) */
+    z?: number;
+    /** Duration in milliseconds */
+    duration: number;
+}
+/**
+ * Rotate an entity by euler angles (degrees) over a duration.
+ *
+ * @example
+ * ```ts
+ * entity.runAction(rotateBy({ y: 360, duration: 2000 }));
+ * ```
+ */
+declare function rotateBy(opts: RotateByOptions): Action;
+/**
+ * Wait for a duration. Useful inside `sequence()`.
+ *
+ * @param ms Duration in milliseconds
+ * @example
+ * ```ts
+ * entity.runAction(sequence(moveBy({ x: 5, duration: 1000 }), delay(500), moveBy({ y: 3, duration: 1000 })));
+ * ```
+ */
+declare function delay(ms: number): Action;
+/**
+ * Call a function immediately. Completes in one frame.
+ * Useful inside `sequence()` for side effects.
+ *
+ * @example
+ * ```ts
+ * entity.runAction(sequence(moveBy({ x: 5, duration: 1000 }), callFunc(() => console.log('done'))));
+ * ```
+ */
+declare function callFunc(fn: () => void): Action;
+interface FadeOpacityOptions {
+    /** Starting opacity (default: 1) */
+    from?: number;
+    /** Ending opacity (default: 0) */
+    to?: number;
+    /** Duration in milliseconds */
+    duration: number;
+    /** Optional Object3D roots to traverse; defaults to entity.group ?? entity.mesh */
+    targets?: Object3D[];
+    /** When complete and `to >= 1`, restore transparent=false on affected materials */
+    restoreOpaque?: boolean;
+}
+/**
+ * Fade material opacity on an entity (or explicit targets) over a duration.
+ *
+ * @example
+ * ```ts
+ * entity.runAction(fadeOpacity({ from: 0, to: 1, duration: 400, restoreOpaque: true }));
+ * ```
+ */
+declare function fadeOpacity(opts: FadeOpacityOptions): Action;
+
+interface ThrottleOptions {
+    /** Interval in milliseconds between ready cycles */
+    duration: number;
+}
+/**
+ * A repeating timer that becomes ready every N milliseconds.
+ * Register with `entity.action(throttle(...))`.
+ *
+ * @example
+ * ```ts
+ * const t = entity.action(throttle({ duration: 500 }));
+ * entity.onUpdate(() => {
+ *   if (t.ready) { t.consume(); // do something every 500ms }
+ * });
+ * ```
+ */
+declare function throttle(opts: ThrottleOptions): ThrottleAction;
+declare class ThrottleAction implements Action {
+    readonly duration: number;
+    done: boolean;
+    persistent: boolean;
+    ready: boolean;
+    private elapsed;
+    /** @param durationMs Duration in milliseconds */
+    constructor(durationMs: number);
+    tick(_entity: GameEntity<any>, delta: number): void;
+    /** Consume the ready state and reset the timer */
+    consume(): void;
+    reset(): void;
+}
+/**
+ * Detects the rising edge of a boolean signal (press).
+ * Call `.check(isPressed)` each frame in your onUpdate; `.triggered` is
+ * true for one frame on press.
+ *
+ * @example
+ * ```ts
+ * const press = entity.action(onPress());
+ * entity.onUpdate(({ inputs }) => {
+ *   press.check(inputs.p1.buttons.A.pressed);
+ *   if (press.triggered) { // do something once on press }
+ * });
+ * ```
+ */
+declare function onPress(): OnPressAction;
+declare class OnPressAction implements Action {
+    readonly duration: number;
+    done: boolean;
+    persistent: boolean;
+    triggered: boolean;
+    private wasPressed;
+    tick(): void;
+    /**
+     * Feed the current pressed state. Sets `.triggered = true` on the
+     * frame where `isPressed` transitions from false to true.
+     */
+    check(isPressed: boolean): void;
+    reset(): void;
+}
+/**
+ * Detects the falling edge of a boolean signal (release).
+ * Call `.check(isPressed)` each frame; `.triggered` is true for one frame
+ * on release.
+ *
+ * @example
+ * ```ts
+ * const release = entity.action(onRelease());
+ * entity.onUpdate(({ inputs }) => {
+ *   release.check(inputs.p1.buttons.A.pressed);
+ *   if (release.triggered) { // do something once on release }
+ * });
+ * ```
+ */
+declare function onRelease(): OnReleaseAction;
+declare class OnReleaseAction implements Action {
+    readonly duration: number;
+    done: boolean;
+    persistent: boolean;
+    triggered: boolean;
+    private wasPressed;
+    tick(): void;
+    /**
+     * Feed the current pressed state. Sets `.triggered = true` on the
+     * frame where `isPressed` transitions from true to false.
+     */
+    check(isPressed: boolean): void;
+    reset(): void;
+}
+
+/**
+ * Run actions in order, one after another.
+ *
+ * @example
+ * ```ts
+ * entity.runAction(sequence(
+ *   moveBy({ x: 5, duration: 1000 }),
+ *   delay(500),
+ *   moveBy({ y: 3, duration: 1000 }),
+ * ));
+ * ```
+ */
+declare function sequence(...actions: Action[]): Action;
+/**
+ * Run all actions simultaneously. Done when all children are done.
+ *
+ * @example
+ * ```ts
+ * entity.runAction(parallel(
+ *   moveBy({ x: 5, duration: 1000 }),
+ *   rotateBy({ y: 360, duration: 1000 }),
+ * ));
+ * ```
+ */
+declare function parallel(...actions: Action[]): Action;
+/**
+ * Repeat an action a fixed number of times.
+ *
+ * @example
+ * ```ts
+ * entity.runAction(repeat(moveBy({ x: 2, duration: 500 }), 5));
+ * ```
+ */
+declare function repeat(action: Action, times: number): Action;
+/**
+ * Repeat an action forever. Never completes.
+ *
+ * @example
+ * ```ts
+ * enemy.runAction(repeatForever(
+ *   sequence(moveBy({ x: 3, duration: 2000 }), moveBy({ x: -3, duration: 2000 })),
+ * ));
+ * ```
+ */
+declare function repeatForever(action: Action): Action;
 
 /**
  * Entity that can have transformations applied from a store
@@ -31,4 +278,4 @@ interface TransformableEntity {
  */
 declare function applyTransformChanges(entity: TransformableEntity, store: TransformState): void;
 
-export { TransformState, applyTransformChanges };
+export { Action, type FadeOpacityOptions, type MoveByOptions, type MoveToOptions, type OpacityEntity, type RotateByOptions, type ThrottleOptions, applyTransformChanges, callFunc, delay, fadeOpacity, moveBy, moveTo, onPress, onRelease, parallel, repeat, repeatForever, resetEntityOpacity, rotateBy, sequence, throttle };