@nodemod/core 1.0.0

package/dist/core/sound.js

@@ -0,0 +1,300 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SoundChannel = void 0;
+/**
+ * Audio channel constants for categorizing sounds.
+ */
+exports.SoundChannel = {
+    /** Automatically select appropriate channel */
+    auto: 0,
+    /** Weapon sounds */
+    weapon: 1,
+    /** Voice communications */
+    voice: 2,
+    /** Item interaction sounds */
+    item: 3,
+    /** Body/movement sounds */
+    body: 4,
+    /** Streaming audio */
+    stream: 5,
+    /** Static/ambient sounds */
+    static: 6,
+    /** Network voice communication base */
+    networkVoiceBase: 7,
+    /** Network voice communication end */
+    networkVoiceEnd: 500
+};
+/**
+ * Enhanced sound system providing comprehensive audio functionality for the game server.
+ * Handles sound emission, validation, and management with improved defaults and error handling.
+ *
+ * @example
+ * ```typescript
+ * // Play a weapon sound
+ * nodemodCore.sound.emitSound({
+ *   entity: player,
+ *   channel: SoundChannel.weapon,
+ *   sound: 'weapons/ak47/ak47-1.wav',
+ *   volume: 0.8,
+ *   pitch: 110
+ * });
+ *
+ * // Broadcast ambient sound to all players
+ * nodemodCore.sound.broadcastSound('ambient/music/track1.wav', {
+ *   volume: 0.5,
+ *   attenuation: 0.5
+ * });
+ *
+ * // Play client-side sound command
+ * nodemodCore.sound.emitClientSound(player, 'ui/buttonclick');
+ * ```
+ */
+class NodemodSound {
+    /** Utility service for entity operations */
+    util;
+    /**
+     * Creates a new NodemodSound instance.
+     *
+     * @param utilService - Utility service for entity operations
+     */
+    constructor(utilService) {
+        this.util = utilService;
+    }
+    /**
+     * Emits a sound with enhanced validation and default values.
+     * Provides better parameter validation and clamping than the basic engine function.
+     *
+     * @param options - Sound emission configuration
+     * @returns True if sound was emitted successfully, false otherwise
+     *
+     * @example
+     * ```typescript
+     * // Basic sound emission
+     * nodemodCore.sound.emitSound({
+     *   sound: 'weapons/ak47/ak47-1.wav'
+     * });
+     *
+     * // Advanced sound with all options
+     * nodemodCore.sound.emitSound({
+     *   entity: player,
+     *   channel: SoundChannel.weapon,
+     *   sound: 'weapons/ak47/ak47-1.wav',
+     *   volume: 0.8,
+     *   attenuation: 1.5,
+     *   flags: 0, // Normal playback
+     *   pitch: 110
+     * });
+     * ```
+     */
+    emitSound(options) {
+        const { entity = 0, channel = exports.SoundChannel.auto, sound, volume = 1.0, attenuation = 1.0, flags = 0, pitch = 100 } = options;
+        if (!sound) {
+            console.error('NodemodSound.emitSound: sound parameter is required');
+            return false;
+        }
+        const entityObj = entity ? this.util.forceEntityObject(entity) : nodemod.eng.pEntityOfEntIndex(0);
+        nodemod.eng.emitSound(entityObj, channel, sound, Math.max(0, Math.min(1, volume)), // Clamp volume 0-1
+        Math.max(0, attenuation), flags, Math.max(1, Math.min(255, pitch)) // Clamp pitch 1-255
+        );
+        return true;
+    }
+    /**
+     * Sends a client-side sound command to a specific player.
+     * Uses the client's `spk` command to play sounds locally.
+     *
+     * @param entity - Target player entity or index
+     * @param soundName - Name of the sound file (with or without extension)
+     * @param extension - File extension to append if not present in soundName
+     * @returns True if command was sent successfully, false otherwise
+     *
+     * @example
+     * ```typescript
+     * // Play UI sound to player
+     * nodemodCore.sound.emitClientSound(player, 'ui/buttonclick');
+     *
+     * // Play custom sound with specific extension
+     * nodemodCore.sound.emitClientSound(player, 'custom/notification', 'mp3');
+     * ```
+     */
+    emitClientSound(entity, soundName, extension = 'wav') {
+        const entityObj = this.util.forceEntityObject(entity);
+        if (!entityObj) {
+            console.error('NodemodSound.emitClientSound: invalid entity');
+            return false;
+        }
+        const soundPath = soundName.includes('.') ? soundName : `${soundName}.${extension}`;
+        nodemod.eng.clientCommand(entityObj, `spk sound/${soundPath}\n`);
+        return true;
+    }
+    /**
+     * Emits an ambient sound at a specific 3D position.
+     * Useful for environmental sounds, explosions, or location-based audio.
+     *
+     * @param position - 3D coordinates [x, y, z] where the sound originates
+     * @param sound - Path to the sound file
+     * @param volume - Volume level (0.0 to 1.0)
+     * @param attenuation - How quickly sound fades with distance
+     * @param flags - Sound transmission flags
+     * @param pitch - Pitch adjustment (1-255, 100 = normal)
+     * @returns True if sound was emitted successfully, false otherwise
+     *
+     * @example
+     * ```typescript
+     * // Explosion sound at coordinates
+     * nodemodCore.sound.emitAmbientSound(
+     *   [100, 200, 50],
+     *   'weapons/explode1.wav',
+     *   0.9,
+     *   2.0
+     * );
+     *
+     * // Ambient environmental sound
+     * nodemodCore.sound.emitAmbientSound(
+     *   [0, 0, 0],
+     *   'ambient/wind/wind1.wav',
+     *   0.3,
+     *   0.5,
+     *   nodemod.SND.SPAWNING
+     * );
+     * ```
+     */
+    emitAmbientSound(position, sound, volume = 1.0, attenuation = 1.0, flags = 0, pitch = 100) {
+        if (!sound || !Array.isArray(position) || position.length < 3) {
+            console.error('NodemodSound.emitAmbientSound: invalid parameters');
+            return false;
+        }
+        nodemod.eng.emitAmbientSound(null, // entity parameter - using null for ambient sounds
+        position, sound, Math.max(0, Math.min(1, volume)), Math.max(0, attenuation), flags, Math.max(1, Math.min(255, pitch)));
+        return true;
+    }
+    /**
+     * Broadcasts a sound to all players on the server.
+     * Convenient wrapper for playing sounds that everyone should hear.
+     *
+     * @param sound - Path to the sound file
+     * @param options - Optional sound configuration overrides
+     * @returns True if sound was broadcast successfully, false otherwise
+     *
+     * @example
+     * ```typescript
+     * // Simple server announcement sound
+     * nodemodCore.sound.broadcastSound('admin/announcement.wav');
+     *
+     * // Round start music with custom settings
+     * nodemodCore.sound.broadcastSound('music/roundstart.wav', {
+     *   volume: 0.7,
+     *   channel: SoundChannel.stream,
+     *   attenuation: 0.1
+     * });
+     * ```
+     */
+    broadcastSound(sound, options = {}) {
+        const soundOptions = {
+            entity: 0, // World entity
+            channel: exports.SoundChannel.auto,
+            sound,
+            volume: 1.0,
+            attenuation: 1.0,
+            flags: 0,
+            pitch: 100,
+            ...options
+        };
+        return this.emitSound(soundOptions);
+    }
+    /**
+     * Attempts to stop a sound on a specific entity.
+     * Uses a workaround by playing a very quiet sound since direct stop may not be available.
+     *
+     * @param entity - Target entity or entity index
+     * @param channel - Audio channel to stop
+     * @param sound - Specific sound to stop (empty for all sounds on channel)
+     * @returns True if stop attempt was successful, false otherwise
+     *
+     * @example
+     * ```typescript
+     * // Stop all sounds on entity
+     * nodemodCore.sound.stopSound(player);
+     *
+     * // Stop weapon channel sounds
+     * nodemodCore.sound.stopSound(player, SoundChannel.weapon);
+     * ```
+     */
+    stopSound(entity, channel = exports.SoundChannel.auto, sound = '') {
+        const entityObj = this.util.forceEntityObject(entity);
+        if (!entityObj)
+            return false;
+        // Fallback: emit very quiet sound to "override" since stopSound may not be available
+        return this.emitSound({
+            entity: entityObj,
+            channel,
+            sound: sound || 'common/null.wav',
+            volume: 0.001,
+            pitch: 1
+        });
+    }
+    /**
+     * Validates whether a sound file path is valid.
+     * Checks for supported file extensions and proper format.
+     *
+     * @param soundPath - Path to the sound file to validate
+     * @returns True if the sound path is valid, false otherwise
+     *
+     * @example
+     * ```typescript
+     * // Valid sound files
+     * console.log(nodemodCore.sound.isValidSound('weapons/ak47-1.wav')); // true
+     * console.log(nodemodCore.sound.isValidSound('music/track.mp3')); // true
+     *
+     * // Invalid sound files
+     * console.log(nodemodCore.sound.isValidSound('invalid.txt')); // false
+     * console.log(nodemodCore.sound.isValidSound('')); // false
+     * ```
+     */
+    isValidSound(soundPath) {
+        if (!soundPath || typeof soundPath !== 'string')
+            return false;
+        const validExtensions = ['wav', 'mp3'];
+        const extension = soundPath.split('.').pop()?.toLowerCase();
+        return extension ? validExtensions.includes(extension) : false;
+    }
+    /**
+     * Emits multiple sounds in batch with individual result tracking.
+     * Useful for playing multiple sounds simultaneously or handling bulk operations.
+     *
+     * @param soundConfigs - Array of sound configurations to emit
+     * @returns Array of results indicating success/failure for each sound
+     *
+     * @example
+     * ```typescript
+     * const sounds = [
+     *   { sound: 'weapons/ak47/ak47-1.wav', entity: player1, volume: 0.8 },
+     *   { sound: 'weapons/deagle/deagle-1.wav', entity: player2, volume: 0.9 },
+     *   { sound: 'items/ammopickup2.wav', volume: 0.5 }
+     * ];
+     *
+     * const results = nodemodCore.sound.emitMultipleSounds(sounds);
+     * results.forEach((result, i) => {
+     *   if (result.success) {
+     *     console.log(`Sound ${i} played successfully`);
+     *   } else {
+     *     console.log(`Sound ${i} failed: ${result.error}`);
+     *   }
+     * });
+     * ```
+     */
+    emitMultipleSounds(soundConfigs) {
+        const results = [];
+        soundConfigs.forEach((config, index) => {
+            try {
+                const result = this.emitSound(config);
+                results.push({ index, success: result, config });
+            }
+            catch (error) {
+                results.push({ index, success: false, error: error instanceof Error ? error.message : String(error), config });
+            }
+        });
+        return results;
+    }
+}
+exports.default = NodemodSound;
+//# sourceMappingURL=sound.js.map

