Audio
Volver a la referencia

Audio

Sound, music in layers, zones and the listener.

19 símbolos

useAudiofunctionhooknacatamalon

useAudio() => TAudioHandle

The game's volumes: the general one and one per channel, plus a way to silence everything.

A channel is a group of sounds that share a volume. 'sfx' and 'music' are there from the start, and any other name works the moment a sound uses it. This is what the sliders of an options screen move, and the numbers a game saves in its store so they are still there next time.

Volumes go from 0 (silent) to 1 (as recorded); above 1 is allowed and can distort.

Ejemplo

declare const settings: TGameStore<{ music: number }>;
declare const quieter: TText;

export const Options: TSceneFn = () => {
    const audio = useAudio();
    audio.setVolume(settings.state.music, 'music');

    listen(quieter, { onClick: () => audio.setVolume(audio.getVolume('music') - 0.1, 'music') });
    return createScene();
};
Ver el código · hooks/audio/use_audio.ts:34

useAudioListenerfunctionhooknacatamalon

useAudioListener(options: { enabled }) => TAudioListener

Puts the game's ears on this object: every sound placed in the world is heard from where it is, and in a 3D scene, facing the way it faces.

Without it the game is heard from the camera, which is right until the camera is not where the player is. A game seen from behind its character wants the ears on the character: a bird to the character's left is then heard on the left, wherever the camera has swung round to.

One per object. With several switched on the first one is used, and that is said once; switch one off with enabled to hand over to the next, and in the end back to the camera.

Parámetros

options{ enabled }

Whether it starts on. Default on.

Ejemplo

const Player = () => {
    useTransform({ x: 0, y: 0.5, z: 0 });
    createMesh({ geometry: useCubeGeometry() });
    useAudioListener();
};
Ver el código · hooks/audio/use_audio_listener.ts:33

useMusicfunctionhooknacatamalon

useMusic(options: TMusicOptions) => TMusicHandle

Plays a piece of music made of layers, and hands back the controls for it.

The layers are the same tune played by different instruments, one file each and all the same length. They always play together and in time; what the game changes is how loud each one is. That is how music follows the place without ever starting over: walk into the water and the tune goes muffled, start a fight and the drums come in, and the melody never loses its place.

It belongs to the channel 'music' unless it says otherwise, so an options screen moves it with the rest. Like every sound, it stops with the scene or the object that asked for it.

Parámetros

optionsTMusicOptions

The layers by name, each with the volume it starts at, and the piece's volume, channel and whether it starts on its own.

Ejemplo

declare const player: TSprite;

const Level = () => {
    const music = useMusic({
        layers: {
            land: { src: '/audio/theme_land.ogg' },
            water: { src: '/audio/theme_water.ogg', volume: 0 },
        },
        autoplay: true,
    });

    useUpdate(() => {
        const under = player.transform.y < 0;
        music.setLayer('land', under ? 0 : 1, 0.5);
        music.setLayer('water', under ? 1 : 0, 0.5);
    });
    return createScene();
};
Ver el código · hooks/audio/use_music.ts:72

useSoundfunctionhooknacatamalon

useSound(source: TSoundSource, options: TSoundOptions) => TSoundHandle

Plays a sound, and hands back the controls for it.

Called in the body of a scene, like every hook; the controls are used whenever, from an update, a click, a signal. When the scene stops or the object that asked for it is destroyed, its sound stops: a level's music does not survive the level.

A one-off (the default) can sound on top of itself, which is what effects need: two coins picked up at once are heard twice. A looping sound is a single thing that pause, resume and stop act on: music, rain, an engine.

With spatial it is heard from where the object that asked for it is, and follows it; with zone it fills an area around the object instead, the way birds fill a meadow. Starting and stopping can fade, and so can the volume.

Pausing the game or the scene does not stop a sound, because a menu over a frozen level often wants the music to carry on. To silence something on pause, listen to scenePaused/gamePaused and decide for each sound.

Parámetros

sourceTSoundSource

A clip from useLoadAudio, or { src } to load it here.

optionsTSoundOptions

Volume, looping, speed, channel, and placing it in the world: at a point, facing a way, or filling an area.

Ejemplo

export const Level: TSceneFn = () => {
    const music = useSound({ src: '/audio/theme.mp3' }, { channel: 'music', loop: true, autoplay: true });
    const jump = useSound({ src: '/audio/jump.mp3' }, { volume: 0.6 });
    const keys = useKeyboard();

    useUpdate(() => {
        if (keys.justPressed('Space')) jump.play();
    });

    useSignal(scenePaused, () => music.setVolume(0.2));
    return createScene();
};
Ver el código · hooks/audio/use_sound.ts:77

TAudioHandletypenacatamalon

The volumes of a game, and the way to silence it. Returned by useAudio.

A channel is a group of sounds that share a volume: 'sfx' and 'music' are there from the start, and any other name works the moment a sound uses it. This is what an options screen with a slider per kind of sound is made of, and what a game saves in its store.

Propiedades

setVolume
getVolume
stopAll
Ver el código · audio/types/t_audio.ts:94

TAudioListenertypenacatamalon

Where the game is heard from, put on an object: its ears.

Without one the ears are in the camera, which is right for most games. A game seen from behind its character wants them on the character instead, or a bird on the left of the character is heard on whichever side of the camera it happens to be.

Propiedades

type'audio-listener'
idstring
enabledboolean

