@zylem/game-lib 0.4.1 → 0.5.1

package/dist/entity-bQElAdpo.d.ts

@@ -0,0 +1,347 @@
+import { Vector3, Vector2, Color, Material, BufferGeometry, Mesh, Group, ShaderMaterial } from 'three';
+import { Vector3 as Vector3$1, RigidBodyDesc, ColliderDesc, RigidBody, Collider } from '@dimforge/rapier3d-compat';
+import { IComponent } from 'bitecs';
+
+/** Input
+ *
+ * Maximum number of local players is 8.
+ * All input can be mapped to a gamepad or keyboard but shares the common
+ * interface represented as a gamepad.
+ */
+type InputPlayerNumber = 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8;
+type InputPlayer = `p${InputPlayerNumber}`;
+interface ButtonState {
+    pressed: boolean;
+    released: boolean;
+    held: number;
+}
+interface AnalogState {
+    value: number;
+    held: number;
+}
+interface InputGamepad {
+    playerNumber: InputPlayerNumber;
+    buttons: {
+        A: ButtonState;
+        B: ButtonState;
+        X: ButtonState;
+        Y: ButtonState;
+        Start: ButtonState;
+        Select: ButtonState;
+        L: ButtonState;
+        R: ButtonState;
+    };
+    directions: {
+        Up: ButtonState;
+        Down: ButtonState;
+        Left: ButtonState;
+        Right: ButtonState;
+    };
+    shoulders: {
+        LTrigger: ButtonState;
+        RTrigger: ButtonState;
+    };
+    axes: {
+        Horizontal: AnalogState;
+        Vertical: AnalogState;
+    };
+}
+type Inputs = Record<InputPlayer, InputGamepad>;
+
+type LoadingEvent = {
+    type: 'start' | 'progress' | 'complete';
+    message?: string;
+    progress?: number;
+    total?: number;
+    current?: number;
+};
+interface IGame<TGlobals extends Record<string, unknown> = any> {
+    start: () => Promise<this>;
+    nextStage: () => Promise<void>;
+    previousStage: () => Promise<void>;
+    reset: () => Promise<void>;
+    pause: () => Promise<void>;
+    resume: () => Promise<void>;
+    onLoading: (callback: (event: LoadingEvent) => void) => void;
+    loadStageFromId: (stageId: string) => Promise<void>;
+    end: () => Promise<void>;
+    goToStage: () => void;
+}
+interface IStage {
+    onUpdate: (callback: UpdateFunction<IStage>) => void;
+    onSetup: (callback: SetupFunction<IStage>) => void;
+    onDestroy: (callback: DestroyFunction<IStage>) => void;
+}
+interface ICamera {
+    move: (position: Vector3) => void;
+    rotate: (pitch: number, yaw: number, roll: number) => void;
+}
+
+type GlobalRecord = Record<string, unknown>;
+/** Setup */
+interface SetupContext<T, TGlobals extends GlobalRecord = any> {
+    me: T;
+    globals: TGlobals;
+    inputs?: Inputs;
+    camera?: ICamera;
+    stage?: IStage;
+    game?: IGame<TGlobals>;
+}
+interface SetupFunction<T, TGlobals extends GlobalRecord = any> {
+    (context: SetupContext<T, TGlobals>): void;
+}
+/** Loaded */
+interface LoadedContext<T, TGlobals extends GlobalRecord = any> {
+    me: T;
+    globals: TGlobals;
+}
+interface LoadedFunction<T, TGlobals extends GlobalRecord = any> {
+    (context: LoadedContext<T, TGlobals>): void;
+}
+/** Update */
+type UpdateContext<T, TGlobals extends GlobalRecord = any> = {
+    me: T;
+    delta: number;
+    inputs: Inputs;
+    globals: TGlobals;
+    camera: ICamera;
+    stage?: IStage;
+    game?: IGame<TGlobals>;
+};
+interface UpdateFunction<T, TGlobals extends GlobalRecord = any> {
+    (context: UpdateContext<T, TGlobals>): void;
+}
+/** Destroy */
+interface DestroyContext<T, TGlobals extends GlobalRecord = any> {
+    me: T;
+    globals: TGlobals;
+}
+interface DestroyFunction<T, TGlobals extends GlobalRecord = any> {
+    (context: DestroyContext<T, TGlobals>): void;
+}
+/** Cleanup */
+interface CleanupContext<T, TGlobals extends GlobalRecord = any> {
+    me: T;
+    globals: TGlobals;
+}
+interface CleanupFunction<T, TGlobals extends GlobalRecord = any> {
+    (context: CleanupContext<T, TGlobals>): void;
+}
+
+interface NodeInterface {
+    uuid: string;
+    name: string;
+    markedForRemoval: boolean;
+    nodeSetup(params: SetupContext<any>): void;
+    nodeUpdate(params: UpdateContext<any>): void;
+    nodeDestroy(params: DestroyContext<any>): void;
+    setParent(parent: NodeInterface | null): void;
+    getParent(): NodeInterface | null;
+}
+
+type BaseNodeOptions<T = any> = BaseNode | Partial<T>;
+declare abstract class BaseNode<Options = any, T = any> implements NodeInterface {
+    protected parent: NodeInterface | null;
+    protected children: NodeInterface[];
+    options: Options;
+    eid: number;
+    uuid: string;
+    name: string;
+    markedForRemoval: boolean;
+    setup: SetupFunction<this>;
+    loaded: LoadedFunction<this>;
+    update: UpdateFunction<this>;
+    destroy: DestroyFunction<this>;
+    cleanup: CleanupFunction<this>;
+    constructor(args?: BaseNodeOptions[]);
+    setParent(parent: NodeInterface | null): void;
+    getParent(): NodeInterface | null;
+    add(baseNode: NodeInterface): void;
+    remove(baseNode: NodeInterface): void;
+    getChildren(): NodeInterface[];
+    isComposite(): boolean;
+    abstract create(): T;
+    protected abstract _setup(params: SetupContext<this>): void;
+    protected abstract _loaded(params: LoadedContext<this>): Promise<void>;
+    protected abstract _update(params: UpdateContext<this>): void;
+    protected abstract _destroy(params: DestroyContext<this>): void;
+    protected abstract _cleanup(params: CleanupContext<this>): Promise<void>;
+    nodeSetup(params: SetupContext<this>): void;
+    nodeUpdate(params: UpdateContext<this>): void;
+    nodeDestroy(params: DestroyContext<this>): void;
+    getOptions(): Options;
+    setOptions(options: Partial<Options>): void;
+}
+
+type Vec3 = Vector3 | Vector3$1;
+
+declare function shortHash(objString: string): string;
+
+type ZylemShaderType = 'standard' | 'fire' | 'star' | 'debug';
+
+interface MaterialOptions {
+    path?: string;
+    repeat?: Vector2;
+    shader?: ZylemShaderType;
+    color?: Color;
+}
+type BatchGeometryMap = Map<symbol, number>;
+interface BatchMaterialMapObject {
+    geometryMap: BatchGeometryMap;
+    material: Material;
+}
+type BatchKey = ReturnType<typeof shortHash>;
+type TexturePath = string | null;
+declare class MaterialBuilder {
+    static batchMaterialMap: Map<BatchKey, BatchMaterialMapObject>;
+    materials: Material[];
+    batchMaterial(options: Partial<MaterialOptions>, entityType: symbol): void;
+    build(options: Partial<MaterialOptions>, entityType: symbol): Promise<void>;
+    withColor(color: Color): this;
+    withShader(shaderType: ZylemShaderType): this;
+    setTexture(texturePath?: TexturePath, repeat?: Vector2): Promise<void>;
+    setColor(color: Color): void;
+    setShader(customShader: ZylemShaderType): void;
+}
+
+interface CollisionOptions {
+    static?: boolean;
+    sensor?: boolean;
+    size?: Vector3;
+    position?: Vector3;
+    collisionType?: string;
+    collisionFilter?: string[];
+}
+
+declare class CollisionBuilder {
+    static: boolean;
+    sensor: boolean;
+    gravity: Vec3;
+    build(options: Partial<CollisionOptions>): [RigidBodyDesc, ColliderDesc];
+    withCollision(collisionOptions: Partial<CollisionOptions>): this;
+    collider(options: CollisionOptions): ColliderDesc;
+    bodyDesc({ isDynamicBody }: {
+        isDynamicBody?: boolean | undefined;
+    }): RigidBodyDesc;
+}
+
+/**
+ * TODO: allow for multiple materials requires geometry groups
+ * TODO: allow for instanced uniforms
+ * TODO: allow for geometry groups
+ * TODO: allow for batched meshes
+ * import { InstancedUniformsMesh } from 'three-instanced-uniforms-mesh';
+ * may not need geometry groups for shaders though
+ * setGeometry<T extends BufferGeometry>(geometry: T) {
+ *   MeshBuilder.bachedMesh = new BatchedMesh(10, 5000, 10000, material);
+ * }
+ */
+type MeshBuilderOptions = Partial<Pick<GameEntityOptions, 'batched' | 'material'>>;
+declare class MeshBuilder {
+    _build(meshOptions: MeshBuilderOptions, geometry: BufferGeometry, materials: Material[]): Mesh;
+    _postBuild(): void;
+}
+
+declare abstract class EntityCollisionBuilder extends CollisionBuilder {
+    abstract collider(options: GameEntityOptions): ColliderDesc;
+}
+declare abstract class EntityMeshBuilder extends MeshBuilder {
+    build(options: GameEntityOptions): BufferGeometry;
+    postBuild(): void;
+}
+
+interface Behavior {
+    component: IComponent;
+    values: any;
+}
+
+interface LifeCycleDelegate<U> {
+    setup?: ((params: SetupContext<U>) => void)[];
+    update?: ((params: UpdateContext<U>) => void)[];
+    destroy?: ((params: DestroyContext<U>) => void)[];
+}
+interface CollisionContext<T, O extends GameEntityOptions, TGlobals extends Record<string, unknown> = any> {
+    entity: T;
+    other: GameEntity<O>;
+    globals: TGlobals;
+}
+type BehaviorContext<T, O extends GameEntityOptions> = SetupContext<T, O> | UpdateContext<T, O> | CollisionContext<T, O> | DestroyContext<T, O>;
+type BehaviorCallback<T, O extends GameEntityOptions> = (params: BehaviorContext<T, O>) => void;
+interface CollisionDelegate<T, O extends GameEntityOptions> {
+    collision?: ((params: CollisionContext<T, O>) => void)[];
+}
+type IBuilder<BuilderOptions = any> = {
+    preBuild: (options: BuilderOptions) => BuilderOptions;
+    build: (options: BuilderOptions) => BuilderOptions;
+    postBuild: (options: BuilderOptions) => BuilderOptions;
+};
+type GameEntityOptions = {
+    name?: string;
+    color?: Color;
+    size?: Vec3;
+    position?: Vec3;
+    batched?: boolean;
+    collision?: Partial<CollisionOptions>;
+    material?: Partial<MaterialOptions>;
+    custom?: {
+        [key: string]: any;
+    };
+    collisionType?: string;
+    collisionGroup?: string;
+    collisionFilter?: string[];
+    _builders?: {
+        meshBuilder?: IBuilder | EntityMeshBuilder | null;
+        collisionBuilder?: IBuilder | EntityCollisionBuilder | null;
+        materialBuilder?: MaterialBuilder | null;
+    };
+};
+declare abstract class GameEntityLifeCycle {
+    abstract _setup(params: SetupContext<this>): void;
+    abstract _update(params: UpdateContext<this>): void;
+    abstract _destroy(params: DestroyContext<this>): void;
+}
+interface EntityDebugInfo {
+    buildInfo: () => Record<string, string>;
+}
+type BehaviorCallbackType = 'setup' | 'update' | 'destroy' | 'collision';
+declare class GameEntity<O extends GameEntityOptions> extends BaseNode<O> implements GameEntityLifeCycle, EntityDebugInfo {
+    behaviors: Behavior[];
+    group: Group | undefined;
+    mesh: Mesh | undefined;
+    materials: Material[] | undefined;
+    bodyDesc: RigidBodyDesc | null;
+    body: RigidBody | null;
+    colliderDesc: ColliderDesc | undefined;
+    collider: Collider | undefined;
+    custom: Record<string, any>;
+    debugInfo: Record<string, any>;
+    debugMaterial: ShaderMaterial | undefined;
+    lifeCycleDelegate: LifeCycleDelegate<O>;
+    collisionDelegate: CollisionDelegate<this, O>;
+    collisionType?: string;
+    behaviorCallbackMap: Record<BehaviorCallbackType, BehaviorCallback<this, O>[]>;
+    constructor();
+    create(): this;
+    onSetup(...callbacks: ((params: SetupContext<this>) => void)[]): this;
+    onUpdate(...callbacks: ((params: UpdateContext<this>) => void)[]): this;
+    onDestroy(...callbacks: ((params: DestroyContext<this>) => void)[]): this;
+    onCollision(...callbacks: ((params: CollisionContext<this, O>) => void)[]): this;
+    _setup(params: SetupContext<this>): void;
+    protected _loaded(_params: LoadedContext<this>): Promise<void>;
+    _update(params: UpdateContext<this>): void;
+    _destroy(params: DestroyContext<this>): void;
+    protected _cleanup(_params: CleanupContext<this>): Promise<void>;
+    _collision(other: GameEntity<O>, globals?: any): void;
+    addBehavior(behaviorCallback: ({
+        type: BehaviorCallbackType;
+        handler: any;
+    })): this;
+    addBehaviors(behaviorCallbacks: ({
+        type: BehaviorCallbackType;
+        handler: any;
+    })[]): this;
+    protected updateMaterials(params: any): void;
+    buildInfo(): Record<string, string>;
+}
+
+export { type AnalogState as A, type BehaviorCallbackType as B, type CleanupContext as C, type DestroyFunction as D, GameEntity as G, type InputGamepad as I, type LoadingEvent as L, type MaterialOptions as M, type SetupFunction as S, type TexturePath as T, type UpdateContext as U, type Vec3 as V, type Behavior as a, type UpdateFunction as b, type SetupContext as c, type DestroyContext as d, BaseNode as e, type InputPlayerNumber as f, type Inputs as g, type ButtonState as h, GameEntityLifeCycle as i, type IGame as j, type LoadedContext as k, type GameEntityOptions as l, type CollisionContext as m };

