@zylem/game-lib 0.6.4 → 0.8.0

package/dist/entity.d.ts

@@ -0,0 +1,268 @@
+export { A as ACTOR_TYPE, $ as AmbientLightOptions, B as BOX_TYPE, z as CONE_TYPE, J as CYLINDER_TYPE, C as CollisionShapeType, D as DISK_TYPE, a1 as DirectionalLightOptions, aj as EntityForType, ai as EntityTypeMap, a7 as FOG_TYPE, a0 as HemisphereLightOptions, Y as LIGHT_TYPE, aa as LINE_TYPE, a4 as LightShadowOptions, ad as LinePickResult, n as OnEnterParams, o as OnExitParams, O as OnHeldParams, U as PARTICLE_SYSTEM_TYPE, M as PILL_TYPE, P as PLANE_TYPE, G as PYRAMID_TYPE, a2 as PointLightOptions, R as RECT_TYPE, S as SPHERE_TYPE, f as SPRITE_TYPE, a3 as SpotLightOptions, h as SpriteAnimation, g as SpriteImage, T as TEXT_TYPE, m as ZONE_TYPE, q as ZylemActor, Z as ZylemBox, y as ZylemCone, I as ZylemCylinder, w as ZylemDisk, a6 as ZylemFog, ag as ZylemFogHeightOptions, ah as ZylemFogNoiseOptions, ae as ZylemFogOptions, af as ZylemFogType, X as ZylemLight, _ as ZylemLightOptions, a9 as ZylemLine, ac as ZylemLineOptions, Q as ZylemParticleSystem, V as ZylemParticleSystemOptions, L as ZylemPill, j as ZylemPlane, F as ZylemPyramid, u as ZylemRect, b as ZylemSphere, e as ZylemSprite, s as ZylemText, l as ZylemZone, p as createActor, c as createBox, x as createCone, H as createCylinder, v as createDisk, a5 as createFog, W as createLight, a8 as createLine, N as createParticleSystem, K as createPill, i as createPlane, E as createPyramid, t as createRect, a as createSphere, d as createSprite, r as createText, k as createZone, ab as pickZylemLine } from './entity-type-map-Bd69SpAS.js';
+import { G as GameEntity, a as GameEntityOptions, E as EntityBuilder, D as EntityMeshBuilder, F as EntityCollisionBuilder, B as BaseNode } from './entity-BdSI8CL3.js';
+export { C as CollisionComponent, b as boxCollision, d as coneCollision, c as create, e as cylinderCollision, f as pillCollision, g as planeCollision, p as pyramidCollision, s as sphereCollision, z as zoneCollision } from './entity-BdSI8CL3.js';
+import { Color, Mesh } from 'three';
+import { b as Vec2Input, e as Vec3Input } from './vector-CiSHbivc.js';
+import { e as MaterialOptions } from './material-9vJ6SZaI.js';
+import './base-node-life-cycle-D2NuN1VB.js';
+import './stage-transition-CmGpV4tc.js';
+import '@zylem/behaviors/core';
+import './entity-DZbFQ1Wg.js';
+import '@zylem/behaviors/particle-emitter';
+import 'three/addons/lines/webgpu/Line2.js';
+import './collision-builder-jF-toPIl.js';
+import './events.js';
+import 'mitt';
+import 'three/webgpu';
+
+interface CreateGameEntityOptions<T extends GameEntity<any>, CreateOptions extends GameEntityOptions> {
+    args: Array<any>;
+    defaultConfig: GameEntityOptions;
+    EntityClass: new (options: any) => T;
+    BuilderClass: new (options: any, entity: T, meshBuilder: any, collisionBuilder: any) => EntityBuilder<T, CreateOptions>;
+    MeshBuilderClass?: new (data: any) => EntityMeshBuilder;
+    CollisionBuilderClass?: new (data: any) => EntityCollisionBuilder;
+    entityType: symbol;
+    cloneFactory: (options?: Partial<CreateOptions>) => T;
+}
+declare function createEntity<T extends GameEntity<any>, CreateOptions extends GameEntityOptions>(params: CreateGameEntityOptions<T, CreateOptions>): T;
+
+/**
+ * Factory interface for generating entity copies
+ */
+interface TemplateFactory<E extends GameEntity<O>, O extends GameEntityOptions = GameEntityOptions> {
+    /** The template entity used for cloning */
+    readonly template: E;
+    /**
+     * Generate multiple copies of the template entity
+     * @param count Number of copies to generate
+     * @returns Array of new entity instances
+     */
+    generate(count: number): E[];
+}
+/**
+ * Create an entity factory from a template entity.
+ *
+ * @param template The entity to use as a template for cloning
+ * @returns Factory object with generate() method
+ *
+ * @example
+ * ```typescript
+ * const asteroidTemplate = createSprite({ images: [{ name: 'asteroid', file: asteroidImg }] });
+ * const asteroidFactory = createEntityFactory(asteroidTemplate);
+ * const asteroids = asteroidFactory.generate(10);
+ *
+ * asteroids.forEach((asteroid, i) => {
+ *     asteroid.setPosition(Math.random() * 20 - 10, Math.random() * 15 - 7.5, 0);
+ *     stage.add(asteroid);
+ * });
+ * ```
+ */
+declare function createEntityFactory<E extends GameEntity<O>, O extends GameEntityOptions = GameEntityOptions>(template: E): TemplateFactory<E, O>;
+
+/**
+ * CooldownIcon -- a WoW-style cooldown icon UI entity.
+ *
+ * Renders a square icon with a semi-transparent clockwise sweep overlay
+ * that reflects cooldown progress from the CooldownStore. Optionally shows
+ * remaining time text in the center.
+ *
+ * Modeled after ZylemRect's canvas-based viewport-attached sprite pattern.
+ */
+
+/**
+ * Reference point on the viewport for positioning UI elements.
+ * The offset in `screenPosition` is applied relative to this anchor.
+ */
+type ScreenAnchor = 'top-left' | 'top-center' | 'top-right' | 'center-left' | 'center' | 'center-right' | 'bottom-left' | 'bottom-center' | 'bottom-right';
+/** Preset icon sizes in view units. */
+declare const ICON_SIZE_PRESETS: {
+    readonly xs: 8;
+    readonly sm: 16;
+    readonly md: 32;
+    readonly lg: 48;
+    readonly xl: 64;
+};
+/** Named size preset. */
+type IconSizePreset = keyof typeof ICON_SIZE_PRESETS;
+/**
+ * Icon size expressed as a named preset, a square unit value, or
+ * a `{ width, height }` object for non-square icons.
+ *
+ * All numeric values are in **view units** (viewport height = 192 units).
+ */
+type IconSize = IconSizePreset | number | {
+    width: number;
+    height: number;
+};
+type ZylemCooldownIconOptions = GameEntityOptions & {
+    /** Name of the cooldown in the CooldownStore */
+    cooldown: string;
+    /** Texture path for the icon background (optional) */
+    icon?: string;
+    /** Solid fill color when no icon texture is provided */
+    fillColor?: Color | string;
+    /**
+     * Size of the icon in view units, a named preset, or a `{ width, height }` object.
+     *
+     * Presets: `'xs'` (8), `'sm'` (16), `'md'` (32), `'lg'` (48), `'xl'` (64).
+     * A bare number creates a square icon of that many units.
+     * The viewport height equals 192 units; width scales with aspect ratio.
+     *
+     * @default 'md'
+     */
+    iconSize?: IconSize;
+    /** Whether to show remaining time text */
+    showTimer?: boolean;
+    /** Whether to attach to the camera viewport (default: true) */
+    stickToViewport?: boolean;
+    /**
+     * Viewport anchor the icon is positioned relative to.
+     * @default 'top-left'
+     */
+    screenAnchor?: ScreenAnchor;
+    /**
+     * Offset from the {@link screenAnchor} in **view units**.
+     * Positive x = right, positive y = down.
+     * Accepts a `Vector2`, plain `{ x, y }` object, or tuple.
+     * @default { x: 0, y: 0 }
+     */
+    screenPosition?: Vec2Input;
+    /** Distance from camera (default: 1) */
+    zDistance?: number;
+    /** Color of the sweep overlay (default: semi-transparent black) */
+    overlayColor?: string;
+};
+declare class ZylemCooldownIcon extends GameEntity<ZylemCooldownIconOptions> {
+    static type: symbol;
+    private _sprite;
+    private _texture;
+    private _canvas;
+    private _ctx;
+    private _cameraRef;
+    private _iconTexture;
+    private _iconImage;
+    private _lastRenderedProgress;
+    constructor(options?: ZylemCooldownIconOptions);
+    private createSprite;
+    private redraw;
+    private toCssColor;
+    private getResolution;
+    private iconSetup;
+    private iconUpdate;
+    /**
+     * Resolve screen position to pixels.
+     * Computes the anchor point in pixels, then adds the view-unit offset.
+     */
+    private resolveScreenPosition;
+    /**
+     * Resolve `iconSize` to screen pixels using the view-unit grid.
+     * Viewport height = {@link VIEW_UNITS_HEIGHT} units; width scales with aspect ratio.
+     */
+    private resolveIconSize;
+    /** Compute the world-space half-extents at a given distance from the camera. */
+    private computeWorldExtents;
+    private updateStickyTransform;
+    /**
+     * Dispose Three.js / DOM resources when the entity is destroyed.
+     */
+    private iconDestroy;
+}
+type CooldownIconOptions = BaseNode | Partial<ZylemCooldownIconOptions>;
+/**
+ * Create a WoW-style cooldown icon UI entity.
+ *
+ * @example
+ * ```ts
+ * const attackIcon = createCooldownIcon({
+ *   cooldown: 'attack',
+ *   icon: swordIconPath,
+ *   screenAnchor: 'top-center',         // reference point on the viewport
+ *   screenPosition: { x: 0, y: 10 },    // offset in view units from anchor
+ *   iconSize: 'sm',                      // preset (16 × 16 view units)
+ *   // iconSize: 24,                     // square  (24 × 24 view units)
+ *   // iconSize: { width: 16, height: 24 }, // custom rectangle
+ * });
+ * ```
+ */
+declare function createCooldownIcon(...args: Array<CooldownIconOptions>): ZylemCooldownIcon;
+
+declare function destroy(entity: any, globals?: any): void;
+
+/** Shared options that every mesh factory accepts. */
+interface BaseMeshOptions {
+    /** Offset position relative to the entity origin */
+    position?: Vec3Input;
+    /** Material options (texture, shader, etc.) */
+    material?: Partial<MaterialOptions>;
+    /** Convenience color override */
+    color?: Color;
+}
+interface BoxMeshOptions extends BaseMeshOptions {
+    /** Box dimensions (default: 1x1x1) */
+    size?: Vec3Input;
+}
+/**
+ * Create a box mesh.
+ */
+declare function boxMesh(opts?: BoxMeshOptions): Mesh;
+interface SphereMeshOptions extends BaseMeshOptions {
+    /** Sphere radius (default: 1) */
+    radius?: number;
+}
+/**
+ * Create a sphere mesh.
+ */
+declare function sphereMesh(opts?: SphereMeshOptions): Mesh;
+interface ConeMeshOptions extends BaseMeshOptions {
+    /** Base radius (default: 1) */
+    radius?: number;
+    /** Height (default: 2) */
+    height?: number;
+    /** Radial segments (default: 32) */
+    radialSegments?: number;
+}
+/**
+ * Create a cone mesh.
+ */
+declare function coneMesh(opts?: ConeMeshOptions): Mesh;
+interface PyramidMeshOptions extends BaseMeshOptions {
+    /** Base radius (default: 1) */
+    radius?: number;
+    /** Height (default: 2) */
+    height?: number;
+}
+/**
+ * Create a pyramid mesh (4-sided cone).
+ */
+declare function pyramidMesh(opts?: PyramidMeshOptions): Mesh;
+interface CylinderMeshOptions extends BaseMeshOptions {
+    /** Top radius (default: 1) */
+    radiusTop?: number;
+    /** Bottom radius (default: 1) */
+    radiusBottom?: number;
+    /** Height (default: 2) */
+    height?: number;
+    /** Radial segments (default: 32) */
+    radialSegments?: number;
+}
+/**
+ * Create a cylinder mesh.
+ */
+declare function cylinderMesh(opts?: CylinderMeshOptions): Mesh;
+interface PillMeshOptions extends BaseMeshOptions {
+    /** Capsule hemisphere radius (default: 0.5) */
+    radius?: number;
+    /** Cylindrical section length (default: 1) */
+    length?: number;
+    /** Cap segments (default: 10) */
+    capSegments?: number;
+    /** Radial segments (default: 20) */
+    radialSegments?: number;
+}
+/**
+ * Create a pill (capsule) mesh.
+ */
+declare function pillMesh(opts?: PillMeshOptions): Mesh;
+
+export { GameEntity, GameEntityOptions, type IconSize, type IconSizePreset, type ScreenAnchor, type TemplateFactory, boxMesh, coneMesh, createCooldownIcon, createEntity, createEntityFactory, cylinderMesh, destroy, pillMesh, pyramidMesh, sphereMesh };

