@directivegames/genesys.js 3.1.24

package/dist/src/components/gameplay/Equipment.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Equipment interface describes components that can initiate primary and
+ * secondary fire actions, as well as reload functionality.
+ *
+ * It provides a minimal contract used by weapon components or other gameplay
+ * systems to trigger logic such as firing projectiles, activating abilities,
+ * or reloading ammunition.
+ * The helper function `isEquipment` performs a runtime check so scripts can
+ * safely interact with unknown objects.
+ *
+ * Recommended usage (for humans and AI assistants):
+ * - Implement this interface on components intended to be equipped by actors.
+ * - Use `isEquipment` before casting when interacting with external code.
+ */
+export interface IEquipment {
+    beginFire(): boolean;
+    endFire(): boolean;
+    beginAltFire(): boolean;
+    endAltFire(): boolean;
+    reload(): boolean;
+}
+export declare function isEquipment(object: any): object is IEquipment;

package/dist/src/components/gameplay/Equipment.js

@@ -0,0 +1,9 @@
+export function isEquipment(object) {
+    for (const name of ['beginFire', 'endFire', 'beginAltFire', 'endAltFire', 'reload']) {
+        if (typeof object[name] !== 'function') {
+            return false;
+        }
+    }
+    return true;
+}
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiRXF1aXBtZW50LmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vLi4vLi4vLi4vc3JjL2NvbXBvbmVudHMvZ2FtZXBsYXkvRXF1aXBtZW50LnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQXNCQSxNQUFNLFVBQVUsV0FBVyxDQUFDLE1BQVc7SUFDckMsS0FBSyxNQUFNLElBQUksSUFBSSxDQUFDLFdBQVcsRUFBRSxTQUFTLEVBQUUsY0FBYyxFQUFFLFlBQVksRUFBRSxRQUFRLENBQUMsRUFBRSxDQUFDO1FBQ3BGLElBQUksT0FBTyxNQUFNLENBQUMsSUFBSSxDQUFDLEtBQUssVUFBVSxFQUFFLENBQUM7WUFDdkMsT0FBTyxLQUFLLENBQUM7UUFDZixDQUFDO0lBQ0gsQ0FBQztJQUNELE9BQU8sSUFBSSxDQUFDO0FBQ2QsQ0FBQyJ9

package/dist/src/components/gameplay/GenericEquipment.d.ts

@@ -0,0 +1,37 @@
+/**
+ * GenericEquipment provides timing logic for fire actions used by weapon-like
+ * components.
+ *
+ * Extending SceneComponent, it tracks when firing starts and ensures repeated
+ * shots respect a configurable interval. Derived classes implement the
+ * `doFire` method to spawn projectiles or perform custom behavior each time a
+ * shot is triggered. The base class also handles single-fire modes where only
+ * one shot occurs per button press.
+ *
+ * Recommended usage (for humans and AI assistants):
+ * - Extend this class for common weapon behaviors that need rate limiting.
+ * - Override `doFire` to define the exact firing logic such as spawning
+ *   projectiles.
+ */
+import { SceneComponent } from '../SceneComponent.js';
+import type { SceneComponentOptions } from '../SceneComponent.js';
+import type { IEquipment } from './Equipment.js';
+export interface GenericEquipmentOptions extends SceneComponentOptions {
+    fireInterval: number;
+    isSingleFire: boolean;
+}
+export declare abstract class GenericEquipment<TOptions extends GenericEquipmentOptions> extends SceneComponent<TOptions> implements IEquipment {
+    private fireFlag;
+    private fireCount;
+    private lastFireTime;
+    static get DEFAULT_OPTIONS(): GenericEquipmentOptions;
+    constructor(options: TOptions);
+    beginFire(): boolean;
+    endFire(): boolean;
+    beginAltFire(): boolean;
+    endAltFire(): boolean;
+    reload(): boolean;
+    tickPrePhysics(deltaTime: number): void;
+    protected checkFire(): void;
+    protected abstract doFire(): void;
+}

