@series-inc/rundot-3d-engine 0.3.0

package/LICENSE.txt

@@ -0,0 +1,6 @@
+By downloading, copying, or using this template, you agree to the
+RUN.game Terms of Service:
+
+https://policy.run.game/eula.html
+
+© Series Inc. All rights reserved.

package/README.md

@@ -0,0 +1,80 @@
+# Run.3DEngine
+
+A Three.js-based game engine with ECS architecture, physics, navigation, and comprehensive game systems.
+
+## Features
+
+- **ECS Architecture**: Component-based GameObject system
+- **Physics**: Rapier3D integration with RigidBody components
+- **Navigation**: Dynamic navigation system with A* pathfinding
+- **Animation**: Advanced animation system with blending and retargeting
+- **Audio**: 2D/3D audio system with music management
+- **UI**: Comprehensive UI system with utilities
+- **Camera**: Follow camera, free camera with smooth transitions
+- **Asset Loading**: FBX, GLB, OBJ loaders with skeleton caching
+- **Particles**: Flexible particle system
+- **Input**: Cross-platform input management with mobile support
+
+## Installation
+
+### As npm workspace dependency
+```json
+{
+  "dependencies": {
+    "@series-ai/rundot-3d-engine": "^0.2.0"
+  }
+}
+```
+
+### As git submodule
+```bash
+git submodule add https://github.com/series-ai/Run.3DEngine.git rundot-3D-engine
+git submodule update --init --recursive
+```
+
+## Usage
+
+```typescript
+import { VenusGame, GameObject, Component } from "@series-ai/rundot-3d-engine"
+import { PhysicsSystem, UISystem } from "@series-ai/rundot-3d-engine/systems"
+
+class MyGame extends VenusGame {
+  async onCreate(): Promise<void> {
+    // Initialize game
+  }
+  
+  async onStart(): Promise<void> {
+    // Start game logic
+  }
+}
+```
+
+## Dependencies
+
+- **three** ^0.180.0
+- **@dimforge/rapier3d** ^0.11.2
+- **@series-inc/rundot-game-sdk** 5.0.4
+- **@stowkit/reader** ^0.1.39
+- **@stowkit/three-loader** ^0.1.40
+
+## Development
+
+```bash
+# Install dependencies
+npm install
+
+# Build
+npm run build
+
+# Watch mode
+npm run dev
+
+# Lint
+npm run lint
+```
+
+## License
+
+See LICENSE file in root repository.
+
+

package/dist/ComponentRegistry-V_7WauAE.d.ts

