@rb-games/core 0.1.0

package/dist/plugins/skin/SkinPlugin.d.ts

@@ -0,0 +1,285 @@
+import { Skin } from './Skin';
+import type { SkinPluginConfig, SkinOptions } from './SkinPlugin.types';
+import type { EnginePlugin } from '../Plugin.types';
+import { PixiEngine } from '../../engine/PixiEngine';
+/**
+ * Event data for global data changes.
+ *
+ * @public
+ */
+export interface GlobalDataChangeEvent {
+    /** Property path that changed */
+    path: string;
+    /** Previous value */
+    oldValue: any;
+    /** New value */
+    newValue: any;
+    /** Skins affected by this change */
+    affectedSkins: Skin<any>[];
+}
+/**
+ * Skin management plugin for theme-based UI configuration.
+ *
+ * SkinPlugin provides a centralized system for managing UI themes and data injection.
+ * It allows components to have multiple themes and dynamically inject global data.
+ *
+ * ## Features
+ *
+ * - **Multi-Theme Support**: Create skins with multiple theme variants
+ * - **Global Theme Switching**: Change themes across all skins at once
+ * - **Data Injection**: Inject global data into skin properties using template strings
+ * - **Automatic Updates**: Components automatically update when data changes
+ * - **Type-Safe**: Full TypeScript support with generics
+ *
+ * ## Core Concepts
+ *
+ * ### 1. Skins
+ * Skins are theme-based configuration objects. Each skin can have multiple themes
+ * (default, dark, mobile, etc.) and properties are merged from default + current theme.
+ *
+ * ### 2. Global Data Injection
+ * Use template strings `${path}` in skin data to reference global values:
+ * ```typescript
+ * const skinData = {
+ *   default: {
+ *     color: '${ui.default.themeColor.default}',  // Will be injected
+ *     fontSize: '${ui.default.fontSize.normal}'    // Will be injected
+ *   }
+ * };
+ * ```
+ *
+ * ### 3. Theme Inheritance
+ * Themes inherit from the default theme. Only specify differences:
+ * ```typescript
+ * {
+ *   default: { color: 0xFF0000, size: 100 },
+ *   dark: { color: 0x000000 }  // size inherited from default
+ * }
+ * ```
+ *
+ * @example
+ * Basic usage:
+ * ```typescript
+ * const skinPlugin = new SkinPlugin({ debugMode: true });
+ * engine.registerPlugin(skinPlugin);
+ *
+ * // Create a button skin
+ * const { skin: buttonSkin } = skinPlugin.createSkin({
+ *   data: {
+ *     default: {
+ *       up: { background: { texture: 'btn_spin_up' } },
+ *       over: { background: { texture: 'btn_spin_over' } }
+ *     },
+ *     dark: {
+ *       up: { background: { texture: 'btn_spin_dark_up' } }
+ *     }
+ *   }
+ * });
+ *
+ * // Use skin properties
+ * const button = new ButtonComp({
+ *   skinData: buttonSkin.getProperties()
+ * });
+ *
+ * // Switch theme
+ * skinPlugin.setTheme('dark');
+ * ```
+ *
+ * @example
+ * Global data injection from EmptyScene:
+ * ```typescript
+ * const skinPlugin = engine.getPlugin<SkinPlugin>('skinPlugin');
+ *
+ * // Set global UI values
+ * skinPlugin.setGlobalData('ui.default.fontSize.header', 36);
+ * skinPlugin.setGlobalData('ui.default.fontSize.normal', 24);
+ * skinPlugin.setGlobalData('ui.default.fontFamily', 'NotoSansBlack');
+ * skinPlugin.setGlobalData('ui.default.textColor', 0xFFFFFF);
+ * skinPlugin.setGlobalData('ui.default.themeColor.default', 0xFFD100);
+ *
+ * // Create skin with template strings
+ * const { skin } = skinPlugin.createSkin({
+ *   data: {
+ *     default: {
+ *       title: {
+ *         fontSize: '${ui.default.fontSize.header}',
+ *         fontFamily: '${ui.default.fontFamily}',
+ *         fill: '${ui.default.textColor}'
+ *       },
+ *       button: {
+ *         color: '${ui.default.themeColor.default}'
+ *       }
+ *     }
+ *   }
+ * });
+ *
+ * // Properties are automatically injected
+ * const props = skin.getProperties();
+ * // { title: { fontSize: 36, fontFamily: 'NotoSansBlack', fill: 0xFFFFFF },
+ * //   button: { color: 0xFFD100 } }
+ * ```
+ *
+ * @example
+ * Using with DataInjector from EmptyScene:
+ * ```typescript
+ * import { DataInjector } from '@rb-games/core/utils';
+ *
+ * // Start with default skin
+ * let autoplaySkin = defaultAutoplayMenuSkin;
+ *
+ * // Inject specific textures
+ * autoplaySkin = DataInjector(autoplaySkin, 'options.buttonSkin', {
+ *   up: { background: { texture: 'btn_checkbox_up' } },
+ *   over: { background: { texture: 'btn_checkbox_over' } },
+ *   down: { background: { texture: 'btn_checkbox_down' } }
+ * });
+ *
+ * autoplaySkin = DataInjector(autoplaySkin, 'count.sliderSkin', {
+ *   up: { knob: { texture: 'icon_autoplay_slider_up' } },
+ *   over: { knob: { texture: 'icon_autoplay_slider_over' } }
+ * });
+ *
+ * // Create skin with injected data
+ * const { skin } = skinPlugin.createSkin({
+ *   data: { default: autoplaySkin }
+ * });
+ * ```
+ *
+ * @example
+ * Listening to data changes:
+ * ```typescript
+ * const { skin } = skinPlugin.createSkin({ data: skinData });
+ *
+ * // Listen for data injection
+ * skin.on('dataInjected', (event) => {
+ *   console.log(`Data changed: ${event.path}`);
+ *   console.log(`Old: ${event.oldValue}, New: ${event.newValue}`);
+ *   updateComponent(skin.getProperties());
+ * });
+ *
+ * // Listen for theme changes
+ * skin.on('themeChanged', (event) => {
+ *   console.log(`Theme: ${event.oldTheme} -> ${event.newTheme}`);
+ *   updateComponent(skin.getProperties());
+ * });
+ *
+ * // Change global data (triggers dataInjected event)
+ * skinPlugin.setGlobalData('ui.button.color', 0xFF0000);
+ * ```
+ *
+ * @category Plugins
+ * @public
+ */
+export declare class SkinPlugin implements EnginePlugin {
+    name: string;
+    priority: number;
+    dependencies: string[];
+    private skins;
+    private skinCache;
+    private globalTheme;
+    private config;
+    private isInitialized;
+    private globalData;
+    constructor(config?: SkinPluginConfig);
+    initialize(engine: PixiEngine): Promise<void>;
+    onReady(engine: PixiEngine): void;
+    isReady(): boolean;
+    cleanup(): void;
+    /**
+     * Creates a new skin instance.
+     *
+     * Factory method that creates and registers a skin.
+     *
+     * @typeParam T - The type of skin properties
+     * @param options - Skin configuration options
+     * @returns Object containing the skin instance and its ID
+     *
+     * @example
+     * ```typescript
+     * const { skin, skinId } = skinPlugin.createSkin({
+     *   data: {
+     *     default: { color: 0xFF0000 },
+     *     dark: { color: 0x000000 }
+     *   },
+     *   defaultTheme: 'default'
+     * });
+     * ```
+     */
+    createSkin<T extends Record<string, any>>(options: SkinOptions<T>): {
+        skin: Skin<T>;
+        skinId: string;
+        cached?: boolean;
+    };
+    private createAndRegisterSkin;
+    registerSkin(skin: Skin<any>): string;
+    unregisterSkin(skin: Skin<any> | string): void;
+    /**
+     * Sets the global theme for all registered skins.
+     *
+     * Applies the theme to all skins that have it defined.
+     *
+     * @param themeName - Theme name to activate
+     *
+     * @example
+     * ```typescript
+     * skinPlugin.setTheme('dark');
+     * skinPlugin.setTheme('mobile');
+     * ```
+     */
+    setTheme(themeName: string): void;
+    getTheme(): string;
+    getSkinCount(): number;
+    getAllSkins(): Skin<any>[];
+    clearAllSkins(): void;
+    getSkinById(id: string): Skin<any> | undefined;
+    /**
+     * Sets global data for property injection.
+     *
+     * Updates global data and triggers 'dataInjected' event on affected skins.
+     * Skins using template strings like `${path}` will be automatically updated.
+     *
+     * @param path - Dot-notation path (e.g., 'ui.button.color')
+     * @param value - Value to set
+     * @example
+     * ```typescript
+     * skinPlugin.setGlobalData('ui.default.themeColor.default', 0xFFD100);
+     * skinPlugin.setGlobalData('ui.default.fontSize.header', 36);
+     * // Or set multiple values at once:
+     * skinPlugin.setGlobalData({
+     *   'ui.default.themeColor.default': 0xFFD100,
+     *   'ui.default.fontSize.header': 36
+     * });
+     * ```
+     */
+    setGlobalData(path: string, value: any): void;
+    setGlobalData(data: Record<string, any>): void;
+    /**
+     * Gets global data.
+     *
+     * @param path - Optional dot-notation path. If omitted, returns all global data.
+     * @returns Global data value or entire global data object
+     */
+    getGlobalData(path?: string): any;
+    clearGlobalData(): void;
+    clearCache(): void;
+    getCacheStats(): {
+        size: number;
+        entries: Array<{
+            key: string;
+            skinId: string;
+            refCount: number;
+        }>;
+    };
+    private generateCacheKey;
+    private stringifyDeterministic;
+    private simpleHash;
+    injectGlobalData<T>(skinData: T): T;
+    private setNestedProperty;
+    private getNestedProperty;
+    private injectProperties;
+    private findSkinsUsingProperty;
+    private skinUsesProperty;
+    private objectContainsTemplate;
+    [key: symbol]: any;
+}
+//# sourceMappingURL=SkinPlugin.d.ts.map