package/dist/src/components/gameplay/GenericEquipment.js

@@ -0,0 +1,90 @@
+/**
+ * GenericEquipment provides timing logic for fire actions used by weapon-like
+ * components.
+ *
+ * Extending SceneComponent, it tracks when firing starts and ensures repeated
+ * shots respect a configurable interval. Derived classes implement the
+ * `doFire` method to spawn projectiles or perform custom behavior each time a
+ * shot is triggered. The base class also handles single-fire modes where only
+ * one shot occurs per button press.
+ *
+ * Recommended usage (for humans and AI assistants):
+ * - Extend this class for common weapon behaviors that need rate limiting.
+ * - Override `doFire` to define the exact firing logic such as spawning
+ *   projectiles.
+ */
+import { SceneComponent } from '../SceneComponent.js';
+export class GenericEquipment extends SceneComponent {
+    static get DEFAULT_OPTIONS() {
+        return {
+            ...SceneComponent.DEFAULT_OPTIONS,
+            fireInterval: 0.5,
+            isSingleFire: false,
+        };
+    }
+    constructor(options) {
+        super(options);
+        Object.defineProperty(this, "fireFlag", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: false
+        });
+        Object.defineProperty(this, "fireCount", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: 0
+        });
+        Object.defineProperty(this, "lastFireTime", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: 0
+        });
+    }
+    beginFire() {
+        this.fireFlag = true;
+        this.checkFire();
+        return true;
+    }
+    endFire() {
+        this.fireFlag = false;
+        return true;
+    }
+    beginAltFire() {
+        return false;
+    }
+    endAltFire() {
+        return false;
+    }
+    reload() {
+        return false;
+    }
+    tickPrePhysics(deltaTime) {
+        this.checkFire();
+    }
+    //====================================================================================================
+    checkFire() {
+        if (this.fireFlag) {
+            if (this.options.isSingleFire && this.fireCount > 0) {
+                return;
+            }
+            const currentTime = this.getWorld()?.getGameTime() ?? 0;
+            let fireTime = this.lastFireTime + this.options.fireInterval;
+            while (fireTime <= currentTime) {
+                if (!this.fireCount) {
+                    fireTime = currentTime;
+                }
+                this.fireCount++;
+                this.doFire();
+                this.lastFireTime = fireTime;
+                fireTime += this.options.fireInterval;
+            }
+        }
+        else {
+            this.fireCount = 0;
+        }
+    }
+}
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiR2VuZXJpY0VxdWlwbWVudC5qcyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uLy4uLy4uLy4uL3NyYy9jb21wb25lbnRzL2dhbWVwbGF5L0dlbmVyaWNFcXVpcG1lbnQudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IkFBQUE7Ozs7Ozs7Ozs7Ozs7O0dBY0c7QUFDSCxPQUFPLEVBQUUsY0FBYyxFQUFFLE1BQU0sc0JBQXNCLENBQUM7QUFZdEQsTUFBTSxPQUFnQixnQkFBMkQsU0FBUSxjQUF3QjtJQUsvRyxNQUFNLEtBQWMsZUFBZTtRQUNqQyxPQUFPO1lBQ0wsR0FBRyxjQUFjLENBQUMsZUFBZTtZQUNqQyxZQUFZLEVBQUUsR0FBRztZQUNqQixZQUFZLEVBQUUsS0FBSztTQUNwQixDQUFDO0lBQ0osQ0FBQztJQUVELFlBQVksT0FBaUI7UUFDM0IsS0FBSyxDQUFDLE9BQU8sQ0FBQyxDQUFDO1FBYlQ7Ozs7bUJBQW9CLEtBQUs7V0FBQztRQUMxQjs7OzttQkFBb0IsQ0FBQztXQUFDO1FBQ3RCOzs7O21CQUF1QixDQUFDO1dBQUM7SUFZakMsQ0FBQztJQUVNLFNBQVM7UUFDZCxJQUFJLENBQUMsUUFBUSxHQUFHLElBQUksQ0FBQztRQUNyQixJQUFJLENBQUMsU0FBUyxFQUFFLENBQUM7UUFDakIsT0FBTyxJQUFJLENBQUM7SUFDZCxDQUFDO0lBRU0sT0FBTztRQUNaLElBQUksQ0FBQyxRQUFRLEdBQUcsS0FBSyxDQUFDO1FBQ3RCLE9BQU8sSUFBSSxDQUFDO0lBQ2QsQ0FBQztJQUVNLFlBQVk7UUFDakIsT0FBTyxLQUFLLENBQUM7SUFDZixDQUFDO0lBRU0sVUFBVTtRQUNmLE9BQU8sS0FBSyxDQUFDO0lBQ2YsQ0FBQztJQUVNLE1BQU07UUFDWCxPQUFPLEtBQUssQ0FBQztJQUNmLENBQUM7SUFFZSxjQUFjLENBQUMsU0FBaUI7UUFDOUMsSUFBSSxDQUFDLFNBQVMsRUFBRSxDQUFDO0lBQ25CLENBQUM7SUFFRCxzR0FBc0c7SUFFNUYsU0FBUztRQUNqQixJQUFJLElBQUksQ0FBQyxRQUFRLEVBQUUsQ0FBQztZQUNsQixJQUFJLElBQUksQ0FBQyxPQUFPLENBQUMsWUFBWSxJQUFJLElBQUksQ0FBQyxTQUFTLEdBQUcsQ0FBQyxFQUFFLENBQUM7Z0JBQ3BELE9BQU87WUFDVCxDQUFDO1lBQ0QsTUFBTSxXQUFXLEdBQUcsSUFBSSxDQUFDLFFBQVEsRUFBRSxFQUFFLFdBQVcsRUFBRSxJQUFJLENBQUMsQ0FBQztZQUN4RCxJQUFJLFFBQVEsR0FBRyxJQUFJLENBQUMsWUFBWSxHQUFHLElBQUksQ0FBQyxPQUFPLENBQUMsWUFBWSxDQUFDO1lBQzdELE9BQU8sUUFBUSxJQUFJLFdBQVcsRUFBRSxDQUFDO2dCQUMvQixJQUFJLENBQUMsSUFBSSxDQUFDLFNBQVMsRUFBRSxDQUFDO29CQUNwQixRQUFRLEdBQUcsV0FBVyxDQUFDO2dCQUN6QixDQUFDO2dCQUNELElBQUksQ0FBQyxTQUFTLEVBQUUsQ0FBQztnQkFDakIsSUFBSSxDQUFDLE1BQU0sRUFBRSxDQUFDO2dCQUNkLElBQUksQ0FBQyxZQUFZLEdBQUcsUUFBUSxDQUFDO2dCQUM3QixRQUFRLElBQUksSUFBSSxDQUFDLE9BQU8sQ0FBQyxZQUFZLENBQUM7WUFDeEMsQ0FBQztRQUNILENBQUM7YUFBTSxDQUFDO1lBQ04sSUFBSSxDQUFDLFNBQVMsR0FBRyxDQUFDLENBQUM7UUFDckIsQ0FBQztJQUNILENBQUM7Q0FHRiJ9