@@ -0,0 +1,448 @@
+import * as THREE from 'three';
+import { RigidBody, Collider } from '@dimforge/rapier3d';
+
+/**
+ * Three.js version of GameObject
+ * Clean implementation without Babylon.js dependencies
+ */
+declare class GameObject extends THREE.Object3D {
+    private components;
+    private isDestroyed;
+    private static idCounter;
+    /**
+     * Create a new Three.js GameObject
+     * @param name Optional name for the GameObject. If not provided, an auto-generated name will be used.
+     */
+    constructor(name?: string);
+    /**
+     * Adds a component instance to the GameObject
+     * @returns The component instance
+     * @throws If component of same type already exists
+     */
+    addComponent<T extends Component>(component: T): T;
+    /**
+     * Gets a component of the specified type
+     * @returns The component if found, undefined otherwise
+     */
+    getComponent<T extends Component>(componentType: new (...args: any[]) => T): T | undefined;
+    /**
+     * Checks if the GameObject has a component of the specified type
+     */
+    hasComponent<T extends Component>(componentType: new (...args: any[]) => T): boolean;
+    /**
+     * Removes a component of the specified type
+     * @returns true if component was found and removed
+     */
+    removeComponent<T extends Component>(componentType: new (...args: any[]) => T): boolean;
+    /**
+     * Disposes of the GameObject and all its components
+     */
+    dispose(): void;
+    /**
+     * Get the Three.js scene the GameObject is in
+     */
+    getScene(): THREE.Scene;
+    /**
+     * Three.js equivalent of setEnabled - uses visible property
+     */
+    setEnabled(value: boolean): void;
+    /**
+     * Three.js equivalent of isEnabled - checks visible property AND parent hierarchy
+     */
+    isEnabled(): boolean;
+    /**
+     * Override THREE.Object3D.add() to handle enabled state propagation
+     * When adding a child to a disabled parent, the child should be effectively disabled too
+     */
+    add(...objects: THREE.Object3D[]): this;
+    /**
+     * Recursively notify all children that their enabled state may have changed
+     */
+    protected notifyChildrenEnabledStateChanged(): void;
+    /**
+     * Internal method to trigger enabled state change notifications
+     * This causes components to receive onEnabled/onDisabled callbacks
+     */
+    protected notifyEnabledStateChanged(isEnabled: boolean): void;
+}
+/**
+ * Three.js Component base class
+ * Clean implementation without Babylon.js dependencies
+ */
+declare abstract class Component {
+    protected gameObject: GameObject;
+    private _isAttached;
+    /**
+     * Get the GameObject this component is attached to
+     */
+    getGameObject(): GameObject;
+    /**
+     * Get the scene the GameObject is in
+     */
+    protected get scene(): THREE.Scene;
+    /**
+     * Attach this component to a GameObject
+     * @internal Called by GameObject.addComponent
+     */
+    attach(gameObject: GameObject): void;
+    /**
+     * Clean up this component
+     * @internal Called by GameObject when removing component
+     */
+    cleanup(): void;
+    /**
+     * Called when the component is first added to a GameObject
+     * Override this method to implement component initialization
+     */
+    protected onCreate(): void;
+    /**
+     * Called when the component is being removed/destroyed
+     * Override this method to implement component cleanup
+     */
+    protected onCleanup(): void;
+    /**
+     * Called when the GameObject becomes enabled
+     * Override this method to react to enable state changes
+     */
+    onEnabled(): void;
+    /**
+     * Called when the GameObject becomes disabled
+     * Override this method to react to enable state changes
+     */
+    onDisabled(): void;
+    /**
+     * Called every frame if the component's GameObject is enabled
+     * Override this method to implement per-frame logic
+     * @param deltaTime Time in seconds since last frame
+     */
+    update?(deltaTime: number): void;
+    /**
+     * Called every frame after all update() calls have completed
+     * Perfect for camera movement, UI updates, and anything that should happen last
+     * @param deltaTime Time in seconds since last frame
+     */
+    lateUpdate?(deltaTime: number): void;
+    /**
+     * Check if the component is attached to a GameObject
+     */
+    isAttached(): boolean;
+    /**
+     * Gets a component of the specified type from the same GameObject
+     * @returns The component if found, undefined otherwise
+     */
+    getComponent<T extends Component>(componentType: new (...args: any[]) => T): T | undefined;
+}
+
+/**
+ * Animation Culling Manager
+ * Handles frustum culling and distance-based optimization for animated characters
+ */
+declare class AnimationCullingManager {
+    private static instance;
+    private cameras;
+    private primaryCamera;
+    private readonly frustum;
+    private readonly projScreenMatrix;
+    private readonly _tempSphere;
+    private readonly _tempBox;
+    private readonly _tempVec;
+    private frustumCullingEnabled;
+    private distanceCullingEnabled;
+    private maxUpdateDistance;
+    private lodDistance;
+    private frustumExpansion;
+    private frameCounter;
+    private constructor();
+    static getInstance(): AnimationCullingManager;
+    /**
+     * Add a camera for frustum culling
+     */
+    addCamera(camera: THREE.Camera, isPrimary?: boolean): void;
+    /**
+     * Remove a camera from culling
+     */
+    removeCamera(camera: THREE.Camera): void;
+    /**
+     * Set the primary camera (used for distance calculations)
+     */
+    setPrimaryCamera(camera: THREE.Camera): void;
+    /**
+     * Enable/disable frustum culling
+     */
+    setFrustumCullingEnabled(enabled: boolean): void;
+    /**
+     * Enable/disable distance-based culling
+     */
+    setDistanceCullingEnabled(enabled: boolean): void;
+    /**
+     * Set the maximum distance for animation updates
+     */
+    setMaxUpdateDistance(distance: number): void;
+    /**
+     * Set the LOD distance threshold
+     */
+    setLodDistance(distance: number): void;
+    /**
+     * Set the frustum expansion factor.
+     * Values > 1.0 expand the frustum to avoid pop-in when characters enter view.
+     * Default is 1.2 (20% larger frustum)
+     */
+    setFrustumExpansion(factor: number): void;
+    /**
+     * Call once per frame before animation updates
+     */
+    beginFrame(): void;
+    /**
+     * Check if an object should have its animation updated this frame
+     * @param object The object containing the animated model
+     * @param boundingRadius Optional bounding radius for frustum check (default 2 units)
+     * @returns { shouldUpdate: boolean, isLod: boolean }
+     */
+    shouldUpdateAnimation(object: THREE.Object3D, boundingRadius?: number): {
+        shouldUpdate: boolean;
+        isLod: boolean;
+    };
+    /**
+     * Get debug stats
+     */
+    getStats(): {
+        cameraCount: number;
+        frustumCullingEnabled: boolean;
+        distanceCullingEnabled: boolean;
+        frameCounter: number;
+    };
+}
+
+declare enum RigidBodyType {
+    DYNAMIC = "dynamic",
+    STATIC = "static",
+    KINEMATIC = "kinematic"
+}
+declare enum ColliderShape {
+    BOX = "box",
+    SPHERE = "sphere",
+    CAPSULE = "capsule"
+}
+declare function createCollisionGroup(membership: number, filter: number): number;
+interface RigidBodyOptions {
+    type?: RigidBodyType;
+    shape?: ColliderShape;
+    size?: THREE.Vector3;
+    radius?: number;
+    height?: number;
+    mass?: number;
+    restitution?: number;
+    friction?: number;
+    isSensor?: boolean;
+    fitToMesh?: boolean;
+    centerOffset?: THREE.Vector3;
+    linearDamping?: number;
+    angularDamping?: number;
+    lockRotationX?: boolean;
+    lockRotationY?: boolean;
+    lockRotationZ?: boolean;
+    lockTranslationX?: boolean;
+    lockTranslationY?: boolean;
+    lockTranslationZ?: boolean;
+    enableCollisionEvents?: boolean;
+    collisionGroups?: number;
+}
+/**
+ * Simple component for adding Rapier physics to GameObjects
+ * Automatically syncs GameObject position with physics body
+ */
+declare class RigidBodyComponentThree extends Component {
+    private rigidBody;
+    private collider;
+    private options;
+    private bodyId;
+    private onTriggerEnterCallback;
+    private onTriggerExitCallback;
+    private isRegisteredWithPhysics;
+    constructor(options?: RigidBodyOptions);
+    protected onCreate(): void;
+    private createPhysicsBody;
+    /**
+     * Update syncs between GameObject and physics body based on rigidbody type
+     * - DYNAMIC: Physics drives GameObject position (physics simulation)
+     * - KINEMATIC: GameObject drives physics position (nav agents, scripts)
+     * - STATIC: No updates needed
+     */
+    update(_: number): void;
+    /**
+     * Apply force to the rigid body
+     */
+    applyForce(force: THREE.Vector3, point?: THREE.Vector3): void;
+    /**
+     * Apply impulse to the rigid body
+     */
+    applyImpulse(impulse: THREE.Vector3, point?: THREE.Vector3): void;
+    /**
+     * Set the velocity of the rigid body
+     */
+    setVelocity(velocity: THREE.Vector3): void;
+    /**
+     * Get linear velocity into the provided output vector (zero allocation)
+     */
+    getVelocity(out: THREE.Vector3): void;
+    /**
+     * Set angular velocity
+     */
+    setAngularVelocity(velocity: THREE.Vector3): void;
+    /**
+     * Get the rigid body for advanced operations
+     */
+    getRigidBody(): RigidBody | null;
+    /**
+     * Get the collider for advanced operations
+     */
+    getCollider(): Collider | null;
+    /**
+     * Enable/disable the rigid body
+     */
+    setEnabled(enabled: boolean): void;
+    /**
+     * Check if the rigid body is enabled
+     */
+    isEnabled(): boolean;
+    /**
+     * Get the unique body ID for this physics body
+     */
+    getBodyId(): string;
+    /**
+     * Register a callback for when objects enter this trigger
+     * @param callback Function to call when an object enters this trigger
+     */
+    registerOnTriggerEnter(callback: (other: any) => void): void;
+    /**
+     * Register a callback for when objects exit this trigger
+     * @param callback Function to call when an object exits this trigger
+     */
+    registerOnTriggerExit(callback: (other: any) => void): void;
+    /**
+     * Unregister trigger enter callback
+     */
+    unregisterOnTriggerEnter(): void;
+    /**
+     * Unregister trigger exit callback
+     */
+    unregisterOnTriggerExit(): void;
+    /**
+     * Called by physics system when an object enters this trigger
+     */
+    onTriggerEnter(other: any): void;
+    /**
+     * Called by physics system when an object exits this trigger
+     */
+    onTriggerExit(other: any): void;
+    /**
+     * Ensure this RigidBody is registered with physics system if it has any trigger callbacks
+     */
+    private ensureRegisteredWithPhysicsSystem;
+    /**
+     * Check if we should unregister from physics system (no more callbacks)
+     */
+    private checkIfShouldUnregisterFromPhysics;
+    /**
+     * Create a RigidBodyComponent from bounds size
+     * @param bounds The size vector from renderer.getBounds()
+     * @param options Physics options (size will be overridden by bounds)
+     * @returns A new RigidBodyComponentThree with bounds-fitted size
+     */
+    static fromBounds(bounds: THREE.Vector3, options?: Omit<RigidBodyOptions, "fitToMesh" | "size">): RigidBodyComponentThree;
+    /**
+     * Get the bounding box dimensions of all meshes in a GameObject hierarchy
+     * @param gameObject The GameObject to analyze
+     * @returns Vector3 containing width, height, depth of the combined mesh bounds
+     */
+    static getMeshBounds(gameObject: GameObject): THREE.Vector3;
+    /**
+     * Called when GameObject becomes enabled
+     */
+    onEnabled(): void;
+    getBounds(): THREE.Box3;
+    /**
+     * Called when GameObject becomes disabled
+     */
+    onDisabled(): void;
+    protected onCleanup(): void;
+}
+
+interface PrefabCollectionJSON {
+    prefabs: PrefabJSON[];
+}
+interface PrefabJSON {
+    schema: string;
+    version: number;
+    meta: {
+        name: string;
+        created: string;
+    };
+    mounts: PrefabMountJSON[];
+    root: PrefabNodeJSON;
+}
+interface PrefabMountJSON {
+    alias: string;
+    path: string;
+}
+interface TransformComponentJSON {
+    type: "transform";
+    position: number[];
+    rotation: number[];
+    scale: number[];
+    [key: string]: unknown;
+}
+interface PrefabComponentJSON {
+    type: string;
+    [key: string]: unknown;
+}
+interface PrefabNodeJSON {
+    name: string;
+    components?: PrefabComponentJSON[];
+    children?: PrefabNodeJSON[];
+}
+declare function isTransformComponent(c: PrefabComponentJSON): c is TransformComponentJSON;
+
+declare class PrefabNode {
+    static createFromJSON(json: PrefabNodeJSON): PrefabNode;
+    private readonly _name;
+    private readonly _transform;
+    private readonly _components;
+    private readonly _children;
+    private readonly _childByNameLookup;
+    private readonly _nodeByPathLookup;
+    constructor(name: string, transform: TransformComponentJSON, components: PrefabComponentJSON[], children: PrefabNode[]);
+    get name(): string;
+    get id(): string;
+    get transform(): TransformComponentJSON;
+    get components(): ReadonlyArray<PrefabComponentJSON>;
+    get children(): ReadonlyArray<PrefabNode>;
+    get position(): THREE.Vector3;
+    get rotation(): THREE.Euler;
+    get scale(): THREE.Vector3;
+    getChildByName(name: string): PrefabNode | undefined;
+    getNodeByPath(path: string): PrefabNode | undefined;
+    get descendants(): MapIterator<[string, PrefabNode]>;
+    depthFirstSearchForNode(nodeName: string): PrefabNode | undefined;
+    getComponentData<T extends PrefabComponentJSON>(type: string): T | undefined;
+    applyTransformTo(object: THREE.Object3D): void;
+    private mapDescendant;
+}
+
+type ComponentJSON = Record<string, unknown> & {
+    type: string;
+};
+interface PrefabComponentFactory {
+    fromPrefabJSON(json: ComponentJSON, node: PrefabNode): Component | null;
+}
+type PrefabComponentConstructor = (new (...args: any[]) => Component) & PrefabComponentFactory;
+declare class ComponentRegistryImpl {
+    private registry;
+    register(typeName: string, componentClass: PrefabComponentConstructor): void;
+    get(typeName: string): PrefabComponentConstructor | undefined;
+    has(typeName: string): boolean;
+    getRegisteredTypes(): string[];
+}
+declare const ComponentRegistry: ComponentRegistryImpl;
+
+export { AnimationCullingManager as A, Component as C, GameObject as G, PrefabNode as P, RigidBodyComponentThree as R, type TransformComponentJSON as T, type ComponentJSON as a, type PrefabComponentConstructor as b, type PrefabJSON as c, type PrefabCollectionJSON as d, RigidBodyType as e, ColliderShape as f, createCollisionGroup as g, type RigidBodyOptions as h, ComponentRegistry as i, type PrefabComponentFactory as j, type PrefabMountJSON as k, type PrefabComponentJSON as l, type PrefabNodeJSON as m, isTransformComponent as n };