Off, the ears go back to the next in line, and in the end to the camera.

Ver el código · audio/types/t_audio_listener.ts:12

TMusicAttachmenttypenacatamalon

A piece of music in layers attached to one object: which files, and how loud each is meant to be. What it keeps is the intention, never how far into the tune it had got.

Propiedades

type'music'
idstring
layersTMusicLayer[]
volumenumber
channelstring
autoplayboolean
Ver el código · audio/types/t_music.ts:71

TMusicLayerOptionstypenacatamalon

TMusicLayerOptions: { src, key } | { clip } & { volume }

One layer of a piece of music: a file, or a clip already loaded, and how loud it starts.

Ver el código · audio/types/t_music.ts:11

TMusicOptionstypenacatamalon

How a piece of music in layers plays.

Propiedades

idopcionalstring

The same name the saved scene keeps. Made up when nobody says.

layersRecord<string, TMusicLayerOptions>

The layers, by name: the same tune played by different instruments, each in its own file and all the same length. They always play together and in time, and what changes is how loud each one is.

volumeopcionalnumber

The volume of the whole piece. Default 1.

channelopcionalstring

Default 'music'.

autoplayopcionalboolean

Starts as soon as every layer is ready, with no play(). Default false.

Ver el código · audio/types/t_music.ts:25

TSoundAttachmenttypenacatamalon

One sound attached to one object: which clip, and how it was asked to play.

What it holds is the intention, never what is sounding. A scene saved while the music was halfway through comes back ready to start, not halfway through: where a voice had got to is a fact about this run, and a level is not.

It carries the clip itself rather than its name, the way a sprite carries its texture, so that whoever writes the scene down can name the file and ask for it to be fetched again in one step.

Propiedades

type'sound'
idstring
clipTAudioClip
volumenumber
loopboolean
ratenumber
channelstring
autoplayboolean
spatialboolean
refDistancenumber | null

null until somebody chooses one: then it is what the scene measures in.

maxDistancenumber | null
coneTSoundCone | null
zoneTSoundZone | null
Ver el código · audio/types/t_sound.ts:169

TSoundConetypenacatamalon

Where a sound is heard loudest: a speaker, a siren, a radio on a shelf. Straight ahead of its object it plays at full volume, and further round it drops towards outerVolume.

Ahead is the way the object faces: its -Z in a 3D scene, the same way a camera and a lamp face, and along its turn in a flat one (to the right when it is not turned).

Propiedades

innernumber

How wide the loud part is, in degrees, from edge to edge.

outernumber

Past this width, in degrees, it is at its quietest. Between the two it fades.

outerVolumenumber

How loud it is behind, from 0 (silent) to 1 (the same as ahead).

Ver el código · audio/types/t_sound.ts:25

TSoundHandletypenacatamalon

Controls a sound made with useSound.

Propiedades

play
stop
pause
resume
setVolume
setLoop
setRate
playingboolean

Whether something of this sound is sounding right now.

Ver el código · audio/types/t_sound.ts:195

TSoundOptionstypenacatamalon

How a sound plays.

Propiedades

idopcionalstring

The name this sound keeps in a saved scene, so that opening one and saving it again gives the same file back. Made up when nobody says, which is right for a sound written in code and wrong for one that came out of a document.

volumeopcionalnumber

0 silent, 1 as recorded. Default 1. This sound only: the channel and the general volume still apply.

loopopcionalboolean

Repeats until it is stopped. Default false.

It also decides what the sound is: a one-off can be played on top of itself (two coins at once are heard twice), while a looping one is a single sound that pause, resume and stop act on: music, rain, an engine.

rateopcionalnumber

How fast it plays, which also changes the pitch: 2 is twice as fast, an octave up. Default 1.

channelopcionalstring

Which volume group it belongs to: 'sfx' (the default) or 'music' are there from the start, and any other name works straight away. An options screen moves these with useAudio.

autoplayopcionalboolean

Starts as soon as the file is ready, with no play(). Default false.

spatialopcionalboolean

Places the sound in the world, where the object that asked for it is: it comes from a side and gets quieter with distance. It follows the object wherever it goes, including when what carries it is what moves.

Heard from the camera, or from whatever useAudioListener put the ears on. In a 3D scene it can also be told apart in front and behind, best with headphones. Default false, which is the same volume wherever the listener is.

refDistanceopcionalnumber

How far it can be heard at full volume. Placed sounds only. Measured the way the scene measures: 100 pixels in a flat scene and under an orthographic camera, 1 unit under a perspective one.

maxDistanceopcionalnumber

Past this distance it is not heard at all: between refDistance and this it fades in a straight line. Placed sounds only. 2000 pixels, or 20 units under a perspective camera.

coneopcionalTSoundCone

Louder ahead of the object than behind it. Placed sounds only.

zoneopcionalTSoundZone

Fills an area instead of coming from a point: full volume inside, fading outside, and never from one side, because an ambience is all around. Wins over spatial.

Ver el código · audio/types/t_sound.ts:77

TSoundZonetypenacatamalon

An area a sound fills, the way a meadow is full of birds or a cave of dripping: inside, it plays at full volume wherever you stand, and outside it fades as you walk away.

Propiedades

shapeTSoundZoneShape

Measured on the object, so it moves, turns and grows with it.

fadenumber

How far outside the shape it takes to fade to silence. 0 stops dead at the edge.

Ver el código · audio/types/t_sound.ts:59