package/dist/src/components/gameplay/InstantHitWeaponComponent.d.ts

@@ -0,0 +1,96 @@
+/**
+ * InstantHitWeaponComponent fires instant hit rays with configurable damage and effects.
+ *
+ * Built on top of BaseWeaponComponent, it performs raycast-based hit detection
+ * instead of spawning projectiles. When `doFire` is called, it immediately
+ * traces a ray from the weapon position to the target and applies damage or
+ * effects instantly. This is ideal for weapons like rifles, pistols, or laser
+ * weapons that have no travel time.
+ *
+ * Recommended usage (for humans and AI assistants):
+ * - Set `damage` to control how much damage the weapon deals.
+ * - Set `range` to limit the maximum effective distance.
+ * - Override `onHit` to customize hit effects like particle systems or decals.
+ * - Use `penetration` to allow shots to pass through multiple targets.
+ */
+import * as THREE from 'three';
+import { Delegate } from '../../utils/Delegate.js';
+import { BaseWeaponComponent } from './BaseWeaponComponent.js';
+import type { BaseWeaponOptions } from './BaseWeaponComponent.js';
+import type { Actor } from '../../actors/Actor.js';
+import type { HitTestResult } from '../../physics/PhysicsEngine.js';
+export interface InstantHitWeaponOptions extends BaseWeaponOptions {
+    /**
+     * Amount of damage dealt per hit.
+     */
+    damage: number;
+    /**
+     * Optional spread angle in radians for accuracy simulation.
+     * 0 means perfect accuracy.
+     */
+    spread?: number;
+}
+export interface HitInfo {
+    /**
+     * The actor that was hit.
+     */
+    hitActor: Actor | null;
+    /**
+     * The exact world position where the hit occurred.
+     */
+    hitLocation: THREE.Vector3;
+    /**
+     * The surface normal at the hit point.
+     */
+    hitNormal: THREE.Vector3;
+    /**
+     * The distance from the weapon to the hit point.
+     */
+    distance: number;
+    /**
+     * The damage dealt to the target.
+     */
+    damageDealt: number;
+}
+export type HitDelegate = Delegate<[HitInfo], void>;
+export type InstantHitWeaponDefaultOptions = BaseWeaponOptions & Partial<InstantHitWeaponOptions>;
+export declare class InstantHitWeaponComponent extends BaseWeaponComponent<InstantHitWeaponOptions> {
+    static get DEFAULT_OPTIONS(): InstantHitWeaponDefaultOptions;
+    readonly onHit: HitDelegate;
+    constructor(options: InstantHitWeaponOptions);
+    protected doFire(): void;
+    /**
+     * Applies random spread to the fire direction for accuracy simulation.
+     * @param direction The base fire direction
+     * @param spreadAngle The maximum spread angle in radians
+     * @returns The direction with applied spread
+     */
+    protected applySpread(direction: THREE.Vector3, spreadAngle: number): THREE.Vector3;
+    /**
+     * Performs the instant hit raycast and handles hit results.
+     * @param origin The starting position of the ray
+     * @param direction The direction of the ray
+     */
+    protected performInstantHit(origin: THREE.Vector3, direction: THREE.Vector3): void;
+    /**
+     * Processes a single hit result and applies damage/effects.
+     * @param hitResult The hit test result
+     * @param fireOrigin The original fire position for distance calculation
+     */
+    protected processHit(hitResult: HitTestResult, fireOrigin: THREE.Vector3): void;
+    /**
+     * Applies damage to the target actor.
+     * Override this method to customize damage application logic.
+     * @param target The actor to damage
+     * @param damage The amount of damage to apply
+     * @param hitInfo The hit test result
+     */
+    protected applyDamage(target: Actor, damage: number, hitInfo: HitTestResult): void;
+    /**
+     * Plays visual hit effects at the hit location.
+     * Override this method to customize hit effects.
+     * @param hitInfo Information about the hit
+     */
+    protected playHitEffect(hitInfo: HitInfo): void;
+    getEditorClassIcon(): string | null;
+}