package/dist/core/sound.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sound.js","sourceRoot":"","sources":["../../src/core/sound.ts"],"names":[],"mappings":"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"}

package/dist/enhanced/entity.d.ts

@@ -0,0 +1,263 @@
+import type NodemodUtil from '../utils/util';
+/**
+ * Extended entity interface that allows dynamic property access.
+ * Useful for setting custom entity properties not defined in the base interface.
+ */
+export interface DynamicEntity extends nodemod.Entity {
+    /** Allow dynamic property access */
+    [key: string]: any;
+}
+/**
+ * Criteria for filtering entities in search operations.
+ */
+export interface EntityCriteria {
+    /** Filter by entity class name */
+    className?: string;
+    /** Filter by entity target name */
+    targetName?: string;
+    /** Filter by entity target */
+    target?: string;
+    /** Filter by model path */
+    model?: string;
+    /** Filter by health value */
+    health?: number;
+    /** Filter by entity flags (bitwise AND check) */
+    flags?: number;
+    /** Filter by spawn flags (bitwise AND check) */
+    spawnflags?: number;
+}
+/**
+ * Enhanced entity wrapper providing convenient property access and utility methods.
+ * Extends nodemod.Entity directly for full compatibility with nodemod.eng functions.
+ */
+export interface EntityWrapper extends nodemod.Entity {
+    /** Remove the entity from the world */
+    remove(): void;
+    /** Make entity static (non-moving) */
+    makeStatic(): void;
+    /** Set entity bounding box size */
+    setSize(mins: number[], maxs: number[]): void;
+    /** Drop entity to floor and return drop distance */
+    dropToFloor(): number;
+    /** Check if entity is on the floor */
+    isOnFloor(): number;
+    /** Emit a sound from this entity */
+    emitSound(channel: number, sound: string, volume?: number, attenuation?: number, flags?: number, pitch?: number): void;
+    /** Get distance to another entity */
+    getDistance(target: EntityWrapper | nodemod.Entity): number;
+    /** Get illumination level at entity position */
+    getIllum(): number;
+    /** Set callback for when this entity is touched */
+    onTouch(callback: (other: EntityWrapper | null) => void): void;
+    /** Set callback for when this entity is used */
+    onUse(callback: (other: EntityWrapper | null) => void): void;
+    use(): void;
+    touch(other: nodemod.Entity): void;
+}
+/**
+ * Comprehensive entity management system providing enhanced entity creation, searching, and manipulation.
+ * Wraps raw nodemod entities with convenient property accessors and utility methods.
+ *
+ * @example
+ * ```typescript
+ * // Find all players
+ * const players = nodemodCore.entity.find({ className: 'player' });
+ * players.forEach(player => {
+ *   console.log(`Player at: ${player.origin}`);
+ * });
+ *
+ * // Create a light entity
+ * const light = nodemodCore.entity.createLight([100, 200, 300], '_light', 500);
+ * if (light) {
+ *   light.targetName = 'my_light';
+ * }
+ *
+ * // Find entities near a position
+ * const nearby = nodemodCore.entity.findInSphere([0, 0, 0], 512, 'weapon_ak47');
+ * console.log(`Found ${nearby.length} AK47s nearby`);
+ * ```
+ */
+export default class NodemodEntity {
+    /** Utility service for entity operations */
+    private util;
+    /**
+     * Creates a new NodemodEntity instance.
+     *
+     * @param utilService - Utility service for entity operations
+     */
+    constructor(utilService: NodemodUtil);
+    /**
+     * Creates a new entity with optional class name.
+     *
+     * @param className - Entity class name (e.g., 'info_player_start', 'weapon_ak47')
+     * @returns EntityWrapper for the created entity, or null if creation failed
+     *
+     * @example
+     * ```typescript
+     * // Create a generic entity
+     * const entity = nodemodCore.entity.create();
+     *
+     * // Create a specific entity class
+     * const weapon = nodemodCore.entity.create('weapon_ak47');
+     * if (weapon) {
+     *   weapon.origin = [100, 200, 300];
+     * }
+     * ```
+     */
+    create(className?: string | null): EntityWrapper | null;
+    /**
+     * Wraps a raw nodemod entity with enhanced functionality while preserving nodemod.eng compatibility.
+     * The entity object itself is returned with additional methods attached, ensuring full compatibility
+     * with core nodemod.eng functions.
+     *
+     * @param entity - The raw nodemod entity to wrap
+     * @returns EntityWrapper with enhanced functionality, or null if entity is invalid
+     *
+     * @example
+     * ```typescript
+     * const rawEntity = nodemod.eng.pEntityOfEntIndex(1);
+     * const wrapped = nodemodCore.entity.wrap(rawEntity);
+     * if (wrapped) {
+     *   console.log(`Entity class: ${wrapped.classname}`);
+     *   wrapped.health = 100;
+     *   wrapped.emitSound(0, 'items/healthkit.wav');
+     *   // Still compatible with nodemod.eng functions:
+     *   nodemod.eng.setOrigin(wrapped, [0, 0, 0]);
+     * }
+     * ```
+     */
+    wrap(entity: nodemod.Entity): EntityWrapper | null;
+    /**
+     * Finds entities matching the specified criteria.
+     *
+     * @param criteria - Search criteria to filter entities
+     * @returns Array of EntityWrapper objects matching the criteria
+     *
+     * @example
+     * ```typescript
+     * // Find all players
+     * const players = nodemodCore.entity.find({ className: 'player' });
+     *
+     * // Find entities with specific target name
+     * const targets = nodemodCore.entity.find({ targetName: 'button_secret' });
+     *
+     * // Find entities with specific flags
+     * const onGroundEntities = nodemodCore.entity.find({
+     *   flags: nodemod.FL.ONGROUND
+     * });
+     *
+     * // Combine multiple criteria
+     * const healthyPlayers = nodemodCore.entity.find({
+     *   className: 'player',
+     *   health: 100
+     * });
+     * ```
+     */
+    find(criteria: EntityCriteria): EntityWrapper[];
+    /**
+     * Finds the first entity matching the specified criteria.
+     * Convenience method for when you only need one result.
+     *
+     * @param criteria - Search criteria to filter entities
+     * @returns First EntityWrapper matching criteria, or null if none found
+     *
+     * @example
+     * ```typescript
+     * // Find first player
+     * const player = nodemodCore.entity.findOne({ className: 'player' });
+     * if (player) {
+     *   console.log(`Player health: ${player.health}`);
+     * }
+     *
+     * // Find specific target
+     * const secretButton = nodemodCore.entity.findOne({
+     *   targetName: 'secret_button'
+     * });
+     * ```
+     */
+    findOne(criteria: EntityCriteria): EntityWrapper | null;
+    /**
+     * Finds entities within a spherical radius of a position.
+     * Uses actual entity bounds, not just origin points - works correctly with brush entities.
+     *
+     * @param origin - Center position [x, y, z] to search from
+     * @param radius - Search radius in world units
+     * @param className - Optional filter by entity class name
+     * @returns Array of EntityWrapper objects within the sphere
+     *
+     * @example
+     * ```typescript
+     * // Find all entities near player
+     * const playerPos = [100, 200, 300];
+     * const nearbyEntities = nodemodCore.entity.findInSphere(playerPos, 512);
+     *
+     * // Find specific entity types nearby
+     * const nearbyWeapons = nodemodCore.entity.findInSphere(
+     *   playerPos,
+     *   256,
+     *   'weapon_ak47'
+     * );
+     *
+     * // Find entities in explosion radius
+     * const explosionPos = [0, 0, 0];
+     * const affected = nodemodCore.entity.findInSphere(explosionPos, 200);
+     * affected.forEach(entity => {
+     *   // Apply damage logic
+     * });
+     * ```
+     */
+    findInSphere(origin: number[], radius: number, className?: string | null): EntityWrapper[];
+    getById(id: number): EntityWrapper | null;
+    getAll(): EntityWrapper[];
+    private matchesCriteria;
+    /**
+     * Creates a light entity at the specified position.
+     *
+     * @param origin - Position [x, y, z] for the light
+     * @param color - Light color property name (default: '_light')
+     * @param brightness - Light brightness value (default: 300)
+     * @returns EntityWrapper for the created light, or null if creation failed
+     *
+     * @example
+     * ```typescript
+     * // Create standard light
+     * const light = nodemodCore.entity.createLight([100, 200, 300]);
+     *
+     * // Create colored light
+     * const redLight = nodemodCore.entity.createLight([0, 0, 0], '_light', 500);
+     * if (redLight) {
+     *   (redLight as any)._color = '255 0 0'; // Red color
+     * }
+     * ```
+     */
+    createLight(origin: number[], color?: string, brightness?: number): EntityWrapper | null;
+    createInfo(className: string, origin: number[], angles?: number[]): EntityWrapper | null;
+    createTrigger(className: string, origin: number[], size?: number[]): EntityWrapper | null;
+    /**
+     * Removes all entities matching the specified criteria.
+     *
+     * @param criteria - Search criteria to filter entities for removal
+     * @returns Number of entities removed
+     *
+     * @example
+     * ```typescript
+     * // Remove all weapons from the map
+     * const removed = nodemodCore.entity.removeAll({
+     *   className: 'weapon_ak47'
+     * });
+     * console.log(`Removed ${removed} AK47s`);
+     *
+     * // Remove entities with specific target name
+     * nodemodCore.entity.removeAll({
+     *   targetName: 'cleanup_target'
+     * });
+     *
+     * // Remove all low-health entities
+     * nodemodCore.entity.removeAll({
+     *   health: 1
+     * });
+     * ```
+     */
+    removeAll(criteria: EntityCriteria): number;
+}
+//# sourceMappingURL=entity.d.ts.map

package/dist/enhanced/entity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"entity.d.ts","sourceRoot":"","sources":["../../src/enhanced/entity.ts"],"names":[],"mappings":"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"}