Sound and music

phantom.aj.soundThe screen and sound

Sound and music volume.

Scripts and plugins

A script has all of it, as phantom.aj.sound, and so does a plugin, from ctx.phantom(): the SDK runs in the plugin's own frame. Each call is marked with what it needs: game:read for what the area knows and hears, which "game": "read" in the manifest grants, and game:act for doing things in it as the player, which needs "game": "act" (see Permissions).

Overview

Member	What it does	Plugins
`apply()`	Puts the audio to a whole set of settings at once: what `current()` gave, or any part of it.	`game:act`
`banks()`	Which of the banks of sounds the client loads only when it needs them are in.	`game:read`
`current()`	What the audio is set to now, or null before the client has set its audio up.	`game:read`
`effects()`	Every named sound `play` takes, for a tool that offers them.	`game:read`
`isBankLoaded()`	Whether one bank of sounds is in (`AJAudio.hasLoadedGiftUnwrapSfx` and kin).	`game:read`
`keepMusicVolume()`	Holds the room's music at a level, 0 to 1, from track to track, until the handle is called, which puts the track playing then back to its own level.	`game:act`
`pause()`	Pauses the sound effects, the music, or both where they are (`SBAudio.pauseSounds`, `pauseMusic`, `pauseAll`), until the handle carries them on.	`game:act`
`play()`	Plays one of the client's own sounds on this computer, as the game plays it (`SBAudio.playCachedSound`): a named one (`'achievement'`, `effects()` lists them) or any cached sound by the name the client cached it under (`'GemsEarnedSound'`).	`game:act`
`setMuted()`	Mutes or unmutes the sound effects, the music, or both, through the client's own calls (`SBAudio.muteSounds`, `muteMusic`, `muteAll` and their `unmute`), which keep the choice for the next game.	`game:act`
`setVolume()`	Sets a level, 0 to 1, for everything (`SBAudio.setVolumeAll`), or only the sound effects or the music playing now (`setVolumeSounds`, `setVolumeMusic`).	`game:act`
`silence()`	Mutes everything, and gives back what puts the audio back as it was: a player who had the music off before is owed it off afterwards.	`game:act`
`stop()`	Stops every sound effect, the music, or both (`SBAudio.stopSounds`, `stopMusic`, `stopAll`).	`game:act`
`toggleMute()`	Turns both the other way about (`SBAudio.toggleMuteAll`), which is what the HUD's sound button does, and resolves with where that left them.	`game:act`
`onChange()`	Hears the audio change, whoever changed it: the HUD's sound button, the Settings screen, the client, this area.	`game:read`
`onPlay()`	Hears every cached sound the client plays, its own clicks and chimes as much as `play`'s.	`game:read`
`onStop()`	Hears every cached sound the client stops.	`game:read`

Methods

`apply`

methodplugins · game:act

TypeScript

apply(settings: Partial<SoundSettings>, options?: ActOptions) => Promise<SoundSettings>

Puts the audio to a whole set of settings at once: what current() gave, or any part of it. The mutes are kept for next time as the HUD's button keeps them; the levels are not.

Parameters

Name	Type
`settings`	`Partial<SoundSettings>`
`options` optional	`ActOptions`

Returns

Promise<SoundSettings>

Types

SoundSettings · ActOptions

`banks`

methodplugins · game:read

TypeScript

banks() => Promise<Record<"gift" | "trade" | "dailySpin" | "journeyBookWorld" | "journeyBookBook" | "petCreate", boolean>>

Which of the banks of sounds the client loads only when it needs them are in. A sound in a bank that is not is silent: play throws NOT_READY for one.

Returns

`current`

methodplugins · game:read

TypeScript

current() => Promise<SoundSettings | null>

What the audio is set to now, or null before the client has set its audio up.

Returns

Promise<SoundSettings \| null>

Types

SoundSettings

`effects`

methodplugins · game:read

TypeScript

effects() => ("newspaper" | "doorBell" | "dailySpin" | "hudButtonOver" | "hudButtonClick" | "menuButtonOver" | "menuButtonClick" | "exitButtonOver" | "exitButtonClick" | "scrollUpDown" | "scrollLeftRight" | "textType" | "textEnter" | "idleWarning" | "shopCaching" | "gemsEarned" | "itemRecycled" | "mailReceived" | "mailSent" | "buddyOnlineOffline" | "achievement" | "buddyCardOpen" | "buddyCardClose" | "limitedChatError" | "chatOpen" | "chatClose" | "randomLever" | "nameGenRotation" | "nameGenStop" | "giftUnwrap" | "treasureUnwrap" | "treasureBagUnwrap" | "treasureLuckyUnwrap" | "treasureEggUnwrap" | "journeyBookPrize" | "journeyBookOpen" | "journeyBookClose" | "journeyBookBookOpen" | "journeyBookBookClose" | "tradeSuccess" | "tradeFailed" | "tradeRequest" | "petCreateFinish")[]