package/dist/plugins/skin/SkinPlugin.d.ts.map

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

package/dist/plugins/skin/SkinPlugin.types.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Theme data structure mapping theme names to their properties.
+ *
+ * @typeParam T - The type of properties for each theme
+ *
+ * @example
+ * ```typescript
+ * const buttonThemes: ThemeData<ButtonSkinData> = {
+ *   default: { color: 0xFF0000, size: 100 },
+ *   dark: { color: 0x000000, size: 100 },
+ *   mobile: { color: 0xFF0000, size: 80 }
+ * };
+ * ```
+ *
+ * @public
+ */
+export interface ThemeData<T = any> {
+    [themeName: string]: T;
+}
+/**
+ * Options for creating a skin.
+ *
+ * @typeParam T - The type of skin properties
+ *
+ * @public
+ */
+export interface SkinOptions<T> {
+    /** Theme data mapping theme names to properties */
+    data: ThemeData<T>;
+    /** Default theme name (uses first theme if not specified) */
+    defaultTheme?: string;
+    /** Use cache to reuse existing skins with same structure (default: false) */
+    useCache?: boolean;
+    /** Manual cache key for template-based skins (optional) */
+    cacheKey?: string;
+}
+/**
+ * Callback for theme change events.
+ *
+ * @typeParam T - The type of skin properties
+ *
+ * @public
+ */
+export type SkinChangeListener<T> = (skin: any, oldTheme: string, newTheme: string) => void;
+/**
+ * Configuration for SkinPlugin.
+ *
+ * @public
+ */
+export interface SkinPluginConfig {
+    /** Automatically cleanup skins when plugin is destroyed (default: true) */
+    autoCleanup?: boolean;
+    /** Enable skin caching to prevent duplicate skin creation (default: true) */
+    enableCache?: boolean;
+}
+//# sourceMappingURL=SkinPlugin.types.d.ts.map

