soundUtil Library

This documentation explains how to use the soundUtil library to play sound effects and background music in your workshop node.

Introduction

The soundUtil library provides a comprehensive set of functions for managing audio in your workshop node. It allows you to:

• Play sounds for hosts, clients, or everyone
• Register custom sounds
• Play background music with looping
• Control volume, fade-in, and fade-out effects
• Target specific users or groups for sounds

Key Concepts

State Management

All sounds are stored in the workshop state. The library manages:

• Sound registrations
• Currently playing looping sounds
• Sending a list of sounds used in the workshop for preloading on client side.

Sound Registration

Before playing a sound, it must be registered using soundUtil_RegisterSounds(). This ensures that:

1. The sound is preloaded on the client on match join.
2. The sounds can be overwritten by simply registering the sound name with a diffrent url.
3. The URL is properly formatted

Node Sounds

Workshop nodes can have associated sounds that are played when the node is displayed.

Automatic Sound Assignment

If a sound is not explicitly defined in the Workshop JSON for a node, the library will attempt to assign a default sound based on the node type.

Overriding Default Behavior

To prevent the automatic sound assignment or to use a custom sound, you can explicitly define the sound variable for the node. This will override the default behavior.

Example: Timer Node

The Timer node demonstrates the default behavior. By default, it is configured to play a countdown sound when the node is shown.

Sound Playback

Sounds can be played with various functions depending on who should hear them:

• soundUtil_playSoundTarget() - Play for a specific target (host, client, everyone)
• soundUtil_playSoundHost() - Play only for the host
• soundUtil_playSoundPlayers() - Play only for clients
• soundUtil_playSoundEveryone() - Play for everyone
• soundUtil_playSoundPresence() - Play for specific list of users

Sound Target Types

The library defines three targets for sound playback:

enum soundUtil_Target {
  Host, // Only the host will hear the sound
  Client, // Only the clients will hear the sound
  Everyone, // Everyone will hear the sound
}

Default Sounds

The library comes with built-in sounds you can use immediately:

enum soundUtil_DefaultSounds {
  Plop = 'plop',
  TestBg = 'testbg',
  TRexRoar = 'trexroar',
  CountUp1 = 'countup1',
  // ... and many more
}

Registering Sounds

Basic Registration

// Register default sounds
soundUtil_RegisterSounds(state, ctx, [
  {
    name: soundUtil_DefaultSounds.CountDownRand,
    target: soundUtil_Target.Host,
  },
  {
    name: soundUtil_DefaultSounds.DrumHit,
    target: soundUtil_Target.Everyone,
  },
]);

Custom Sound Registration

// Register a custom sound
soundUtil_RegisterSounds(state, ctx, [
  {
    name: 'my-custom-sound',
    target: soundUtil_Target.Everyone,
    url: '/sounds/my-custom-sound.wav',
  },
]);

Multiple Sound Variations

// Register multiple variations of the same sound (one will be chosen randomly)
soundUtil_RegisterSounds(state, ctx, [
  {
    name: 'background-music',
    target: soundUtil_Target.Everyone,
    url: [
      '/sounds/background1.wav',
      '/sounds/background2.wav',
      '/sounds/background3.wav',
    ],
  },
]);

Playing Sounds

Basic Playback

// Play a sound for the host
soundUtil_playSoundTarget(
  state,
  logger,
  dispatcher,
  soundUtil_DefaultSounds.CountDownRand, // sound name
  0.5, // volume (0-3)
  soundUtil_Target.Host, // target audience
  false, // looping (true/false)
  0, // fade-in time (seconds)
  0 // fade-out time (seconds)
);

Playing Sound for Everyone

soundUtil_playSoundEveryone(
  state,
  dispatcher,
  logger,
  'background-music', // sound name
  true, // looping
  0.3, // volume
  2, // fade-in time
  2 // fade-out time
);

Stopping All Sounds