package/dist/entity-spawner-DNnLYnZq.d.ts

@@ -0,0 +1,11 @@
+import { Vector2 } from 'three';
+import { G as GameEntity } from './entity-bQElAdpo.js';
+import { a as Stage } from './stage-CrmY7V0i.js';
+
+interface EntitySpawner {
+    spawn: (stage: Stage, x: number, y: number) => Promise<GameEntity<any>>;
+    spawnRelative: (source: any, stage: Stage, offset?: Vector2) => Promise<any | void>;
+}
+declare function entitySpawner(factory: (x: number, y: number) => Promise<any> | GameEntity<any>): EntitySpawner;
+
+export { entitySpawner as e };

package/dist/main.d.ts

@@ -0,0 +1,135 @@
+import { G as Game } from './core-C2mjetAd.js';
+export { V as Vect3, Z as ZylemGameConfig, c as createGame, g as gameConfig, a as globalChange, b as globalChanges, d as variableChange, e as variableChanges, v as vessel } from './core-C2mjetAd.js';
+export { S as StageOptions, c as createStage } from './stage-CrmY7V0i.js';
+export { e as entitySpawner } from './entity-spawner-DNnLYnZq.js';
+export { P as PerspectiveType, a as Perspectives, c as camera } from './camera-Dk-fOVZE.js';
+export { ZylemBox, actor, box, plane, rect, sphere, sprite, text, zone } from './entities.js';
+import { U as UpdateContext, B as BehaviorCallbackType } from './entity-bQElAdpo.js';
+export { a as Behavior, L as LoadingEvent } from './entity-bQElAdpo.js';
+export { boundary2d, ricochet2DCollision, ricochet2DInBounds } from './behaviors.js';
+import { M as MoveableEntity } from './moveable-B_vyA6cw.js';
+export { m as makeMoveable, b as move, a as moveable, r as resetVelocity } from './moveable-B_vyA6cw.js';
+export { m as makeRotatable, a as makeTransformable, r as rotatable, b as rotateInDirection } from './transformable-CUhvyuYO.js';
+export { Howl } from 'howler';
+import * as three from 'three';
+export { three as THREE };
+import * as RAPIER from '@dimforge/rapier3d-compat';
+export { RAPIER };
+import 'bitecs';
+import 'three/addons/controls/OrbitControls.js';
+import 'three/examples/jsm/postprocessing/EffectComposer.js';
+
+interface MovementSequence2DStep {
+    name: string;
+    moveX?: number;
+    moveY?: number;
+    timeInSeconds: number;
+}
+interface MovementSequence2DOptions {
+    sequence: MovementSequence2DStep[];
+    loop?: boolean;
+}
+type MovementSequence2DCallback = (current: MovementSequence2DStep, index: number, ctx: UpdateContext<MoveableEntity>) => void;
+/**
+ * Behavior that sequences 2D movements over time.
+ * Each step sets linear velocity via `moveXY` for a duration, then advances.
+ * Defaults to looping when the end is reached.
+ */
+declare function movementSequence2D(opts: MovementSequence2DOptions, onStep?: MovementSequence2DCallback): {
+    type: BehaviorCallbackType;
+    handler: (ctx: UpdateContext<MoveableEntity>) => void;
+};
+
+declare function destroy(entity: any, globals?: any): void;
+
+/**
+ * Plays a ricochet sound effect when boundary collision occurs
+ */
+declare function ricochetSound(frequency?: number, duration?: number): void;
+
+/**
+ * Plays a ping-pong beep sound effect.
+ */
+declare function pingPongBeep(frequency?: number, duration?: number): void;
+
+/**
+ * Set a global value by path.
+ * @example setGlobal('score', 100)
+ * @example setGlobal('player.health', 50)
+ */
+declare function setGlobal(path: string, value: unknown): void;
+/**
+ * Create/initialize a global with a default value.
+ * Only sets the value if it doesn't already exist.
+ * Use this to ensure globals have initial values before game starts.
+ * @example createGlobal('score', 0)
+ * @example createGlobal('player.health', 100)
+ */
+declare function createGlobal<T>(path: string, defaultValue: T): T;
+/**
+ * Get a global value by path.
+ * @example getGlobal('score') // 100
+ * @example getGlobal<number>('player.health') // 50
+ */
+declare function getGlobal<T = unknown>(path: string): T | undefined;
+/**
+ * Subscribe to changes on a global value at a specific path.
+ * Returns an unsubscribe function.
+ * @example const unsub = onGlobalChange('score', (val) => console.log(val));
+ */
+declare function onGlobalChange<T = unknown>(path: string, callback: (value: T) => void): () => void;
+/**
+ * Subscribe to changes on multiple global paths.
+ * Callback fires when any of the paths change, receiving all current values.
+ * Returns an unsubscribe function.
+ * @example const unsub = onGlobalChanges(['score', 'lives'], ([score, lives]) => console.log(score, lives));
+ */
+declare function onGlobalChanges<T extends unknown[] = unknown[]>(paths: string[], callback: (values: T) => void): () => void;
+/**
+ * Get the entire globals object (read-only snapshot).
+ */
+declare function getGlobals<T = Record<string, unknown>>(): T;
+
+/**
+ * Set a variable on an object by path.
+ * @example setVariable(stage1, 'totalAngle', 0.5)
+ * @example setVariable(entity, 'enemy.count', 10)
+ */
+declare function setVariable(target: object, path: string, value: unknown): void;
+/**
+ * Create/initialize a variable with a default value on a target object.
+ * Only sets the value if it doesn't already exist.
+ * @example createVariable(stage1, 'totalAngle', 0)
+ * @example createVariable(entity, 'enemy.count', 10)
+ */
+declare function createVariable<T>(target: object, path: string, defaultValue: T): T;
+/**
+ * Get a variable from an object by path.
+ * @example getVariable(stage1, 'totalAngle') // 0.5
+ * @example getVariable<number>(entity, 'enemy.count') // 10
+ */
+declare function getVariable<T = unknown>(target: object, path: string): T | undefined;
+/**
+ * Subscribe to changes on a variable at a specific path for a target object.
+ * Returns an unsubscribe function.
+ * @example const unsub = onVariableChange(stage1, 'score', (val) => console.log(val));
+ */
+declare function onVariableChange<T = unknown>(target: object, path: string, callback: (value: T) => void): () => void;
+/**
+ * Subscribe to changes on multiple variable paths for a target object.
+ * Callback fires when any of the paths change, receiving all current values.
+ * Returns an unsubscribe function.
+ * @example const unsub = onVariableChanges(stage1, ['count', 'total'], ([count, total]) => console.log(count, total));
+ */
+declare function onVariableChanges<T extends unknown[] = unknown[]>(target: object, paths: string[], callback: (values: T) => void): () => void;
+
+declare class ZylemGameElement extends HTMLElement {
+    private _game;
+    private container;
+    constructor();
+    set game(game: Game<any>);
+    get game(): Game<any> | null;
+    disconnectedCallback(): void;
+}
+
+export { Game, ZylemGameElement, createGlobal, createVariable, destroy, getGlobal, getGlobals, getVariable, movementSequence2D, onGlobalChange, onGlobalChanges, onVariableChange, onVariableChanges, pingPongBeep, ricochetSound, setGlobal, setVariable };