package/dist/entity.js

@@ -0,0 +1 @@
+import{A as $,B as aa,C as ba,D as ca,E as da,F as ea,G as fa,H as ga,I as ha,J as ia,K as ja,L as ka,M as la,N as ma,O as na,P as oa,Q as pa,R as qa,a as B,b as C,c as D,d as E,e as F,f as G,g as H,h as I,i as J,j as K,k as L,l as M,m as N,n as O,o as P,p as Q,q as R,r as S,s as T,t as U,u as V,v as W,w as X,x as Y,y as Z,z as _}from"./chunk-7FR5JSQ2.js";import{b as q,c as r,d as s,e as t,f as u,g as v,h as w,i as x,j as y,k as z,m as A}from"./chunk-XNDS4YFR.js";import{c as a,d as b,e as c,f as d,g as e,h as f,i as g,j as h,n as i,p as j,t as k,u as l,v as m,w as n,x as o,y as p}from"./chunk-XNHVRFAK.js";import"./chunk-CM5YRNBJ.js";import"./chunk-YHEWKN7N.js";import"./chunk-QXVH6POE.js";import"./chunk-E3UBSUPX.js";import"./chunk-4QLJUQSJ.js";import"./chunk-7WRQ2UAN.js";import"./chunk-XRP4JJXL.js";export{k as ACTOR_TYPE,H as BOX_TYPE,Z as CONE_TYPE,da as CYLINDER_TYPE,W as DISK_TYPE,n as FOG_TYPE,ma as LIGHT_TYPE,w as LINE_TYPE,ja as PARTICLE_SYSTEM_TYPE,ga as PILL_TYPE,N as PLANE_TYPE,aa as PYRAMID_TYPE,T as RECT_TYPE,K as SPHERE_TYPE,t as SPRITE_TYPE,q as TEXT_TYPE,Q as ZONE_TYPE,l as ZylemActor,I as ZylemBox,_ as ZylemCone,ea as ZylemCylinder,X as ZylemDisk,o as ZylemFog,na as ZylemLight,y as ZylemLine,ka as ZylemParticleSystem,ha as ZylemPill,O as ZylemPlane,ba as ZylemPyramid,U as ZylemRect,L as ZylemSphere,u as ZylemSprite,r as ZylemText,R as ZylemZone,a as boxCollision,B as boxMesh,c as coneCollision,D as coneMesh,i as create,m as createActor,J as createBox,$ as createCone,pa as createCooldownIcon,fa as createCylinder,Y as createDisk,j as createEntity,A as createEntityFactory,p as createFog,oa as createLight,z as createLine,la as createParticleSystem,ia as createPill,P as createPlane,ca as createPyramid,V as createRect,M as createSphere,v as createSprite,s as createText,S as createZone,e as cylinderCollision,F as cylinderMesh,qa as destroy,x as pickZylemLine,f as pillCollision,G as pillMesh,g as planeCollision,d as pyramidCollision,E as pyramidMesh,b as sphereCollision,C as sphereMesh,h as zoneCollision};