// Stop all currently playing sounds
soundUtil_stopSoundsEveryone(state, dispatcher);

Advanced Features

Looping Background Music

// Play looping background music
soundUtil_playSoundTarget(
  state,
  logger,
  dispatcher,
  soundUtil_DefaultSounds.Background,
  0.3, // lower volume for background
  soundUtil_Target.Everyone,
  true, // enable looping
  2, // 2 second fade-in
  2 // 2 second fade-out
);

Targeting Specific Users

// Play a sound only for specific users
soundUtil_playSoundPresence(
  state,
  dispatcher,
  logger,
  'achievement-sound',
  userPresences, // array of nkruntime.Presence objects
  1.0, // volume
  false, // no looping
  0.5, // fade-in
  0 // fade-out
);

Common Use Cases

Quiz Node Example

The QuizNode example demonstrates how to use sounds for different states of a quiz:

// In constructor - register required sounds
soundUtil_RegisterSounds(state, ctx, [
  {
    name: soundUtil_DefaultSounds.CountDownRand,
    target: soundUtil_Target.Host,
  },
  {
    name: soundUtil_DefaultSounds.DrumHit,
    target: soundUtil_Target.Host,
  },
  {
    name: soundUtil_DefaultSounds.CountUpRand,
    target: soundUtil_Target.Host,
  },
]);

// Play countdown sound when quiz begins
soundUtil_playSoundTarget(
  state,
  workshop.logger,
  workshop.dispatcher,
  soundUtil_DefaultSounds.CountDownRand,
  0.5,
  soundUtil_Target.Host,
  false,
  0,
  0
);

// Play drum hit when revealing answers
soundUtil_playSoundTarget(
  state,
  workshop.logger,
  workshop.dispatcher,
  soundUtil_DefaultSounds.DrumHit,
  0.5,
  soundUtil_Target.Host,
  false,
  0,
  0
);

// Play scoreboard sound when showing scores
soundUtil_playSoundTarget(
  state,
  workshop.logger,
  workshop.dispatcher,
  soundUtil_DefaultSounds.CountUpRand,
  0.5,
  soundUtil_Target.Host,
  false,
  0,
  0
);

API Reference

Registration Functions

soundUtil_RegisterSounds(state, ctx, sounds)

Registers sounds to be played in the workshop.

Parameter	Type	Description
state	workshop_State	State of the workshop
ctx	nkruntime.Context	Context of the workshop
sounds	soundUtil_SoundRegister[]	Array of sounds to register

Playback Functions

soundUtil_playSoundTarget(state, logger, dispatcher, sound, volume, target, repeat, fadein, fadeout)

Plays a sound for a specific target audience.

Parameter	Type	Default	Description
state	workshop_State	-	State of the workshop
logger	nkruntime.Logger	-	Logger for logging
dispatcher	nkruntime.MatchDispatcher	-	Dispatcher to send messages
sound	soundUtil_DefaultSounds | string	-	Sound to play
volume	number	0.5	Volume (0-3)
target	soundUtil_Target	Host	Target audience
repeat	boolean	false	Whether to loop the sound
fadein	number	0.5	Fade-in time in seconds
fadeout	number	0.5	Fade-out time in seconds

soundUtil_playSoundHost(state, logger, dispatcher, sound, repeat, volume, fadein, fadeout)

Plays a sound for the host only.

soundUtil_playSoundPlayers(state, dispatcher, logger, sound, repeat, volume, fadein, fadeout)

Plays a sound for all clients only.

soundUtil_playSoundEveryone(state, dispatcher, logger, sound, repeat, volume, fadein, fadeout)

Plays a sound for everyone.

soundUtil_playSoundPresence(state, dispatcher, logger, sound, presences, volume, repeat, fadein, fadeout)

Plays a sound for specific presences.

Management Functions

soundUtil_stopSoundsEveryone(state, dispatcher)

Stops all sounds that are currently playing.