package/dist/plugins/skin/SkinPlugin.types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SkinPlugin.types.d.ts","sourceRoot":"","sources":["../../../plugins/skin/SkinPlugin.types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,MAAM,WAAW,SAAS,CAAC,CAAC,GAAG,GAAG;IAChC,CAAC,SAAS,EAAE,MAAM,GAAG,CAAC,CAAC;CACxB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,WAAW,CAAC,CAAC;IAC5B,mDAAmD;IACnD,IAAI,EAAE,SAAS,CAAC,CAAC,CAAC,CAAC;IACnB,6DAA6D;IAC7D,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,6EAA6E;IAC7E,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,2DAA2D;IAC3D,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;GAMG;AACH,MAAM,MAAM,kBAAkB,CAAC,CAAC,IAAI,CAAC,IAAI,EAAE,GAAG,EAAE,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,KAAK,IAAI,CAAC;AAE5F;;;;GAIG;AACH,MAAM,WAAW,gBAAgB;IAC/B,2EAA2E;IAC3E,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,6EAA6E;IAC7E,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB"}

package/dist/plugins/skin/index.d.ts

@@ -0,0 +1,5 @@
+export * from './Skin';
+export * from './SkinPlugin';
+export type * from './SkinPlugin.types';
+export type * from './ISkin';
+//# sourceMappingURL=index.d.ts.map

