@utsp/core 0.4.0-nightly.20251201222332.2d9d7a5 → 0.4.0-nightly.20251203172602.bbfc50f
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/index.cjs +4 -4
- package/dist/index.d.ts +603 -3
- package/dist/index.mjs +4 -4
- package/package.json +2 -2
package/dist/index.d.ts
CHANGED
|
@@ -1,4 +1,5 @@
|
|
|
1
|
-
import
|
|
1
|
+
import * as _utsp_types from '@utsp/types';
|
|
2
|
+
import { Vector2, AxisSource, ButtonSource, InputBindingLoadPacket, AxisBinding, ButtonBinding, SoundInstanceId, AudioConfigCommand, PlaySoundCommand, StopSoundCommand, FadeOutSoundCommand, PauseSoundCommand, ResumeSoundCommand, IAudioProcessor, SoundFormat, SoundLoadType, SoundLoadPacket, SoundExternalLoadPacket, UserRenderState } from '@utsp/types';
|
|
2
3
|
export { AxisBinding, AxisSource, ButtonBinding, ButtonSource, InputBindingLoadPacket, RenderState, RenderedCell, UserRenderState, Vector2 } from '@utsp/types';
|
|
3
4
|
|
|
4
5
|
/**
|
|
@@ -1572,6 +1573,13 @@ declare class User<TData = Record<string, any>> {
|
|
|
1572
1573
|
private activeTouchId;
|
|
1573
1574
|
private inputBindings;
|
|
1574
1575
|
private stats;
|
|
1576
|
+
private soundCommands;
|
|
1577
|
+
private nextSoundInstanceId;
|
|
1578
|
+
private audioConfigCommands;
|
|
1579
|
+
private lastListenerX;
|
|
1580
|
+
private lastListenerY;
|
|
1581
|
+
private pendingSendSounds;
|
|
1582
|
+
private audioProcessor?;
|
|
1575
1583
|
/**
|
|
1576
1584
|
* Application-specific data storage
|
|
1577
1585
|
* Use this to store game state, player data, or any custom information
|
|
@@ -2209,6 +2217,312 @@ declare class User<TData = Record<string, any>> {
|
|
|
2209
2217
|
* ```
|
|
2210
2218
|
*/
|
|
2211
2219
|
decodeAndApplyCompressedInput(buffer: Uint8Array): void;
|
|
2220
|
+
/**
|
|
2221
|
+
* Play a sound for this user
|
|
2222
|
+
*
|
|
2223
|
+
* The sound command is queued and will be sent to the client
|
|
2224
|
+
* at the end of the current tick by the runtime.
|
|
2225
|
+
*
|
|
2226
|
+
* @param sound - Sound name (e.g., 'coin') or ID (0-255)
|
|
2227
|
+
* @param options - Playback options (volume, pitch, loop, fadeIn, position)
|
|
2228
|
+
* @returns Instance ID that can be used to stop this specific sound later
|
|
2229
|
+
*
|
|
2230
|
+
* @example
|
|
2231
|
+
* ```typescript
|
|
2232
|
+
* // In updateUser()
|
|
2233
|
+
* if (playerCollectedCoin) {
|
|
2234
|
+
* user.playSound('coin');
|
|
2235
|
+
* }
|
|
2236
|
+
*
|
|
2237
|
+
* // With options
|
|
2238
|
+
* user.playSound('explosion', { volume: 0.8, pitch: 0.9 });
|
|
2239
|
+
*
|
|
2240
|
+
* // Loop background music with fade in
|
|
2241
|
+
* const musicId = user.playSound('music', { loop: true, volume: 0.5, fadeIn: 2 });
|
|
2242
|
+
* // Later: user.fadeOutSound(musicId, 2);
|
|
2243
|
+
*
|
|
2244
|
+
* // Spatial audio (x/y position 0-65535)
|
|
2245
|
+
* user.playSound('explosion', { x: 10000, y: 32768 });
|
|
2246
|
+
* ```
|
|
2247
|
+
*/
|
|
2248
|
+
playSound(sound: string | number, options?: {
|
|
2249
|
+
volume?: number;
|
|
2250
|
+
pitch?: number;
|
|
2251
|
+
loop?: boolean;
|
|
2252
|
+
fadeIn?: number;
|
|
2253
|
+
x?: number;
|
|
2254
|
+
y?: number;
|
|
2255
|
+
}): SoundInstanceId;
|
|
2256
|
+
/**
|
|
2257
|
+
* Stop a sound immediately by instance ID or name
|
|
2258
|
+
*
|
|
2259
|
+
* @param target - Instance ID (number) to stop specific instance,
|
|
2260
|
+
* or sound name (string) to stop all instances of that sound
|
|
2261
|
+
*
|
|
2262
|
+
* @example
|
|
2263
|
+
* ```typescript
|
|
2264
|
+
* // Stop specific instance by ID
|
|
2265
|
+
* const musicId = user.playSound('music', { loop: true });
|
|
2266
|
+
* user.stopSound(musicId);
|
|
2267
|
+
*
|
|
2268
|
+
* // Stop all instances of a sound by name
|
|
2269
|
+
* user.stopSound('explosion');
|
|
2270
|
+
* ```
|
|
2271
|
+
*/
|
|
2272
|
+
stopSound(target: SoundInstanceId | string): void;
|
|
2273
|
+
/**
|
|
2274
|
+
* Fade out and stop a sound
|
|
2275
|
+
*
|
|
2276
|
+
* @param target - Instance ID (number) to fade specific instance,
|
|
2277
|
+
* or sound name (string) to fade all instances of that sound
|
|
2278
|
+
* @param duration - Fade duration in seconds
|
|
2279
|
+
*
|
|
2280
|
+
* @example
|
|
2281
|
+
* ```typescript
|
|
2282
|
+
* // Fade out specific instance over 2 seconds
|
|
2283
|
+
* const musicId = user.playSound('music', { loop: true, fadeIn: 1 });
|
|
2284
|
+
* // Later, when changing scene:
|
|
2285
|
+
* user.fadeOutSound(musicId, 2);
|
|
2286
|
+
*
|
|
2287
|
+
* // Fade out all ambient sounds
|
|
2288
|
+
* user.fadeOutSound('ambient', 1.5);
|
|
2289
|
+
* ```
|
|
2290
|
+
*/
|
|
2291
|
+
fadeOutSound(target: SoundInstanceId | string, duration: number): void;
|
|
2292
|
+
/**
|
|
2293
|
+
* Fade out and stop all sounds for this user
|
|
2294
|
+
*
|
|
2295
|
+
* @param duration - Fade duration in seconds
|
|
2296
|
+
*
|
|
2297
|
+
* @example
|
|
2298
|
+
* ```typescript
|
|
2299
|
+
* // When entering a cutscene, fade out all game audio
|
|
2300
|
+
* user.fadeOutAllSounds(1);
|
|
2301
|
+
* ```
|
|
2302
|
+
*/
|
|
2303
|
+
fadeOutAllSounds(duration: number): void;
|
|
2304
|
+
/**
|
|
2305
|
+
* Stop all sounds immediately for this user
|
|
2306
|
+
*
|
|
2307
|
+
* @example
|
|
2308
|
+
* ```typescript
|
|
2309
|
+
* // When player dies or game pauses
|
|
2310
|
+
* user.stopAllSounds();
|
|
2311
|
+
* ```
|
|
2312
|
+
*/
|
|
2313
|
+
stopAllSounds(): void;
|
|
2314
|
+
/**
|
|
2315
|
+
* Pause a sound by instance ID or name
|
|
2316
|
+
*
|
|
2317
|
+
* @param target - Instance ID (number) to pause specific instance,
|
|
2318
|
+
* or sound name (string) to pause all instances of that sound
|
|
2319
|
+
*
|
|
2320
|
+
* @example
|
|
2321
|
+
* ```typescript
|
|
2322
|
+
* // Pause specific instance
|
|
2323
|
+
* const musicId = user.playSound('music', { loop: true });
|
|
2324
|
+
* user.pauseSound(musicId);
|
|
2325
|
+
* // Later: user.resumeSound(musicId);
|
|
2326
|
+
*
|
|
2327
|
+
* // Pause all ambient sounds
|
|
2328
|
+
* user.pauseSound('ambient');
|
|
2329
|
+
* ```
|
|
2330
|
+
*/
|
|
2331
|
+
pauseSound(target: SoundInstanceId | string): void;
|
|
2332
|
+
/**
|
|
2333
|
+
* Pause all sounds for this user
|
|
2334
|
+
*
|
|
2335
|
+
* @example
|
|
2336
|
+
* ```typescript
|
|
2337
|
+
* // When opening pause menu
|
|
2338
|
+
* user.pauseAllSounds();
|
|
2339
|
+
* ```
|
|
2340
|
+
*/
|
|
2341
|
+
pauseAllSounds(): void;
|
|
2342
|
+
/**
|
|
2343
|
+
* Resume a paused sound by instance ID or name
|
|
2344
|
+
*
|
|
2345
|
+
* @param target - Instance ID (number) to resume specific instance,
|
|
2346
|
+
* or sound name (string) to resume all instances of that sound
|
|
2347
|
+
*
|
|
2348
|
+
* @example
|
|
2349
|
+
* ```typescript
|
|
2350
|
+
* // Resume specific instance
|
|
2351
|
+
* user.resumeSound(musicId);
|
|
2352
|
+
*
|
|
2353
|
+
* // Resume all ambient sounds
|
|
2354
|
+
* user.resumeSound('ambient');
|
|
2355
|
+
* ```
|
|
2356
|
+
*/
|
|
2357
|
+
resumeSound(target: SoundInstanceId | string): void;
|
|
2358
|
+
/**
|
|
2359
|
+
* Resume all paused sounds for this user
|
|
2360
|
+
*
|
|
2361
|
+
* @example
|
|
2362
|
+
* ```typescript
|
|
2363
|
+
* // When closing pause menu
|
|
2364
|
+
* user.resumeAllSounds();
|
|
2365
|
+
* ```
|
|
2366
|
+
*/
|
|
2367
|
+
resumeAllSounds(): void;
|
|
2368
|
+
/**
|
|
2369
|
+
* Set the listener position for spatial audio
|
|
2370
|
+
*
|
|
2371
|
+
* The listener is the "ear" of the player. Sounds with positions
|
|
2372
|
+
* will be panned and attenuated based on their distance to the listener.
|
|
2373
|
+
*
|
|
2374
|
+
* @param x - X position (0-65535, typically matches player position)
|
|
2375
|
+
* @param y - Y position (0-65535, typically matches player position)
|
|
2376
|
+
*
|
|
2377
|
+
* @example
|
|
2378
|
+
* ```typescript
|
|
2379
|
+
* // In updateUser(), follow the player
|
|
2380
|
+
* user.setListenerPosition(player.x, player.y);
|
|
2381
|
+
*
|
|
2382
|
+
* // Play spatial sound (will be panned/attenuated based on distance)
|
|
2383
|
+
* user.playSound('explosion', { x: 100, y: 50 });
|
|
2384
|
+
* ```
|
|
2385
|
+
*/
|
|
2386
|
+
setListenerPosition(x: number, y: number): void;
|
|
2387
|
+
/**
|
|
2388
|
+
* Configure spatial audio parameters
|
|
2389
|
+
*
|
|
2390
|
+
* @param options - Spatial audio configuration options
|
|
2391
|
+
*
|
|
2392
|
+
* @example
|
|
2393
|
+
* ```typescript
|
|
2394
|
+
* // Configure for a smaller game world
|
|
2395
|
+
* user.configureSpatialAudio({
|
|
2396
|
+
* maxDistance: 100, // Sounds beyond 100 units are silent
|
|
2397
|
+
* referenceDistance: 10, // Full volume within 10 units
|
|
2398
|
+
* rolloffFactor: 1, // Linear attenuation
|
|
2399
|
+
* panSpread: 0.8 // Strong stereo panning
|
|
2400
|
+
* });
|
|
2401
|
+
* ```
|
|
2402
|
+
*/
|
|
2403
|
+
configureSpatialAudio(options: {
|
|
2404
|
+
maxDistance?: number;
|
|
2405
|
+
referenceDistance?: number;
|
|
2406
|
+
rolloffFactor?: number;
|
|
2407
|
+
panSpread?: number;
|
|
2408
|
+
}): void;
|
|
2409
|
+
/**
|
|
2410
|
+
* Get pending audio config commands and clear the queue
|
|
2411
|
+
*
|
|
2412
|
+
* Called by the runtime at the end of each tick to send commands to client.
|
|
2413
|
+
*
|
|
2414
|
+
* @returns Array of audio config commands to send
|
|
2415
|
+
* @internal
|
|
2416
|
+
*/
|
|
2417
|
+
flushAudioConfigCommands(): AudioConfigCommand[];
|
|
2418
|
+
/**
|
|
2419
|
+
* Check if there are pending audio config commands
|
|
2420
|
+
*
|
|
2421
|
+
* @returns true if there are commands to send
|
|
2422
|
+
* @internal
|
|
2423
|
+
*/
|
|
2424
|
+
hasAudioConfigCommands(): boolean;
|
|
2425
|
+
/**
|
|
2426
|
+
* Get pending sound commands and clear the queue
|
|
2427
|
+
*
|
|
2428
|
+
* Called by the runtime at the end of each tick to send commands to client.
|
|
2429
|
+
*
|
|
2430
|
+
* @returns Array of sound commands to send
|
|
2431
|
+
* @internal
|
|
2432
|
+
*/
|
|
2433
|
+
flushSoundCommands(): Array<PlaySoundCommand | StopSoundCommand | FadeOutSoundCommand | PauseSoundCommand | ResumeSoundCommand>;
|
|
2434
|
+
/**
|
|
2435
|
+
* Check if there are pending sound commands
|
|
2436
|
+
*
|
|
2437
|
+
* @returns true if there are commands to send
|
|
2438
|
+
* @internal
|
|
2439
|
+
*/
|
|
2440
|
+
hasSoundCommands(): boolean;
|
|
2441
|
+
/**
|
|
2442
|
+
* Request to send all registered sounds to this user
|
|
2443
|
+
*
|
|
2444
|
+
* Call this when you want to transfer audio assets to the client.
|
|
2445
|
+
* Useful for showing a loading screen before sending large audio files.
|
|
2446
|
+
*
|
|
2447
|
+
* The sounds will be sent at the end of the current tick.
|
|
2448
|
+
*
|
|
2449
|
+
* @example
|
|
2450
|
+
* ```typescript
|
|
2451
|
+
* initUser(core: Core, user: User): void {
|
|
2452
|
+
* // Show loading screen
|
|
2453
|
+
* this.showLoadingScreen(user);
|
|
2454
|
+
*
|
|
2455
|
+
* // Request sounds to be sent
|
|
2456
|
+
* user.sendSounds();
|
|
2457
|
+
* }
|
|
2458
|
+
*
|
|
2459
|
+
* updateUser(core: Core, user: User, deltaTime: number): void {
|
|
2460
|
+
* // Check if sounds are loaded (via client ACK or timeout)
|
|
2461
|
+
* if (user.data.soundsLoaded) {
|
|
2462
|
+
* this.hideLoadingScreen(user);
|
|
2463
|
+
* }
|
|
2464
|
+
* }
|
|
2465
|
+
* ```
|
|
2466
|
+
*/
|
|
2467
|
+
sendSounds(): void;
|
|
2468
|
+
/**
|
|
2469
|
+
* Check if sounds need to be sent to this user
|
|
2470
|
+
*
|
|
2471
|
+
* @returns true if sendSounds() was called
|
|
2472
|
+
* @internal
|
|
2473
|
+
*/
|
|
2474
|
+
needsSendSounds(): boolean;
|
|
2475
|
+
/**
|
|
2476
|
+
* Clear the pending send sounds flag
|
|
2477
|
+
*
|
|
2478
|
+
* Called by the runtime after sending sounds.
|
|
2479
|
+
*
|
|
2480
|
+
* @internal
|
|
2481
|
+
*/
|
|
2482
|
+
clearSendSounds(): void;
|
|
2483
|
+
/**
|
|
2484
|
+
* Set the audio processor for this user
|
|
2485
|
+
*
|
|
2486
|
+
* Called by ClientRuntime to inject the AudioManager.
|
|
2487
|
+
* This enables unified audio handling in both standalone and connected modes.
|
|
2488
|
+
*
|
|
2489
|
+
* @param processor - The audio processor (typically AudioManager)
|
|
2490
|
+
* @internal
|
|
2491
|
+
*/
|
|
2492
|
+
setAudioProcessor(processor: IAudioProcessor): void;
|
|
2493
|
+
/**
|
|
2494
|
+
* Get the audio processor
|
|
2495
|
+
*
|
|
2496
|
+
* @returns The audio processor, or undefined if not set
|
|
2497
|
+
* @internal
|
|
2498
|
+
*/
|
|
2499
|
+
getAudioProcessor(): IAudioProcessor | undefined;
|
|
2500
|
+
/**
|
|
2501
|
+
* Apply audio commands (play/stop/fadeOut/pause/resume sounds)
|
|
2502
|
+
*
|
|
2503
|
+
* This is the unified entry point for audio playback, used by both:
|
|
2504
|
+
* - ClientRuntime (standalone mode): applies commands from local queue
|
|
2505
|
+
* - NetworkSync (connected mode): applies commands received from server
|
|
2506
|
+
*
|
|
2507
|
+
* In server mode, this method does nothing (audio is played on client only).
|
|
2508
|
+
*
|
|
2509
|
+
* @param commands - Array of sound commands
|
|
2510
|
+
* @internal
|
|
2511
|
+
*/
|
|
2512
|
+
applyAudioCommands(commands: Array<PlaySoundCommand | StopSoundCommand | FadeOutSoundCommand | PauseSoundCommand | ResumeSoundCommand>): void;
|
|
2513
|
+
/**
|
|
2514
|
+
* Apply audio configuration commands (listener position, spatial config)
|
|
2515
|
+
*
|
|
2516
|
+
* This is the unified entry point for audio configuration, used by both:
|
|
2517
|
+
* - ClientRuntime (standalone mode): applies commands from local queue
|
|
2518
|
+
* - NetworkSync (connected mode): applies commands received from server
|
|
2519
|
+
*
|
|
2520
|
+
* In server mode, this method does nothing (audio is configured on client only).
|
|
2521
|
+
*
|
|
2522
|
+
* @param commands - Array of audio configuration commands
|
|
2523
|
+
* @internal
|
|
2524
|
+
*/
|
|
2525
|
+
applyAudioConfigCommands(commands: AudioConfigCommand[]): void;
|
|
2212
2526
|
}
|
|
2213
2527
|
|
|
2214
2528
|
/**
|
|
@@ -2459,6 +2773,156 @@ declare class BitmapFontRegistry {
|
|
|
2459
2773
|
getFontCount(): number;
|
|
2460
2774
|
}
|
|
2461
2775
|
|
|
2776
|
+
/**
|
|
2777
|
+
* SoundRegistry - Server-side registry for audio assets
|
|
2778
|
+
*
|
|
2779
|
+
* Stores sound definitions that will be sent to clients.
|
|
2780
|
+
* Supports both File (embedded data) and External (URL reference) modes.
|
|
2781
|
+
*
|
|
2782
|
+
* @example
|
|
2783
|
+
* ```typescript
|
|
2784
|
+
* const registry = new SoundRegistry();
|
|
2785
|
+
*
|
|
2786
|
+
* // Register a sound with embedded data (File mode)
|
|
2787
|
+
* const coinData = fs.readFileSync('./assets/coin.mp3');
|
|
2788
|
+
* registry.registerFile('coin', 'mp3', coinData);
|
|
2789
|
+
*
|
|
2790
|
+
* // Register an external sound (FileExternal mode)
|
|
2791
|
+
* registry.registerExternal('music', 'mp3', 'https://cdn.example.com/music.mp3', 1500000);
|
|
2792
|
+
*
|
|
2793
|
+
* // Generate load packets for client
|
|
2794
|
+
* const packets = registry.toLoadPackets();
|
|
2795
|
+
* ```
|
|
2796
|
+
*/
|
|
2797
|
+
|
|
2798
|
+
/**
|
|
2799
|
+
* Internal representation of a registered sound
|
|
2800
|
+
*/
|
|
2801
|
+
interface SoundEntry {
|
|
2802
|
+
/** Unique sound identifier (0-255) */
|
|
2803
|
+
soundId: number;
|
|
2804
|
+
/** Human-readable name */
|
|
2805
|
+
name: string;
|
|
2806
|
+
/** Loading mode: 'file' (embedded) or 'external' (URL) */
|
|
2807
|
+
loadType: SoundLoadType;
|
|
2808
|
+
/** Audio format */
|
|
2809
|
+
format: SoundFormat;
|
|
2810
|
+
/** Raw audio data (only for 'file' mode) */
|
|
2811
|
+
data?: Uint8Array;
|
|
2812
|
+
/** URL to fetch from (only for 'external' mode) */
|
|
2813
|
+
url?: string;
|
|
2814
|
+
/** Expected file size in bytes */
|
|
2815
|
+
size?: number;
|
|
2816
|
+
/** Checksum for validation */
|
|
2817
|
+
checksum?: string;
|
|
2818
|
+
}
|
|
2819
|
+
/**
|
|
2820
|
+
* SoundRegistry - Manages sound definitions on the server
|
|
2821
|
+
*/
|
|
2822
|
+
declare class SoundRegistry {
|
|
2823
|
+
private sounds;
|
|
2824
|
+
private nameToId;
|
|
2825
|
+
private nextId;
|
|
2826
|
+
/**
|
|
2827
|
+
* Register a sound with embedded data (File mode)
|
|
2828
|
+
* The audio data will be sent directly to clients via UTSP
|
|
2829
|
+
*
|
|
2830
|
+
* @param name - Human-readable name for the sound
|
|
2831
|
+
* @param format - Audio format (mp3, wav, ogg, etc.)
|
|
2832
|
+
* @param data - Raw audio file data
|
|
2833
|
+
* @returns The assigned sound ID
|
|
2834
|
+
*/
|
|
2835
|
+
registerFile(name: string, format: SoundFormat, data: Uint8Array): number;
|
|
2836
|
+
/**
|
|
2837
|
+
* Register a sound with embedded data using a specific ID
|
|
2838
|
+
*
|
|
2839
|
+
* @param soundId - Specific ID to use (0-255)
|
|
2840
|
+
* @param name - Human-readable name for the sound
|
|
2841
|
+
* @param format - Audio format
|
|
2842
|
+
* @param data - Raw audio file data
|
|
2843
|
+
*/
|
|
2844
|
+
registerFileWithId(soundId: number, name: string, format: SoundFormat, data: Uint8Array): void;
|
|
2845
|
+
/**
|
|
2846
|
+
* Register an external sound (FileExternal mode)
|
|
2847
|
+
* Only the URL is sent to clients, they download from the external source
|
|
2848
|
+
*
|
|
2849
|
+
* @param name - Human-readable name for the sound
|
|
2850
|
+
* @param format - Audio format
|
|
2851
|
+
* @param url - URL where the audio file can be downloaded
|
|
2852
|
+
* @param size - Optional file size in bytes (for progress tracking)
|
|
2853
|
+
* @param checksum - Optional checksum for validation
|
|
2854
|
+
* @returns The assigned sound ID
|
|
2855
|
+
*/
|
|
2856
|
+
registerExternal(name: string, format: SoundFormat, url: string, size?: number, checksum?: string): number;
|
|
2857
|
+
/**
|
|
2858
|
+
* Register an external sound using a specific ID
|
|
2859
|
+
*/
|
|
2860
|
+
registerExternalWithId(soundId: number, name: string, format: SoundFormat, url: string, size?: number, checksum?: string): void;
|
|
2861
|
+
/**
|
|
2862
|
+
* Get a sound entry by ID or name
|
|
2863
|
+
*/
|
|
2864
|
+
get(idOrName: number | string): SoundEntry | undefined;
|
|
2865
|
+
/**
|
|
2866
|
+
* Check if a sound exists
|
|
2867
|
+
*/
|
|
2868
|
+
has(idOrName: number | string): boolean;
|
|
2869
|
+
/**
|
|
2870
|
+
* Get all sound entries
|
|
2871
|
+
*/
|
|
2872
|
+
getAll(): SoundEntry[];
|
|
2873
|
+
/**
|
|
2874
|
+
* Get all file-mode sounds
|
|
2875
|
+
*/
|
|
2876
|
+
getFileSounds(): SoundEntry[];
|
|
2877
|
+
/**
|
|
2878
|
+
* Get all external-mode sounds
|
|
2879
|
+
*/
|
|
2880
|
+
getExternalSounds(): SoundEntry[];
|
|
2881
|
+
/**
|
|
2882
|
+
* Get all sound names
|
|
2883
|
+
*/
|
|
2884
|
+
getNames(): string[];
|
|
2885
|
+
/**
|
|
2886
|
+
* Get sound ID by name
|
|
2887
|
+
*/
|
|
2888
|
+
getId(name: string): number | undefined;
|
|
2889
|
+
/**
|
|
2890
|
+
* Generate load packets for all registered sounds
|
|
2891
|
+
* Separates File and External sounds into different packets
|
|
2892
|
+
*
|
|
2893
|
+
* @returns Array of load packets ready to send to clients
|
|
2894
|
+
*/
|
|
2895
|
+
toLoadPackets(): Array<SoundLoadPacket | SoundExternalLoadPacket>;
|
|
2896
|
+
/**
|
|
2897
|
+
* Generate a load packet for a specific sound
|
|
2898
|
+
*/
|
|
2899
|
+
toLoadPacket(idOrName: number | string): SoundLoadPacket | SoundExternalLoadPacket | null;
|
|
2900
|
+
/**
|
|
2901
|
+
* Unregister a sound
|
|
2902
|
+
*/
|
|
2903
|
+
unregister(idOrName: number | string): boolean;
|
|
2904
|
+
/**
|
|
2905
|
+
* Clear all registered sounds
|
|
2906
|
+
*/
|
|
2907
|
+
clear(): void;
|
|
2908
|
+
/**
|
|
2909
|
+
* Get the number of registered sounds
|
|
2910
|
+
*/
|
|
2911
|
+
get size(): number;
|
|
2912
|
+
/**
|
|
2913
|
+
* Get registry statistics
|
|
2914
|
+
*/
|
|
2915
|
+
getStats(): {
|
|
2916
|
+
total: number;
|
|
2917
|
+
file: number;
|
|
2918
|
+
external: number;
|
|
2919
|
+
totalFileSize: number;
|
|
2920
|
+
};
|
|
2921
|
+
private allocateId;
|
|
2922
|
+
private validateId;
|
|
2923
|
+
private checkIdAvailable;
|
|
2924
|
+
}
|
|
2925
|
+
|
|
2462
2926
|
/**
|
|
2463
2927
|
* Engine execution context type
|
|
2464
2928
|
*/
|
|
@@ -2533,6 +2997,7 @@ declare class Core {
|
|
|
2533
2997
|
private spriteRegistry;
|
|
2534
2998
|
private webFontRegistry;
|
|
2535
2999
|
private bitmapFontRegistry;
|
|
3000
|
+
private soundRegistry;
|
|
2536
3001
|
private activeWebFontId;
|
|
2537
3002
|
private _renderCallCount;
|
|
2538
3003
|
private onPaletteChangedCallback?;
|
|
@@ -3516,6 +3981,141 @@ declare class Core {
|
|
|
3516
3981
|
* @internal
|
|
3517
3982
|
*/
|
|
3518
3983
|
getSpriteRegistry(): SpriteRegistry;
|
|
3984
|
+
/**
|
|
3985
|
+
* Gets the sound registry
|
|
3986
|
+
*
|
|
3987
|
+
* Use this to access the full SoundRegistry API for advanced operations.
|
|
3988
|
+
*
|
|
3989
|
+
* @returns The SoundRegistry instance
|
|
3990
|
+
*
|
|
3991
|
+
* @example
|
|
3992
|
+
* ```typescript
|
|
3993
|
+
* const registry = core.getSoundRegistry();
|
|
3994
|
+
* console.log(`${registry.size} sounds registered`);
|
|
3995
|
+
* ```
|
|
3996
|
+
*/
|
|
3997
|
+
getSoundRegistry(): SoundRegistry;
|
|
3998
|
+
/**
|
|
3999
|
+
* Loads and registers a sound from a file path
|
|
4000
|
+
*
|
|
4001
|
+
* Works in both Node.js and browser environments:
|
|
4002
|
+
* - Node.js: loads synchronously with fs.readFileSync
|
|
4003
|
+
* - Browser: loads asynchronously with fetch
|
|
4004
|
+
*
|
|
4005
|
+
* Format is auto-detected from file extension.
|
|
4006
|
+
*
|
|
4007
|
+
* @param name - Human-readable name (e.g., 'coin', 'explosion')
|
|
4008
|
+
* @param path - Path to the audio file (relative or absolute)
|
|
4009
|
+
* @returns Promise resolving to the assigned sound ID (0-255)
|
|
4010
|
+
*
|
|
4011
|
+
* @example
|
|
4012
|
+
* ```typescript
|
|
4013
|
+
* // In init() - same code works on server and client
|
|
4014
|
+
* async init(core: Core): Promise<void> {
|
|
4015
|
+
* await core.loadSound('coin', './sounds/coin.mp3');
|
|
4016
|
+
* await core.loadSound('jump', './sounds/jump.wav');
|
|
4017
|
+
* }
|
|
4018
|
+
* ```
|
|
4019
|
+
*/
|
|
4020
|
+
loadSound(name: string, path: string): Promise<number>;
|
|
4021
|
+
/**
|
|
4022
|
+
* Loads multiple sounds at once
|
|
4023
|
+
*
|
|
4024
|
+
* @param sounds - Object mapping sound names to file paths
|
|
4025
|
+
* @returns Promise resolving to object mapping names to IDs
|
|
4026
|
+
*
|
|
4027
|
+
* @example
|
|
4028
|
+
* ```typescript
|
|
4029
|
+
* async init(core: Core): Promise<void> {
|
|
4030
|
+
* await core.loadSounds({
|
|
4031
|
+
* coin: './sounds/coin.mp3',
|
|
4032
|
+
* jump: './sounds/jump.wav',
|
|
4033
|
+
* hit: './sounds/hit.ogg',
|
|
4034
|
+
* });
|
|
4035
|
+
* }
|
|
4036
|
+
* ```
|
|
4037
|
+
*/
|
|
4038
|
+
loadSounds(sounds: Record<string, string>): Promise<Record<string, number>>;
|
|
4039
|
+
/**
|
|
4040
|
+
* Detects audio format from file extension
|
|
4041
|
+
*/
|
|
4042
|
+
private detectSoundFormat;
|
|
4043
|
+
/**
|
|
4044
|
+
* Loads sound data from path (isomorphic: Node.js or browser)
|
|
4045
|
+
*/
|
|
4046
|
+
private loadSoundData;
|
|
4047
|
+
/**
|
|
4048
|
+
* Registers a sound with embedded data (File mode) - Low-level API
|
|
4049
|
+
*
|
|
4050
|
+
* The audio data will be sent to clients via UTSP protocol.
|
|
4051
|
+
* Use this for small sounds that should be guaranteed to arrive.
|
|
4052
|
+
*
|
|
4053
|
+
* @param name - Human-readable name (e.g., 'coin', 'explosion')
|
|
4054
|
+
* @param format - Audio format ('mp3', 'wav', 'ogg', etc.)
|
|
4055
|
+
* @param data - Raw audio file data as Uint8Array or Buffer
|
|
4056
|
+
* @returns The assigned sound ID (0-255)
|
|
4057
|
+
*
|
|
4058
|
+
* @example
|
|
4059
|
+
* ```typescript
|
|
4060
|
+
* // If you already have the data
|
|
4061
|
+
* core.registerSound('coin', 'mp3', myAudioData);
|
|
4062
|
+
* ```
|
|
4063
|
+
*/
|
|
4064
|
+
registerSound(name: string, format: SoundFormat, data: Uint8Array): number;
|
|
4065
|
+
/**
|
|
4066
|
+
* Registers an external sound (FileExternal mode)
|
|
4067
|
+
*
|
|
4068
|
+
* Only the URL is sent to clients, who download from the external source.
|
|
4069
|
+
* Use this for large sounds (music) to reduce UTSP bandwidth.
|
|
4070
|
+
*
|
|
4071
|
+
* @param name - Human-readable name (e.g., 'background-music')
|
|
4072
|
+
* @param format - Audio format ('mp3', 'wav', 'ogg', etc.)
|
|
4073
|
+
* @param url - URL where clients can download the audio
|
|
4074
|
+
* @param size - Optional file size in bytes (for progress tracking)
|
|
4075
|
+
* @returns The assigned sound ID (0-255)
|
|
4076
|
+
*
|
|
4077
|
+
* @example
|
|
4078
|
+
* ```typescript
|
|
4079
|
+
* const soundId = core.registerExternalSound(
|
|
4080
|
+
* 'background-music',
|
|
4081
|
+
* 'mp3',
|
|
4082
|
+
* 'https://cdn.example.com/music/theme.mp3',
|
|
4083
|
+
* 1_500_000 // 1.5 MB
|
|
4084
|
+
* );
|
|
4085
|
+
* ```
|
|
4086
|
+
*/
|
|
4087
|
+
registerExternalSound(name: string, format: SoundFormat, url: string, size?: number): number;
|
|
4088
|
+
/**
|
|
4089
|
+
* Checks if a sound is registered
|
|
4090
|
+
*
|
|
4091
|
+
* @param nameOrId - Sound name (string) or ID (number)
|
|
4092
|
+
* @returns true if sound exists
|
|
4093
|
+
*
|
|
4094
|
+
* @example
|
|
4095
|
+
* ```typescript
|
|
4096
|
+
* if (core.hasSound('coin')) {
|
|
4097
|
+
* console.log('Coin sound is ready');
|
|
4098
|
+
* }
|
|
4099
|
+
* ```
|
|
4100
|
+
*/
|
|
4101
|
+
hasSound(nameOrId: string | number): boolean;
|
|
4102
|
+
/**
|
|
4103
|
+
* Generates LoadPackets for all registered sounds
|
|
4104
|
+
*
|
|
4105
|
+
* Returns separate packets for File and External sounds.
|
|
4106
|
+
* Send these to clients during initial connection.
|
|
4107
|
+
*
|
|
4108
|
+
* @returns Array of sound load packets
|
|
4109
|
+
*
|
|
4110
|
+
* @example
|
|
4111
|
+
* ```typescript
|
|
4112
|
+
* const soundPackets = core.generateSoundLoadPackets();
|
|
4113
|
+
* soundPackets.forEach(packet => {
|
|
4114
|
+
* socket.emit('sound-load', packet);
|
|
4115
|
+
* });
|
|
4116
|
+
* ```
|
|
4117
|
+
*/
|
|
4118
|
+
generateSoundLoadPackets(): Array<_utsp_types.SoundLoadPacket | _utsp_types.SoundExternalLoadPacket>;
|
|
3519
4119
|
/**
|
|
3520
4120
|
* Loads the default web font (Courier New, 16px, monospace)
|
|
3521
4121
|
*
|
|
@@ -4829,5 +5429,5 @@ declare class UpdatePacketDecoder {
|
|
|
4829
5429
|
private checkSize;
|
|
4830
5430
|
}
|
|
4831
5431
|
|
|
4832
|
-
export { ASCII_8X8_FONT, BITMASK16_ORDER_MIN_SIZE, BITMASK4_ORDER_MIN_SIZE, BITMASK_ORDER_MIN_SIZE, BitmapFont, BitmapFontRegistry, CHAR_ORDER_SIZE, CIRCLE_SHAPE_SIZE, CLEAR_ORDER_SIZE, COLORMAP_ORDER_MIN_SIZE, COLOR_SKIP, CellBuffer, CharCodeBuffer, Core, CoreStats, DISPLAY_HEADER_SIZE, DOTCLOUD_MULTICOLOR_ORDER_MIN_SIZE, DOTCLOUD_ORDER_MIN_SIZE, Display, ELLIPSE_SHAPE_SIZE, FILLCHAR_ORDER_MIN_SIZE, FILLSPRITE_MULTICOLOR_ORDER_SIZE, FILLSPRITE_ORDER_SIZE, FULLFRAME_MULTICOLOR_ORDER_MIN_SIZE, FULLFRAME_ORDER_MIN_SIZE, FontType, InputBindingRegistry, LAYER_CELL_COUNT, LAYER_HEADER_SIZE, LAYER_SIZE, LINE_SHAPE_SIZE, Layer, LoadType, OrderBuilder, OrderType, RECTANGLE_SHAPE_SIZE, SHAPE_ORDER_MIN_SIZE, SPRITECLOUD_MULTICOLOR_ORDER_MIN_SIZE, SPRITECLOUD_ORDER_MIN_SIZE, SPRITECLOUD_VARIED_MULTICOLOR_ORDER_MIN_SIZE, SPRITECLOUD_VARIED_ORDER_MIN_SIZE, SPRITE_MULTICOLOR_ORDER_SIZE, SPRITE_ORDER_SIZE, SUBFRAME_MULTICOLOR_ORDER_MIN_SIZE, SUBFRAME_ORDER_MIN_SIZE, ShapeType, SpriteRegistry, TEXT_MULTILINE_ORDER_MIN_SIZE, TEXT_ORDER_MIN_SIZE, TRIANGLE_SHAPE_SIZE, TRIGGERGLOBALSOUND_ORDER_SIZE, TRIGGERSOUND_ORDER_SIZE, UPDATE_PACKET_HEADER_SIZE, UpdateFlags, UpdateFlagsHelper, UpdatePacketDecoder, User, UserStats, WebFont, WebFontRegistry, createASCII8x8FontLoad, createEmptyCompressedInputPacket, decodeCompressedInput, decodeInt8ToAxis, encodeAxisToInt8, encodeCompressedInput, getASCII8x8FontConfig, getAllCharCodes, getButtonByteCount, getCharBitmap, getCompressedPacketSize, getOrderTypeName, hasChar, isValidOrderType };
|
|
4833
|
-
export type { AnyLoad, BitmapFontConfig, BitmapFontLoad, Bitmask16Order, Bitmask16Variant, Bitmask4Order, Bitmask4Variant, BitmaskOrder, Cell, CircleShape, Color, ColorPaletteLoad, CompressedInputPacket, CoreMode, CoreOptions, EllipseShape, LineShape, MulticolorCell, MulticolorSprite, MulticolorSpriteLoad, NetworkDisplay, NetworkLayer, RectangleShape, ShapeData, SoundLoad, SpriteLoad, TickStats, TriangleShape, UnicolorSprite, UpdatePacket, UserTickStats, WebFontConfig, WebFontLoad };
|
|
5432
|
+
export { ASCII_8X8_FONT, BITMASK16_ORDER_MIN_SIZE, BITMASK4_ORDER_MIN_SIZE, BITMASK_ORDER_MIN_SIZE, BitmapFont, BitmapFontRegistry, CHAR_ORDER_SIZE, CIRCLE_SHAPE_SIZE, CLEAR_ORDER_SIZE, COLORMAP_ORDER_MIN_SIZE, COLOR_SKIP, CellBuffer, CharCodeBuffer, Core, CoreStats, DISPLAY_HEADER_SIZE, DOTCLOUD_MULTICOLOR_ORDER_MIN_SIZE, DOTCLOUD_ORDER_MIN_SIZE, Display, ELLIPSE_SHAPE_SIZE, FILLCHAR_ORDER_MIN_SIZE, FILLSPRITE_MULTICOLOR_ORDER_SIZE, FILLSPRITE_ORDER_SIZE, FULLFRAME_MULTICOLOR_ORDER_MIN_SIZE, FULLFRAME_ORDER_MIN_SIZE, FontType, InputBindingRegistry, LAYER_CELL_COUNT, LAYER_HEADER_SIZE, LAYER_SIZE, LINE_SHAPE_SIZE, Layer, LoadType, OrderBuilder, OrderType, RECTANGLE_SHAPE_SIZE, SHAPE_ORDER_MIN_SIZE, SPRITECLOUD_MULTICOLOR_ORDER_MIN_SIZE, SPRITECLOUD_ORDER_MIN_SIZE, SPRITECLOUD_VARIED_MULTICOLOR_ORDER_MIN_SIZE, SPRITECLOUD_VARIED_ORDER_MIN_SIZE, SPRITE_MULTICOLOR_ORDER_SIZE, SPRITE_ORDER_SIZE, SUBFRAME_MULTICOLOR_ORDER_MIN_SIZE, SUBFRAME_ORDER_MIN_SIZE, ShapeType, SoundRegistry, SpriteRegistry, TEXT_MULTILINE_ORDER_MIN_SIZE, TEXT_ORDER_MIN_SIZE, TRIANGLE_SHAPE_SIZE, TRIGGERGLOBALSOUND_ORDER_SIZE, TRIGGERSOUND_ORDER_SIZE, UPDATE_PACKET_HEADER_SIZE, UpdateFlags, UpdateFlagsHelper, UpdatePacketDecoder, User, UserStats, WebFont, WebFontRegistry, createASCII8x8FontLoad, createEmptyCompressedInputPacket, decodeCompressedInput, decodeInt8ToAxis, encodeAxisToInt8, encodeCompressedInput, getASCII8x8FontConfig, getAllCharCodes, getButtonByteCount, getCharBitmap, getCompressedPacketSize, getOrderTypeName, hasChar, isValidOrderType };
|
|
5433
|
+
export type { AnyLoad, BitmapFontConfig, BitmapFontLoad, Bitmask16Order, Bitmask16Variant, Bitmask4Order, Bitmask4Variant, BitmaskOrder, Cell, CircleShape, Color, ColorPaletteLoad, CompressedInputPacket, CoreMode, CoreOptions, EllipseShape, LineShape, MulticolorCell, MulticolorSprite, MulticolorSpriteLoad, NetworkDisplay, NetworkLayer, RectangleShape, ShapeData, SoundEntry, SoundLoad, SpriteLoad, TickStats, TriangleShape, UnicolorSprite, UpdatePacket, UserTickStats, WebFontConfig, WebFontLoad };
|