Sounds

Sounds are .sound files your mod names by path. The server plays a sound for the players its group picks: from a point, following a player or an entity, or alike everywhere. A client script plays one for its own player alone, at once and at no network cost, as a click or a banner needs.

A sound played once ends by itself. One that loops is an entity until you stop it, or until what it follows goes.

Every sound plays in one part of each player’s mix: world, weapons, music or interface. A client script turns a part down or muffles it with sound_mix, and each player sets their own volume of each part in Settings.

sound_mix

On a client sound_mix: SoundMix

How loud each category of sounds plays, and how muffled, on top of the player's own volumes.

play_sound

On the server play_sound(name, options?) → Entity?

On a client play_sound(name, options?) → PlayingSound

Plays a sound for the players who hear it, once, or again and again with loop until stop_sound.

On the server

A sound at a point, or following a player or an entity, is heard by the players within its range; one with neither by everyone, alike in both ears. Each sound costs network for every player who hears it, so on a busy server far sounds wait for near ones. A player hears a sound where they stand, or while dead where the player they watch stands. A player who joins while a loop plays hears it from where it is. A sound played once ends by itself; with loop, play_sound gives the sound’s entity, which kind names, so kind without loop fails. One played once that follows something absent is not heard; a loop is silent while what it follows is absent. A player’s game plays 16 sounds longer than 30 s at once, and not one past them.

Name	Type	What it is
`name`	`sound`	Needed.
`options`	`table?`	A table of the options below. It, and each option, may be left out.
`at`	`vector?`	The point it is heard from; alike everywhere, by everyone, without `at` or `follow`. Not with `follow`.
`follow`	`(Player \| Entity \| number)?`	A player or an entity it moves with; a loop stops once the entity is removed or the player leaves. Not with `at`.
`loop`	`boolean`default false	Plays again and again until `stop_sound`, and `play_sound` gives the sound's entity.
`volume`	`number`0 to 1, default 1	How loud, 1 as the file was made.
`speed`	`number`0.25 to 4, default 1	How fast it plays, its pitch rising with it.
`range`	`number`1 to 1000, or math.huge, default 40	How far from `at` or `follow` it is heard, in metres; at any distance, from its direction, with `math.huge`.
`category`	`"weapons" \| "world" \| "music" \| "interface"`default "world"	The part of each player's mix it plays in, which a client script turns down and muffles (`sound_mix`).
`start`	`number`-3600 to 5, default 0	When it starts, in seconds from now: up to an hour ago, heard from part-way through, or up to 5 s ahead.
`owner`	`(Player \| number)?`	The player it is about, whom `owner`, `team` and `spectators` pick by.
`read_by`	`(Group \| ((Player?, Player) -> boolean))?`	Who is shown it; everyone without.
`kind`	`string?`	Its kind, one `entity_kind` declared on its base; the base's own without.

Returns

Entity?

Fails

a value of the wrong type
an option it does not have
a value outside its range
at and follow both

On a client

Plays a sound for this player alone, as hover and click sounds, banners and a ringing ear need; gives its handle, whose stop(transition) fades it out.

No other player hears it, and it costs no network. It starts as the frame ends, 16 a frame at most, and 64 plays and stops wait at most. A sound whose file still loads is not heard. The scripts’ sounds play 32 at once, a new one stopping the oldest, and 16 longer than 30 s, past which one is not heard. A name the server never named fails.

Name	Type	What it is
`name`	`sound`	Needed.
`options`	`table?`	A table of the options below. It, and each option, may be left out.
`volume`	`number`0 to 1, default 1	How loud, 1 as the file was made.
`speed`	`number`0.25 to 4, default 1	How fast it plays, its pitch rising with it.
`loop`	`boolean`default false	Plays again and again, until its handle's `stop`.
`at`	`vector?`	The point in the world it is heard from; alike in both ears without.
`range`	`number`1 to 1000, or math.huge, default 40	How far from `at` it is heard, in metres; at any distance, from its direction, with `math.huge`.
`category`	`"weapons" \| "world" \| "music" \| "interface"`default "interface"	The part of the mix it plays in, which `sound_mix` turns down and muffles.