package/dist/src/components/gameplay/InstantHitWeaponComponent.js

@@ -0,0 +1,194 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+/**
+ * InstantHitWeaponComponent fires instant hit rays with configurable damage and effects.
+ *
+ * Built on top of BaseWeaponComponent, it performs raycast-based hit detection
+ * instead of spawning projectiles. When `doFire` is called, it immediately
+ * traces a ray from the weapon position to the target and applies damage or
+ * effects instantly. This is ideal for weapons like rifles, pistols, or laser
+ * weapons that have no travel time.
+ *
+ * Recommended usage (for humans and AI assistants):
+ * - Set `damage` to control how much damage the weapon deals.
+ * - Set `range` to limit the maximum effective distance.
+ * - Override `onHit` to customize hit effects like particle systems or decals.
+ * - Use `penetration` to allow shots to pass through multiple targets.
+ */
+import * as THREE from 'three';
+import { EngineClass } from '../../systems/ClassRegistry.js';
+import { Delegate } from '../../utils/Delegate.js';
+import { CharacterStatsComponent } from '../CharacterStatsComponent.js';
+import { EmissionShape, ParticleEmitterComponent } from '../visual/ParticleEmitterComponent.js';
+import { BaseWeaponComponent } from './BaseWeaponComponent.js';
+let InstantHitWeaponComponent = class InstantHitWeaponComponent extends BaseWeaponComponent {
+    static get DEFAULT_OPTIONS() {
+        return {
+            ...BaseWeaponComponent.DEFAULT_OPTIONS,
+            damage: 25,
+            spread: 0,
+        };
+    }
+    constructor(options) {
+        super(options);
+        Object.defineProperty(this, "onHit", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: new Delegate()
+        });
+    }
+    doFire() {
+        // Guard against firing without ammo
+        if (!this.canFire()) {
+            return;
+        }
+        const { position, direction } = this.getFirePositionAndDirection();
+        let fireDirection = direction.clone();
+        // Apply target direction if available
+        const targetDirection = this.getTargetDirection();
+        if (targetDirection) {
+            fireDirection = targetDirection;
+        }
+        // Apply spread for accuracy simulation
+        if (this.options.spread && this.options.spread > 0) {
+            fireDirection = this.applySpread(fireDirection, this.options.spread);
+        }
+        // Perform the instant hit trace
+        this.performInstantHit(position, fireDirection);
+        // Handle weapon effects and ammo
+        this.consumeAmmo();
+        this.playFireSound();
+        this.applyRecoilEffects();
+    }
+    /**
+     * Applies random spread to the fire direction for accuracy simulation.
+     * @param direction The base fire direction
+     * @param spreadAngle The maximum spread angle in radians
+     * @returns The direction with applied spread
+     */
+    applySpread(direction, spreadAngle) {
+        // Create a random offset within a cone
+        const phi = Math.random() * Math.PI * 2; // Random angle around the direction
+        const theta = Math.random() * spreadAngle; // Random angle from center up to max spread
+        // Convert spherical coordinates to cartesian offset
+        const x = Math.sin(theta) * Math.cos(phi);
+        const y = Math.sin(theta) * Math.sin(phi);
+        const z = Math.cos(theta);
+        // Create a coordinate system based on the fire direction
+        const up = new THREE.Vector3(0, 1, 0);
+        const right = new THREE.Vector3().crossVectors(direction, up).normalize();
+        const forward = direction.clone().normalize();
+        up.crossVectors(right, forward).normalize();
+        // Apply the spread offset
+        const spreadDirection = new THREE.Vector3()
+            .addScaledVector(right, x)
+            .addScaledVector(up, y)
+            .addScaledVector(forward, z)
+            .normalize();
+        return spreadDirection;
+    }
+    /**
+     * Performs the instant hit raycast and handles hit results.
+     * @param origin The starting position of the ray
+     * @param direction The direction of the ray
+     */
+    performInstantHit(origin, direction) {
+        const world = this.getWorld();
+        const actor = this.getActor();
+        if (!world || !actor) {
+            return;
+        }
+        const maxDistance = this.options.range ?? 1000;
+        // Perform raycast hit test
+        const hitResults = this.getPhysicsEngine()?.performHitTest({
+            origin: origin,
+            direction: direction,
+            maxDistance: maxDistance,
+            stopOnFirstHit: true,
+            ignoredActors: [actor],
+        });
+        for (const hitResult of hitResults ?? []) {
+            this.processHit(hitResult, origin);
+        }
+    }
+    /**
+     * Processes a single hit result and applies damage/effects.
+     * @param hitResult The hit test result
+     * @param fireOrigin The original fire position for distance calculation
+     */
+    processHit(hitResult, fireOrigin) {
+        const hitInfo = {
+            hitActor: hitResult.hitActor ?? null,
+            hitLocation: hitResult.hitLocation.clone(),
+            hitNormal: hitResult.hitNormal.clone(),
+            distance: fireOrigin.distanceTo(hitResult.hitLocation),
+            damageDealt: this.options.damage,
+        };
+        // Apply damage to the hit actor if it has a health component
+        if (hitResult.hitActor && this.options.damage > 0) {
+            this.applyDamage(hitResult.hitActor, this.options.damage, hitResult);
+        }
+        // Show hit effects if enabled
+        this.playHitEffect(hitInfo);
+        // Emit hit event
+        this.onHit.invoke(hitInfo);
+    }
+    /**
+     * Applies damage to the target actor.
+     * Override this method to customize damage application logic.
+     * @param target The actor to damage
+     * @param damage The amount of damage to apply
+     * @param hitInfo The hit test result
+     */
+    applyDamage(target, damage, hitInfo) {
+        const statsComponent = target.getComponent(CharacterStatsComponent);
+        statsComponent?.takeDamage(damage, {
+            hitLocation: hitInfo.hitLocation.clone(),
+            hitNormal: hitInfo.hitNormal.clone(),
+        });
+    }
+    /**
+     * Plays visual hit effects at the hit location.
+     * Override this method to customize hit effects.
+     * @param hitInfo Information about the hit
+     */
+    playHitEffect(hitInfo) {
+        const world = this.getWorld();
+        if (!world) {
+            return;
+        }
+        // Simple spark shower effect based on VFX demo implementation
+        const sparkShower = new ParticleEmitterComponent({
+            position: hitInfo.hitLocation.clone(),
+            particleCount: 50,
+            particleSize: 0.15,
+            particleColor: new THREE.Color(0xffdd00), // Bright yellow sparks
+            particleSpeed: 10,
+            particleLifetime: 0.3,
+            emitterRate: 1000, // Very high rate for quick burst
+            emitContinuously: true, // Allow continuous emission like VFX demo
+            emissionShape: EmissionShape.Sphere,
+        });
+        world.globalParticleManager.attachParticleEmitter(sparkShower);
+    }
+    //====================================================================================================
+    // Editor Functions
+    //====================================================================================================
+    getEditorClassIcon() {
+        return 'Icon_InstantHitWeapon';
+    }
+};
+InstantHitWeaponComponent = __decorate([
+    EngineClass('InstantHitWeaponComponent'),
+    __metadata("design:paramtypes", [Object])
+], InstantHitWeaponComponent);
+export { InstantHitWeaponComponent };
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiSW5zdGFudEhpdFdlYXBvbkNvbXBvbmVudC5qcyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uLy4uLy4uLy4uL3NyYy9jb21wb25lbnRzL2dhbWVwbGF5L0luc3RhbnRIaXRXZWFwb25Db21wb25lbnQudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6Ijs7Ozs7Ozs7O0FBQUE7Ozs7Ozs7Ozs7Ozs7O0dBY0c7QUFDSCxPQUFPLEtBQUssS0FBSyxNQUFNLE9BQU8sQ0FBQztBQUUvQixPQUFPLEVBQUUsV0FBVyxFQUFFLE1BQU0sZ0NBQWdDLENBQUM7QUFDN0QsT0FBTyxFQUFFLFFBQVEsRUFBRSxNQUFNLHlCQUF5QixDQUFDO0FBQ25ELE9BQU8sRUFBRSx1QkFBdUIsRUFBRSxNQUFNLCtCQUErQixDQUFDO0FBQ3hFLE9BQU8sRUFBRSxhQUFhLEVBQUUsd0JBQXdCLEVBQUUsTUFBTSx1Q0FBdUMsQ0FBQztBQUVoRyxPQUFPLEVBQUUsbUJBQW1CLEVBQUUsTUFBTSwwQkFBMEIsQ0FBQztBQThDeEQsSUFBTSx5QkFBeUIsR0FBL0IsTUFBTSx5QkFBMEIsU0FBUSxtQkFBNEM7SUFDekYsTUFBTSxLQUFjLGVBQWU7UUFDakMsT0FBTztZQUNMLEdBQUcsbUJBQW1CLENBQUMsZUFBZTtZQUN0QyxNQUFNLEVBQUUsRUFBRTtZQUNWLE1BQU0sRUFBRSxDQUFDO1NBQ1YsQ0FBQztJQUNKLENBQUM7SUFJRCxZQUFZLE9BQWdDO1FBQzFDLEtBQUssQ0FBQyxPQUFPLENBQUMsQ0FBQztRQUhEOzs7O21CQUFxQixJQUFJLFFBQVEsRUFBbUI7V0FBQztJQUlyRSxDQUFDO0lBRVMsTUFBTTtRQUNkLG9DQUFvQztRQUNwQyxJQUFJLENBQUMsSUFBSSxDQUFDLE9BQU8sRUFBRSxFQUFFLENBQUM7WUFDcEIsT0FBTztRQUNULENBQUM7UUFFRCxNQUFNLEVBQUUsUUFBUSxFQUFFLFNBQVMsRUFBRSxHQUFHLElBQUksQ0FBQywyQkFBMkIsRUFBRSxDQUFDO1FBQ25FLElBQUksYUFB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

