@zylem/game-lib 0.3.14 → 0.3.15

package/README.md

@@ -2,6 +2,23 @@
 
 A powerful and easy-to-use framework for creating simple 3D digital interactive applications using TypeScript.
 
+**Why Zylem?**
+
+I wanted to build something easy to jump into and deploy while still only writing code (no complex game IDEs).
+
+**Who should use Zylem?**
+
+This library is intended for hobbyist developers who want to play with 3D web technologies to build a game.
+
+**What does Zylem do?**
+
+The goal is to give you tools to build simple 3D games. It's basically comprised of:
+
+- Rendering via ThreeJS with some capability to handle postprocessing built-in. [ThreeJS](https://threejs.org/)
+- Collision handling, triggers, and rigid body physics via RapierRS [RapierRS](https://rapier.rs/)
+- Game state management with Valtio [Valtio](https://valtio.dev/)
+- Simplified input handling (gamepad, keyboard, mouse)
+
 >Note: This project is still in alpha. There are unfinished features and some APIs that may change.
 
 ## Installation
@@ -49,17 +66,3 @@ makeMoveable(ball).onUpdate(({ entity, inputs }) => {
 
 game(ball).start();
 ```
-
-## Repository Governance
-
-### Conventional commits
-
-- `feat`: A new feature
-- `fix`: A bug fix
-- `docs`: Documentation only changes
-- `style`: Changes that do not affect the meaning of the code (white-space, formatting, missing semi-colons, etc)
-- `refactor`: A code change that neither fixes a bug nor adds a feature
-- `cleanup`: Removal of dead code, unused functionality, or code changes involving renaming
-- `perf`: A code change that improves performance
-- `test`: Adding missing or correcting existing tests
-- `build`: Changes that affect the build system or external dependencies (example scopes: vite, npm, typescript, etc)

package/dist/lib/actions/global-change.d.ts

@@ -10,3 +10,13 @@ export declare function globalChange<T = any>(key: string, callback: (value: T,
  * Usage: onUpdate(globalChanges(['p1Score','p2Score'], ([p1,p2]) => { ... }))
  */
 export declare function globalChanges<T = any>(keys: string[], callback: (values: T[], ctx: UpdateContext<any>) => void): (ctx: UpdateContext<any>) => void;
+/**
+ * Listen for a single stage variable change inside an onUpdate pipeline.
+ * Usage: onUpdate(variableChange('score', (value, ctx) => { ... }))
+ */
+export declare function variableChange<T = any>(key: string, callback: (value: T, ctx: UpdateContext<any>) => void): (ctx: UpdateContext<any>) => void;
+/**
+ * Listen for multiple stage variable changes; fires when any changes.
+ * Usage: onUpdate(variableChanges(['a','b'], ([a,b], ctx) => { ... }))
+ */
+export declare function variableChanges<T = any>(keys: string[], callback: (values: T[], ctx: UpdateContext<any>) => void): (ctx: UpdateContext<any>) => void;

package/dist/lib/collision/collision-builder.d.ts

@@ -1,5 +1,4 @@
 import { ColliderDesc, RigidBodyDesc } from "@dimforge/rapier3d-compat";
-import { PhysicsOptions } from "./physics";
 import { Vec3 } from "../core/vector";
 import { CollisionOptions } from "./collision";
 export declare function getOrCreateCollisionGroupId(type: string): number;
@@ -15,7 +14,6 @@ export declare class CollisionBuilder {
     gravity: Vec3;
     build(options: Partial<CollisionOptions>): [RigidBodyDesc, ColliderDesc];
     withCollision(collisionOptions: Partial<CollisionOptions>): this;
-    withPhysics(physicsOptions: Partial<PhysicsOptions>): this;
     collider(options: CollisionOptions): ColliderDesc;
     bodyDesc({ isDynamicBody }: {
         isDynamicBody?: boolean | undefined;

package/dist/lib/collision/collision-group.d.ts

@@ -1,5 +1,4 @@
 import { GameEntity } from '../entities/entity';
-import { CollisionContext } from '../entities/entity';
 /**
  * Configure an entity's collision groups to only collide with the specified types.
  * This uses Rapier's built-in collision group system for efficient filtering.
@@ -9,19 +8,3 @@ import { CollisionContext } from '../entities/entity';
  * @returns The entity for method chaining
  */
 export declare function collisionGroup<T extends GameEntity<any>>(entity: T, allowedTypes: string[]): T;
-/**
- * Legacy type definitions for backward compatibility
- * @deprecated Use the new collisionGroup function instead
- */
-export type CollisionCallback = (ctx: CollisionContext<any, any>) => void;
-export type CollisionGroupWrapper = (...actions: CollisionCallback[]) => CollisionCallback;
-/**
- * @deprecated This function is deprecated. Use the new collisionGroup function instead.
- */
-export declare function legacyCollisionGroup(...args: (string | GameEntity<any> | {
-    includeSameType?: boolean;
-})[]): CollisionGroupWrapper;
-/**
- * @deprecated This function is deprecated.
- */
-export declare function combineCollisionGroups(...wrappers: CollisionGroupWrapper[]): CollisionGroupWrapper;

package/dist/lib/core/lazy-loader.d.ts

@@ -24,7 +24,6 @@ export declare const loadGraphics: () => Promise<{
     mesh: typeof import("../graphics/mesh");
 }>;
 export declare const loadPhysics: () => Promise<{
-    physics: typeof import("../collision/physics");
     collision: typeof import("../collision/collision");
     collisionBuilder: typeof import("../collision/collision-builder");
 }>;
@@ -59,7 +58,6 @@ export declare const loadFullGame: () => Promise<{
         mesh: typeof import("../graphics/mesh");
     };
     physics: {
-        physics: typeof import("../collision/physics");
         collision: typeof import("../collision/collision");
         collisionBuilder: typeof import("../collision/collision-builder");
     };

package/dist/lib/core/preset-shader.d.ts

@@ -5,6 +5,7 @@ export type ZylemShaderObject = {
 export declare const starShader: ZylemShaderObject;
 export declare const fireShader: ZylemShaderObject;
 export declare const standardShader: ZylemShaderObject;
-export type ZylemShaderType = 'standard' | 'fire' | 'star';
+export declare const debugShader: ZylemShaderObject;
+export type ZylemShaderType = 'standard' | 'fire' | 'star' | 'debug';
 declare const shaderMap: Map<ZylemShaderType, ZylemShaderObject>;
 export default shaderMap;

package/dist/lib/entities/entity.d.ts

@@ -2,7 +2,6 @@ import { Mesh, Material, ShaderMaterial, Group, Color } from "three";
 import { Collider, ColliderDesc, RigidBody, RigidBodyDesc } from "@dimforge/rapier3d-compat";
 import { Vec3 } from "../core/vector";
 import { MaterialBuilder, MaterialOptions } from "../graphics/material";
-import { PhysicsOptions } from "../collision/physics";
 import { CollisionOptions } from "../collision/collision";
 import { BaseNode } from "../core/base-node";
 import { DestroyContext, SetupContext, UpdateContext } from "../core/base-node-life-cycle";
@@ -39,7 +38,6 @@ export type GameEntityOptions = {
     position?: Vec3;
     batched?: boolean;
     collision?: Partial<CollisionOptions>;
-    physics?: Partial<PhysicsOptions>;
     material?: Partial<MaterialOptions>;
     custom?: {
         [key: string]: any;

package/dist/lib/game/zylem-game.d.ts

@@ -22,6 +22,8 @@ export declare class ZylemGame<TGlobals extends Record<string, BasicTypes> = Glo
     statsRef: {
         begin: () => void;
         end: () => void;
+        showPanel: (panel: number) => void;
+        dom: HTMLElement;
     } | null;
     defaultCamera: ZylemCamera | null;
     static FRAME_LIMIT: number;

package/dist/lib/graphics/zylem-scene.d.ts

@@ -1,15 +1,15 @@
 import { Scene, Color, Object3D, Vector3 } from 'three';
 import { Entity } from '../interfaces/entity';
-import { SetupCallback } from '~/lib/interfaces/game';
 import { GameEntity } from '../entities/entity';
 import { ZylemCamera } from '../camera/zylem-camera';
+import { SetupFunction } from '../core/base-node-life-cycle';
 interface SceneState {
     backgroundColor: Color;
     backgroundImage: string | null;
 }
 export declare class ZylemScene implements Entity<ZylemScene> {
     type: string;
-    _setup?: SetupCallback;
+    _setup?: SetupFunction<ZylemScene>;
     scene: Scene;
     zylemCamera: ZylemCamera;
     containerElement: HTMLElement | null;

package/dist/lib/stage/stage-state.d.ts

@@ -8,5 +8,9 @@ declare const setStageBackgroundImage: (value: string | null) => void;
 declare const setEntitiesToStage: (entities: Partial<BaseEntityInterface>[]) => void;
 declare const setStageVariable: (key: string, value: any) => void;
 declare const getStageVariable: (key: string) => any;
+/** Replace the entire stage variables object (used on stage load). */
+declare const setStageVariables: (variables: Record<string, any>) => void;
+/** Reset all stage variables (used on stage unload). */
+declare const resetStageVariables: () => void;
 declare const stageStateToString: (state: StageStateInterface) => string;
-export { stageState, setStageState, setStageBackgroundColor, setStageBackgroundImage, setEntitiesToStage, stageStateToString, setStageVariable, getStageVariable, };
+export { stageState, setStageState, setStageBackgroundColor, setStageBackgroundImage, setEntitiesToStage, stageStateToString, setStageVariable, getStageVariable, setStageVariables, resetStageVariables, };

package/dist/lib/stage/stage.d.ts

@@ -24,7 +24,6 @@ export declare class Stage {
     onDestroy(callback: DestroyFunction<ZylemStage>): void;
     setVariable(key: string, value: any): void;
     getVariable(key: string): any;
-    watchVariable(key: string, callback: (value: any) => void): void;
 }
 /**
  * Create a stage with optional camera

package/dist/lib/stage/zylem-stage.d.ts

@@ -1,7 +1,6 @@
 import { Color, Vector3 } from 'three';
 import { ZylemWorld } from '../collision/world';
 import { ZylemScene } from '../graphics/zylem-scene';
-import { Conditions } from '../interfaces/game';
 import { GameEntityInterface } from '../types/entity-types';
 import { SetupContext, UpdateContext, DestroyContext } from '../core/base-node-life-cycle';
 import { LifeCycleBase } from '../core/lifecycle-base';
@@ -17,7 +16,6 @@ export interface ZylemStageConfig {
     backgroundImage: string | null;
     gravity: Vector3;
     variables: Record<string, any>;
-    conditions?: Conditions<any>[];
     stageRef?: Stage;
 }
 type NodeLike = {
@@ -44,7 +42,6 @@ export declare class ZylemStage extends LifeCycleBase<ZylemStage> {
     gravity: Vector3;
     world: ZylemWorld | null;
     scene: ZylemScene | null;
-    conditions: Conditions<any>[];
     children: Array<BaseNode>;
     _childrenMap: Map<number, BaseNode>;
     _removalMap: Map<number, BaseNode>;
@@ -85,6 +82,7 @@ export declare class ZylemStage extends LifeCycleBase<ZylemStage> {
     private createDefaultCamera;
     protected _setup(params: SetupContext<ZylemStage>): void;
     protected _update(params: UpdateContext<ZylemStage>): void;
+    outOfLoop(): void;
     /** Update debug overlays and helpers if enabled. */
     debugUpdate(): void;
     /** Cleanup owned resources when the stage is destroyed. */