Every named sound play takes, for a tool that offers them.

Returns

`isBankLoaded`

methodplugins · game:read

TypeScript

isBankLoaded(bank: "gift" | "trade" | "dailySpin" | "journeyBookWorld" | "journeyBookBook" | "petCreate") => Promise<boolean>

Whether one bank of sounds is in (AJAudio.hasLoadedGiftUnwrapSfx and kin).

Parameters

Name	Type
`bank`	`"gift" \| "trade" \| "dailySpin" \| "journeyBookWorld" \| "journeyBookBook" \| "petCreate"`

Returns

Promise<boolean>

`keepMusicVolume`

methodplugins · game:act

TypeScript

keepMusicVolume(volume: number, options?: ActOptions) => Promise<() => Promise<void>>

Holds the room's music at a level, 0 to 1, from track to track, until the handle is called, which puts the track playing then back to its own level. setVolume changes only the track playing now, since every room starts its own at its own level (SBMusic.playNewMusic). This writes _roomMusic.volume in the game whenever the music is not muted (the client's setter would unmute it), so the HUD's button, a video and the bulletin board mute it as ever. Not a minigame's own sounds.

Parameters

Name	Type
`volume`	`number`
`options` optional	`ActOptions`

Returns

Promise<() => Promise<void>>

Types

ActOptions

`pause`

methodplugins · game:act

TypeScript

pause(part?: SoundPart, options?: ActOptions) => Promise<() => Promise<void>>

Pauses the sound effects, the music, or both where they are (SBAudio.pauseSounds, pauseMusic, pauseAll), until the handle carries them on. Unlike muting, it is not kept.

Parameters

Name	Type
`part` optional	`SoundPart`
`options` optional	`ActOptions`

Returns

Promise<() => Promise<void>>

Types

SoundPart · ActOptions

`play`

methodplugins · game:act

TypeScript

play(sound: string, options?: ActOptions & { loops?: number | undefined; }) => Promise<PlayingSound>

Plays one of the client's own sounds on this computer, as the game plays it (SBAudio.playCachedSound): a named one ('achievement', effects() lists them) or any cached sound by the name the client cached it under ('GemsEarnedSound'). Resolves with what stops it. Where the client would play nothing it says why instead: NOT_READY for a sound not cached or a bank not loaded, REFUSED while the music is muted, which silences every interface sound.

Parameters

Name	Type
`sound`	`string`
`options` optional	`ActOptions & { loops?: number \| undefined; }`

Returns

Promise<PlayingSound>

Types

PlayingSound · ActOptions

Example

TypeScript

const warning = await phantom.aj.sound.play('idleWarning', { loops: 5 });
await warning();

Run in Phantom

`setMuted`

methodplugins · game:act

TypeScript

setMuted(muted: boolean, options?: ActOptions & { only?: "music" | "sounds" | undefined; }) => Promise<SoundSettings>

Mutes or unmutes the sound effects, the music, or both, through the client's own calls (SBAudio.muteSounds, muteMusic, muteAll and their unmute), which keep the choice for the next game. The HUD's sound button and the Settings screen's toggle are redrawn to match. Resolves with the audio afterwards; REFUSED when the client's flags did not follow.

Parameters

Name	Type
`muted`	`boolean`
`options` optional	`ActOptions & { only?: "music" \| "sounds" \| undefined; }`

Returns

Promise<SoundSettings>

Types

ActOptions · SoundSettings

Example

TypeScript

await phantom.aj.sound.setMuted(true, { only: 'music' });

Run in Phantom

`setVolume`

methodplugins · game:act

TypeScript

setVolume(volume: number, options?: ActOptions & { only?: "music" | "sounds" | undefined; }) => Promise<SoundSettings>

Sets a level, 0 to 1, for everything (SBAudio.setVolumeAll), or only the sound effects or the music playing now (setVolumeSounds, setVolumeMusic). Anything outside 0 to 1 is brought in. The client keeps no level for next time, and each room starts its track at its own (keepMusicVolume holds one). Resolves with the audio afterwards.

Parameters

Name	Type
`volume`	`number`
`options` optional	`ActOptions & { only?: "music" \| "sounds" \| undefined; }`

Returns

Promise<SoundSettings>

Types

SoundSettings · ActOptions

`silence`

methodplugins · game:act

TypeScript

silence(options?: ActOptions) => Promise<() => Promise<void>>

Mutes everything, and gives back what puts the audio back as it was: a player who had the music off before is owed it off afterwards. Muting is kept for next time, as the HUD's button keeps it, so keep the handle.

Parameters