Returns

PlayingSound

Fails

a value of the wrong type
an option it does not have
a value outside its range

To play a shot where it was fired

play_sound("awp_fire", { at = p.position, range = 200, category = "weapons" })

To blast every player’s ears, wherever they are

play_sound("explosion_boom", { volume = 0.8 })

To groan from a zombie as it walks, and stop the groan

local zombie = spawn()
local groan = play_sound("zombie_groan1", { follow = zombie, loop = true, range = 25 })
stop_sound(groan)

To reload in this player’s ears alone

play_sound("ak47_reload", { volume = 0.5, category = "weapons" })

To ring in the ear after a blast, then fade it out

local ring = play_sound("tinnitus", { loop = true, volume = 0.6 })
ring:stop({ seconds = 3 })

To hear a blast where it went off, for this player alone

play_sound("explosion_boom", { at = vector.create(4, 1, -2), range = 100, category = "world" })

stop_sound

On the server stop_sound(sound)

Stops a looping sound play_sound gave; one stopped already, or gone with what it followed, is left as it is.

Name	Type	What it is
`sound`	`Entity`	Needed.

Fails

a value of the wrong type

To hold a grenade’s hiss until it is thrown

local hiss = play_sound("grenade_hold", { follow = p, loop = true, range = 10 })
stop_sound(hiss)

PlayingSound:stop

On a client PlayingSound:stop(transition?)

Fades the sound out, or stops it at once without a transition; one stopped already is left as it is.

Name	Type	What it is
`transition`	`Transition?`	May be left out.

Fails

a value of the wrong type

To ring in the ear after a blast, then fade it out

local ring = play_sound("tinnitus", { loop = true, volume = 0.6 })
ring:stop({ seconds = 3 })

SoundMix:set

On a client SoundMix:set(categories, transition?)

Turns down and muffles each category it names, eased over transition, at once without; sound_mix.world and the rest read back what was last set.

It changes this player’s mix alone, the sounds the server plays among it. Each category reads {volume = 1, muffle = 0} until set, and a new match sets them so again. A muffle is a low-pass from 20 kHz, clear, down to 200 Hz at 1.

Name	Type	What it is
`categories`	`table`	A table of the options below. Each may be left out.
`weapons`	`Mix?`	Shots, reloads and the rest of the weapons' sounds. A table of the options below it.
`weapons.volume`	`number?`0 to 1	How loud, 0 silent and 1 as made.
`weapons.muffle`	`number?`0 to 1	How muffled, 0 clear and 1 as through a wall.
`world`	`Mix?`	The world's own sounds: steps, doors, blasts and voices. A table of the options below it.
`world.volume`	`number?`0 to 1	How loud, 0 silent and 1 as made.
`world.muffle`	`number?`0 to 1	How muffled, 0 clear and 1 as through a wall.
`music`	`Mix?`	The music the mod plays. A table of the options below it.
`music.volume`	`number?`0 to 1	How loud, 0 silent and 1 as made.
`music.muffle`	`number?`0 to 1	How muffled, 0 clear and 1 as through a wall.
`interface`	`Mix?`	Menus' and the HUD's clicks and banners. A table of the options below it.
`interface.volume`	`number?`0 to 1	How loud, 0 silent and 1 as made.
`interface.muffle`	`number?`0 to 1	How muffled, 0 clear and 1 as through a wall.
`transition`	`Transition?`	May be left out.

Fails

a value of the wrong type
an option it does not have
a value outside its range

To muffle the world after a blast, then bring it back

sound_mix:set({ world = { volume = 0.3, muffle = 0.85 }, weapons = { muffle = 1 } }, { seconds = 0.3 })
sound_mix:set({ world = { volume = 1, muffle = 0 }, weapons = { muffle = 0 } }, { seconds = 4, timing = "ease-in" })