package/dist/plugins/skin/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../plugins/skin/index.ts"],"names":[],"mappings":"AAAA,cAAc,QAAQ,CAAC;AACvB,cAAc,cAAc,CAAC;AAC7B,mBAAmB,oBAAoB,CAAC;AACxC,mBAAmB,SAAS,CAAC"}

package/dist/plugins/sound/SoundPlugin.d.ts

@@ -0,0 +1,319 @@
+import { IMediaInstance } from '@pixi/sound';
+import { PixiEngine } from '../../engine/PixiEngine';
+import type { EnginePlugin } from '../Plugin.types';
+import type { SoundPluginConfig, SoundSpriteData, PlayOptions, QueueInOptions, SoundChannel } from './SoundPlugin.types';
+/**
+ * Sound playback and channel management plugin for PixiJS games.
+ *
+ * SoundPlugin provides a unified API for playing sounds, managing audio channels,
+ * and handling sound sprites. It works with ResourcePlugin for asset loading.
+ *
+ * ## Features
+ *
+ * - **Channel System**: Separate volume/mute control for music, voice, sfx, ui
+ * - **Sound Sprites**: Play segments of longer audio files
+ * - **Unified Play API**: Same `play(alias)` for both sprites and regular sounds
+ * - **Fade Effects**: FadeIn, fadeOut, crossfade with GSAP
+ * - **Mobile Unlock**: Auto-unlock AudioContext on user interaction
+ *
+ * @example
+ * ```typescript
+ * const soundPlugin = new SoundPlugin({
+ *   channels: {
+ *     music: { volume: 0.7, maxInstances: 1 },
+ *     sfx: { volume: 0.8, maxInstances: 10 },
+ *   },
+ *   masterVolume: 1.0,
+ *   autoUnlock: true,
+ * });
+ *
+ * engine.registerPlugin(soundPlugin);
+ * await engine.initialize();
+ *
+ * // Add sprites
+ * soundPlugin.addSprites('sfx-sprite', {
+ *   'win-big': { start: 0, end: 3 },
+ *   'spin': { start: 4, end: 5 },
+ * });
+ *
+ * // Play sounds (sprites or regular)
+ * await soundPlugin.play('win-big');
+ * await soundPlugin.play('bgm-main', { loop: true });
+ * ```
+ *
+ * @category Plugins
+ * @public
+ */
+export declare class SoundPlugin implements EnginePlugin {
+    name: string;
+    priority: number;
+    dependencies: string[];
+    private config;
+    /** Sprite alias -> sound alias + sprite key mapping */
+    private spriteRegistry;
+    /** Channel configurations */
+    private channels;
+    /** Currently playing instances by alias */
+    private playingInstances;
+    /** Sound alias -> channel mapping */
+    private soundChannelMap;
+    /** Master volume */
+    private _masterVolume;
+    /** Audio context unlocked flag */
+    private _unlocked;
+    /** Active interval loop timers by alias */
+    private intervalTimers;
+    /** Active interval loop instance per alias — only this instance may schedule the next play */
+    private activeLoopInstances;
+    /** Store original PlayOptions for interval loops to restore on trigger/replay */
+    private intervalLoopOptions;
+    /** Store original volume for all playing sounds (for mute/unmute restore) */
+    private soundVolumeMap;
+    /** Group -> tracked instances for stopGroup support */
+    private groupInstances;
+    constructor(config?: SoundPluginConfig);
+    initialize(_engine: PixiEngine): Promise<void>;
+    onReady(_engine: PixiEngine): void;
+    cleanup(): void;
+    /**
+     * Initialize channel configurations
+     */
+    private initializeChannels;
+    /**
+     * Setup auto-unlock for mobile browsers
+     */
+    private setupAutoUnlock;
+    /**
+     * Add sound sprites to a sound file.
+     * Each sprite key becomes a playable alias.
+     *
+     * @param soundAlias - The alias of the loaded sound file
+     * @param sprites - Map of sprite names to their start/end times
+     * @param channel - Optional channel assignment for all sprites
+     *
+     * @example
+     * ```typescript
+     * soundPlugin.addSprites('sfx-sprite', {
+     *   'win-big': { start: 0, end: 3 },
+     *   'spin': { start: 4, end: 5.5 },
+     *   'click': { start: 6, end: 6.2 },
+     * }, 'sfx');
+     * ```
+     */
+    addSprites(soundAlias: string, sprites: Record<string, SoundSpriteData>, channel?: SoundChannel): void;
+    /**
+     * Add sprites from a JSON file.
+     *
+     * @param soundAlias - The alias of the loaded sound file
+     * @param jsonPath - Path to the JSON file containing sprite definitions
+     * @param channel - Optional channel assignment for all sprites
+     */
+    addSpritesFromJson(soundAlias: string, jsonPath: string, channel?: SoundChannel): Promise<void>;
+    /**
+     * Register a sound alias to a channel.
+     *
+     * @param alias - Sound alias
+     * @param channel - Channel to assign
+     */
+    setChannel(alias: string, channel: SoundChannel): void;
+    /**
+     * Play a sound by alias. Works for both regular sounds and sprites.
+     *
+     * @param alias - Sound alias or sprite name
+     * @param options - Play options
+     * @returns Promise resolving to the media instance
+     *
+     * @example
+     * ```typescript
+     * // Play regular sound
+     * await soundPlugin.play('bgm-main', { loop: true });
+     *
+     * // Play sprite (same API)
+     * await soundPlugin.play('win-big');
+     * ```
+     */
+    play(alias: string, options?: PlayOptions): Promise<IMediaInstance | null>;
+    /**
+     * Stop all sounds registered under a logical group.
+     *
+     * @param group - The logical group set via PlayOptions.group
+     */
+    stopGroup(group: string): void;
+    /**
+     * Stop a sound by alias.
+     *
+     * @param alias - Sound alias or sprite name
+     */
+    stopAlias(alias: string): void;
+    /**
+     * Stop all sounds in a specific channel.
+     *
+     * @param channel - Channel name (music, sfx, voice, ui)
+     */
+    stopChannel(channel: SoundChannel): void;
+    /**
+     * Stop all playing sounds.
+     */
+    stopAll(): void;
+    /**
+     * Pause a sound by alias.
+     *
+     * @param alias - Sound alias
+     */
+    pause(alias: string): void;
+    /**
+     * Resume a paused sound.
+     *
+     * @param alias - Sound alias
+     */
+    resume(alias: string): void;
+    /**
+     * Fade in a sound.
+     *
+     * @param alias - Sound alias
+     * @param duration - Fade duration in seconds
+     * @param options - Play options
+     */
+    fadeIn(alias: string, duration: number, options?: PlayOptions): Promise<void>;
+    /**
+     * Fade out a sound.
+     *
+     * @param alias - Sound alias
+     * @param duration - Fade duration in seconds
+     * @param stopAfter - Whether to stop the sound after fading out
+     */
+    fadeOut(alias: string, duration: number, stopAfter?: boolean): Promise<void>;
+    /**
+     * Crossfade between two sounds.
+     *
+     * @param fromAlias - Sound to fade out
+     * @param toAlias - Sound to fade in
+     * @param duration - Crossfade duration in seconds
+     * @param options - Play options for the new sound
+     */
+    crossfade(fromAlias: string, toAlias: string, duration: number, options?: PlayOptions): Promise<void>;
+    /**
+     * Fade out all sounds in a channel.
+     *
+     * @param channel - Channel name
+     * @param duration - Fade duration in seconds
+     */
+    fadeOutChannel(channel: SoundChannel, duration: number): Promise<void>;
+    /**
+     * Queue in a new sound by fading out all sounds in its channel and fading in the new one.
+     * Supports both crossfade (simultaneous) and sequential (fade out first, then fade in) transitions.
+     *
+     * @param alias - Sound alias to play
+     * @param duration - Fade in duration in seconds
+     * @param options - Queue in options (includes fadeOutDuration, type, channel, and PlayOptions)
+     * @returns The new sound instance, or null if failed
+     *
+     * @example
+     * ```typescript
+     * // Crossfade (default) - fade out existing and fade in new simultaneously
+     * soundPlugin.queueIn('freespin', 1, { loop: true });
+     *
+     * // Sequential - fade out first, then fade in
+     * soundPlugin.queueIn('freespin', 1, { loop: true, type: 'sequential' });
+     *
+     * // Different fade durations
+     * soundPlugin.queueIn('freespin', 1, { loop: true, fadeOutDuration: 0.5 });
+     * ```
+     */
+    queueIn(alias: string, duration: number, options?: QueueInOptions): Promise<IMediaInstance | null>;
+    /**
+     * Set channel volume.
+     *
+     * @param channel - Channel name
+     * @param volume - Volume (0-1)
+     */
+    setChannelVolume(channel: SoundChannel, volume: number): void;
+    /**
+     * Get channel volume.
+     *
+     * @param channel - Channel name
+     * @returns Volume (0-1)
+     */
+    getChannelVolume(channel: SoundChannel): number;
+    /**
+     * Mute a channel.
+     *
+     * @param channel - Channel name
+     */
+    muteChannel(channel: SoundChannel): void;
+    /**
+     * Unmute a channel.
+     *
+     * @param channel - Channel name
+     */
+    unmuteChannel(channel: SoundChannel): void;
+    /**
+     * Set volume on all currently playing instances in a channel.
+     * Takes into account the original sound volume from soundVolumeMap.
+     */
+    private setChannelInstancesVolume;
+    /**
+     * Check if a channel is muted.
+     *
+     * @param channel - Channel name
+     * @returns True if muted
+     */
+    isChannelMuted(channel: SoundChannel): boolean;
+    /**
+     * Pause all sounds in a channel.
+     *
+     * @param channel - Channel name
+     */
+    pauseChannel(channel: SoundChannel): void;
+    /**
+     * Resume all sounds in a channel.
+     *
+     * @param channel - Channel name
+     */
+    resumeChannel(channel: SoundChannel): void;
+    /**
+     * Set master volume.
+     *
+     * @param volume - Volume (0-1)
+     */
+    set masterVolume(volume: number);
+    /**
+     * Get master volume.
+     */
+    get masterVolume(): number;
+    /**
+     * Check if audio context is unlocked.
+     */
+    get isUnlocked(): boolean;
+    /**
+     * Calculate interval delay from a fixed number or random range.
+     */
+    private getIntervalDelay;
+    /**
+     * Clear an active interval timer for an alias.
+     */
+    private clearIntervalTimer;
+    /**
+     * Trigger an interval loop sound immediately, skipping the wait timer.
+     * Only works for sounds that are in interval loop mode (loopInterval).
+     *
+     * @param alias - Sound alias to trigger
+     */
+    triggerIntervalLoop(alias: string): void;
+    /**
+     * Check if an alias is currently in interval loop mode.
+     *
+     * @param alias - Sound alias to check
+     * @returns True if the alias is an active interval loop
+     */
+    isIntervalLoop(alias: string): boolean;
+    /**
+     * Check if an alias is waiting for its next interval play.
+     *
+     * @param alias - Sound alias to check
+     * @returns True if the alias has a pending interval timer
+     */
+    isWaitingForInterval(alias: string): boolean;
+    [key: symbol]: any;
+}
+//# sourceMappingURL=SoundPlugin.d.ts.map

package/dist/plugins/sound/SoundPlugin.d.ts.map

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