package/dist/src/components/gameplay/PickupComponent.d.ts

@@ -0,0 +1,130 @@
+/**
+ * PickupComponent provides pickup functionality for actors with trigger physics components.
+ *
+ * This component automatically finds trigger-enabled SceneComponents on its actor and
+ * sets up collision detection for pickup interactions. It includes support for sound
+ * effects when collected and provides extensible pickup behavior through delegates
+ * and virtual methods.
+ *
+ * Key Features:
+ * - Automatic trigger component detection (requires isTrigger=true physics state)
+ * - Sound effect support with configurable volume and distance
+ * - Delegate-based event system (onPickup) for external handling
+ * - Extensible pickup logic through canPickup and onPickupInternal overrides
+ * - Built-in actor destruction after pickup
+ *
+ * Included Classes:
+ * - PickupComponent: Base pickup functionality with sound support
+ * - HealthPickupComponent: Specialized pickup that heals CharacterStatsComponent
+ * - PickupSpawnerComponent: Automated spawning system with configurable intervals
+ *
+ * Recommended usage (for humans and AI assistants):
+ * - Attach to an actor that has a SceneComponent with physics enabled
+ * - Ensure the physics component has isTrigger: true and generateCollisionEvents: true
+ * - Override canPickup and onPickupInternal methods for custom pickup behavior
+ * - Use HealthPickupComponent for health restoration functionality
+ * - Use PickupSpawnerComponent for automatic pickup respawning
+ */
+import * as THREE from 'three';
+import * as ENGINE from '../../index.js';
+import { Delegate } from '../../utils/Delegate.js';
+import { PrimitiveComponent } from '../PrimitiveComponent.js';
+import { SceneComponent } from '../SceneComponent.js';
+import type { EditorClassMeta } from '../../utils/EditorClassMeta.js';
+import type { SceneComponentOptions } from '../SceneComponent.js';
+export interface PickupComponentOptions extends SceneComponentOptions {
+    /** Sound configuration */
+    sound?: {
+        /** URL to the pickup sound file */
+        pickupSoundUrl?: string;
+        /** Volume of the pickup sound (0.0 to 1.0) */
+        volume?: number;
+        /** Maximum distance for the pickup sound */
+        maxDistance?: number;
+    };
+}
+export declare class PickupComponent extends SceneComponent<PickupComponentOptions> {
+    private pickupSoundUrl;
+    protected triggerComponent: PrimitiveComponent | null;
+    /** Delegate called when this pickup is collected */
+    readonly onPickup: Delegate<[ENGINE.Actor, ENGINE.Actor], void>;
+    static readonly EDITOR_CLASS_META: EditorClassMeta;
+    static get DEFAULT_OPTIONS(): PickupComponentOptions;
+    constructor(options?: PickupComponentOptions);
+    beginPlay(): void;
+    protected findTriggerComponent(): void;
+    /**
+     * Determines if the pickup can be collected by the given actor
+     * Override this method in subclasses to implement custom pickup logic
+     * @param actor The actor attempting to pick up this item
+     * @returns True if the actor can pick up this item
+     */
+    protected canPickup(actor: ENGINE.Actor): boolean;
+    /**
+     * Internal method that handles the pickup process
+     * @param collector The actor that collected this pickup
+     */
+    private handlePickup;
+    /**
+     * Called when the pickup is collected
+     * Override this method in subclasses to implement custom pickup behavior
+     * @param collector The actor that collected this pickup
+     */
+    protected onPickupInternal(collector: ENGINE.Actor): void;
+    getEditorClassIcon(): string | null;
+}
+export interface HealthPickupComponentOptions extends PickupComponentOptions {
+    /** Amount of health to restore when picked up */
+    healAmount?: number;
+}
+export declare class HealthPickupComponent extends PickupComponent {
+    private healAmount;
+    static get DEFAULT_OPTIONS(): HealthPickupComponentOptions;
+    constructor(options?: HealthPickupComponentOptions);
+    /**
+     * Override to ensure only Pawns with CharacterStatsComponent can pick up health
+     */
+    protected canPickup(actor: ENGINE.Actor): boolean;
+    /**
+     * Override to heal the player when picked up
+     */
+    protected onPickupInternal(collector: ENGINE.Actor): void;
+    getEditorClassIcon(): string | null;
+}
+export interface PickupSpawnerComponentOptions extends SceneComponentOptions {
+    /** Path to the prefab to spawn */
+    prefabPath?: string;
+    /** Spawn interval in seconds. If negative, only spawns once */
+    spawnInterval?: number;
+    /** Offset position relative to the spawner where pickups should appear */
+    spawnOffset?: THREE.Vector3;
+    /** Sound configuration for spawning */
+    sound?: {
+        /** URL to the spawn sound file */
+        spawnSoundUrl?: string;
+        /** Volume of the spawn sound (0.0 to 1.0) */
+        volume?: number;
+        /** Maximum distance for the spawn sound */
+        maxDistance?: number;
+    };
+}
+export declare class PickupSpawnerComponent extends SceneComponent<PickupSpawnerComponentOptions> {
+    private currentPickup;
+    private spawnTimerId;
+    static readonly EDITOR_CLASS_META: EditorClassMeta;
+    static get DEFAULT_OPTIONS(): PickupSpawnerComponentOptions;
+    constructor(options?: PickupSpawnerComponentOptions);
+    beginPlay(): void;
+    endPlay(): void;
+    private spawnPickup;
+    private onPickupCollected;
+    /**
+     * Manually trigger a pickup spawn (if no pickup is currently active)
+     */
+    manualSpawn(): void;
+    /**
+     * Get the currently spawned pickup actor
+     */
+    getCurrentPickup(): ENGINE.Actor | null;
+    getEditorClassIcon(): string | null;
+}