package/dist/events.d.ts

@@ -0,0 +1,181 @@
+import * as mitt from 'mitt';
+import { L as LoadingEvent } from './base-node-life-cycle-D2NuN1VB.js';
+import 'three';
+import './stage-transition-CmGpV4tc.js';
+
+/**
+ * Reusable delegate for event emission and subscription.
+ * Use via composition in Game, Stage, and Entity classes.
+ *
+ * @example
+ * class Game {
+ *   private eventDelegate = new EventEmitterDelegate<GameEvents>();
+ *
+ *   dispatch<K extends keyof GameEvents>(event: K, payload: GameEvents[K]) {
+ *     this.eventDelegate.dispatch(event, payload);
+ *   }
+ * }
+ */
+declare class EventEmitterDelegate<TEvents extends Record<string, unknown>> {
+    private emitter;
+    private unsubscribes;
+    constructor();
+    /**
+     * Dispatch an event to all listeners.
+     */
+    dispatch<K extends keyof TEvents>(event: K, payload: TEvents[K]): void;
+    /**
+     * Subscribe to an event. Returns an unsubscribe function.
+     */
+    listen<K extends keyof TEvents>(event: K, handler: (payload: TEvents[K]) => void): () => void;
+    /**
+     * Subscribe to all events.
+     */
+    listenAll(handler: (type: keyof TEvents, payload: TEvents[keyof TEvents]) => void): () => void;
+    /**
+     * Clean up all subscriptions.
+     */
+    dispose(): void;
+}
+
+/**
+ * Payload for game loading events with stage context.
+ */
+interface GameLoadingPayload extends LoadingEvent {
+    stageName?: string;
+    stageIndex?: number;
+}
+/** Payload for stage configuration sent to editor. */
+interface StageConfigPayload {
+    id: string;
+    backgroundColor: string;
+    backgroundImage: string | null;
+    gravity: {
+        x: number;
+        y: number;
+        z: number;
+    };
+    inputs: Record<string, string[]>;
+    variables: Record<string, unknown>;
+}
+/** Payload for entity configuration sent to editor. */
+interface EntityConfigPayload {
+    uuid: string;
+    name: string;
+    type: string;
+    position: {
+        x: number;
+        y: number;
+        z: number;
+    };
+    rotation: {
+        x: number;
+        y: number;
+        z: number;
+    };
+    scale: {
+        x: number;
+        y: number;
+        z: number;
+    };
+    /** PNG data URL of a framed entity preview, when available. */
+    thumbnail?: string | null;
+    /** World-space AABB size used for thumbnail rulers. */
+    bounds?: {
+        width: number;
+        height: number;
+        depth: number;
+    };
+}
+/** Payload for state dispatch events from game to editor. */
+interface StateDispatchPayload {
+    scope: 'game' | 'stage' | 'entity';
+    path: string;
+    value: unknown;
+    previousValue?: unknown;
+    config?: {
+        id: string;
+        aspectRatio: number;
+        fullscreen: boolean;
+        bodyBackground: string | undefined;
+        internalResolution: {
+            width: number;
+            height: number;
+        } | undefined;
+        debug: boolean;
+    } | null;
+    stageConfig?: StageConfigPayload | null;
+    entities?: EntityConfigPayload[] | null;
+}
+type GameEvents = {
+    'loading:start': GameLoadingPayload;
+    'loading:progress': GameLoadingPayload;
+    'loading:complete': GameLoadingPayload;
+    'paused': {
+        paused: boolean;
+    };
+    'debug': {
+        enabled: boolean;
+    };
+    'state:dispatch': StateDispatchPayload;
+};
+type StageEvents = {
+    'stage:loaded': {
+        stageId: string;
+    };
+    'stage:unloaded': {
+        stageId: string;
+    };
+    'stage:variable:changed': {
+        key: string;
+        value: unknown;
+    };
+};
+type EntityEvents = {
+    'entity:spawned': {
+        entityId: string;
+        name: string;
+    };
+    'entity:destroyed': {
+        entityId: string;
+    };
+    'entity:collision': {
+        entityId: string;
+        otherId: string;
+    };
+    'entity:model:loading': {
+        entityId: string;
+        files: string[];
+    };
+    'entity:model:loaded': {
+        entityId: string;
+        success: boolean;
+        meshCount?: number;
+        errorMessage?: string;
+    };
+    'entity:animation:loaded': {
+        entityId: string;
+        animationCount: number;
+    };
+};
+type ZylemEvents = GameEvents & StageEvents & EntityEvents;
+/**
+ * Global event bus for cross-package communication.
+ *
+ * Usage:
+ * ```ts
+ * import { zylemEventBus } from '@zylem/game-lib/events';
+ *
+ * // Subscribe
+ * const unsub = zylemEventBus.on('loading:progress', (e) => console.log(e));
+ *
+ * // Emit
+ * zylemEventBus.emit('loading:progress', { type: 'progress', progress: 0.5 });
+ *
+ * // Cleanup
+ * unsub();
+ * ```
+ */
+declare const zylemEventBus: mitt.Emitter<ZylemEvents>;
+
+export { type EntityConfigPayload, type EntityEvents, EventEmitterDelegate, type GameEvents, type GameLoadingPayload, type StageConfigPayload, type StageEvents, type StateDispatchPayload, type ZylemEvents, zylemEventBus };

package/dist/events.js

@@ -0,0 +1 @@
+import"./chunk-BIGH6D34.js";import{a,b}from"./chunk-YHEWKN7N.js";import"./chunk-QXVH6POE.js";export{a as EventEmitterDelegate,b as zylemEventBus};