Name	Type
`options` optional	`ActOptions`

Returns

Promise<() => Promise<void>>

Types

ActOptions

Example

TypeScript

const restore = await phantom.aj.sound.silence();
await restore();

Run in Phantom

`stop`

methodplugins · game:act

TypeScript

stop(part?: SoundPart, options?: ActOptions) => Promise<void>

Stops every sound effect, the music, or both (SBAudio.stopSounds, stopMusic, stopAll). Stopped music comes back with the next room; new sounds play as ever.

Parameters

Name	Type
`part` optional	`SoundPart`
`options` optional	`ActOptions`

Returns

Promise<void>

Types

ActOptions · SoundPart

`toggleMute`

methodplugins · game:act

TypeScript

toggleMute(options?: ActOptions) => Promise<SoundSettings>

Turns both the other way about (SBAudio.toggleMuteAll), which is what the HUD's sound button does, and resolves with where that left them. Each is flipped on its own, so with only one muted they swap.

Parameters

Name	Type
`options` optional	`ActOptions`

Returns

Promise<SoundSettings>

Types

SoundSettings · ActOptions

Events

`onChange`

eventplugins · game:read

TypeScript

onChange(listener: (settings: SoundSettings, previous: SoundSettings | null) => void, options?: { everyFrames?: number | undefined; }) => () => void

Hears the audio change, whoever changed it: the HUD's sound button, the Settings screen, the client, this area. Told at once with the audio now, then on every change (looked at every everyFrames, 6 by default), with the settings before.

Parameters

Name	Type
`listener`	`(settings: SoundSettings, previous: SoundSettings \| null) => void`
`options` optional	`{ everyFrames?: number \| undefined; }`

Returns

() => void. Call it to stop listening.

Types

SoundSettings

`onPlay`

eventplugins · game:read

TypeScript

onPlay(listener: (play: SoundPlay) => void) => () => void

Hears every cached sound the client plays, its own clicks and chimes as much as play's.

Parameters

Name	Type
`listener`	`(play: SoundPlay) => void`

Returns

() => void. Call it to stop listening.

Types

SoundPlay

`onStop`

eventplugins · game:read

TypeScript

onStop(listener: (play: SoundPlay) => void) => () => void

Hears every cached sound the client stops.

Parameters

Name	Type
`listener`	`(play: SoundPlay) => void`

Returns

() => void. Call it to stop listening.

Types

SoundPlay

Types

The types the calls above take and give, with every field. Import any of them in a plugin from @phantomclient/plugin/sdk, or use them as they are in a script.

`SoundSettings`

What the game's audio is set to.

Field	Type
`soundsMuted`	`boolean`	The game's sound effects are muted (`SBAudio.areSoundsMuted`).
`musicMuted`	`boolean`	The music is muted (`SBAudio.isMusicMuted`). The client plays none of its interface sounds while it is, whatever `soundsMuted` says.
`volume`	`number \| null`	Everything's level, 0 to 1 (`SBAudio.currentVolume`).
`musicVolume`	`number \| null`	The room music's level, 0 to 1: 0 while muted, null with no music playing.

`ActOptions`

How long something that acts may take, and what may end it first.

Field	Type
`timeoutMs` optional	`number \| undefined`	10 seconds by default.
`signal` optional	`AbortSignal \| undefined`

`SoundPart`

Which of the game's audio an act is about: its sound effects, its music, or both.

TypeScript

type SoundPart = 'sounds' | 'music' | 'all'

`PlayingSound`

A cached sound playing, which stops it when called.

TypeScript

type PlayingSound = (() => Promise<void>) & {
  /** The name the client cached it under. */
  readonly sound: string;
  readonly loops: number;
}

`SoundPlay`

One of a cached sound's plays or stops, whoever asked for it.

Field	Type
`sound`	`string`	The name the client cached it under (`GemsEarnedSound`).
`loops`	`number`	How many times through: 1 for a stop.

Sound and music ​

Overview ​

Methods ​

apply ​

banks ​

current ​

effects ​

isBankLoaded ​

keepMusicVolume ​

pause ​

play ​

setMuted ​

setVolume ​

silence ​

stop ​

toggleMute ​

Events ​

onChange ​

onPlay ​

onStop ​

Types ​

SoundSettings ​

ActOptions ​

SoundPart ​

PlayingSound ​

SoundPlay ​

Sound and music

Overview

Methods

`apply`

`banks`

`current`

`effects`

`isBankLoaded`

`keepMusicVolume`

`pause`

`play`

`setMuted`

`setVolume`

`silence`

`stop`

`toggleMute`

Events

`onChange`

`onPlay`

`onStop`

Types

`SoundSettings`

`ActOptions`

`SoundPart`

`PlayingSound`

`SoundPlay`