Skip to main content

SoundPool

This was deprecated in v1.0.0
No longer maintained; kept for existing projects. There is no direct replacement.
Deprecated

SoundPool is no longer maintained and is kept only for existing projects. There is no direct replacement in this library.

A pool of reusable, invisible anchored Parts each holding one Sound, for playing many short 3D sound effects (fighting-game SFX, hit sounds) without creating and destroying instances every time. PlaySound borrows a part from the pool, points its Sound at the asset and plays it, handing you a SoundPlayback to control it; the part goes back to the pool when the sound ends or when you call Return.

The pooled parts live in a Folder created in workspace and named after the pool. Pooling is done by frqstbite's object-pool package (ObjectPool.new(generator, minimum, maximum)), so minimum parts are created up front and the pool never grows past maximum. 

local SoundPool = require(path.to.SoundPool)

local hitSounds = SoundPool.new("HitSounds", 4, 32)

local function playHit(position: Vector3)
	local playback = hitSounds:PlaySound(9118823101, { Volume = 0.8, Position = position })
	-- In this version the config passed to PlaySound is not applied; set it explicitly:
	playback:UpdateConfig({ Volume = 0.8, Position = position })
	return playback
end

Depends on Sleitnick's Trove and Signal and on frqstbite's object-pool, all installed by Wally.

Credits: Trove and Signal are by sleitnick (sleitnick's RbxUtil); the pooling is object-pool by frqstbite. Wally installs all three.

Installation and guide: SoundPool package page.

Types​

PooledSound​

</>
type PooledSound = Part & {Sound: Sound}

An invisible, anchored, non-collidable Part with a child Sound named "Sound". The Part is positioned for 3D playback; the Sound plays the asset.

SoundConfig​

</>
interface SoundConfig {
Volume: number?--

Sound.Volume.

SoundGroup: SoundGroup?--

Sound.SoundGroup to route the sound through.

PlaybackSpeed: number?--

Sound.PlaybackSpeed (1 is normal speed).

TimePosition: number?--

Sound.TimePosition in seconds to start from.

Looped: boolean?--

Sound.Looped; false is applied too, only nil is skipped.

Position: Vector3?--

World position of the pooled Part, which makes the sound 3D.

RollOffMinDistance: number?--

Sound.RollOffMinDistance.

RollOffMaxDistance: number?--

Sound.RollOffMaxDistance.

RollOffMode: Enum.RollOffMode?--

Sound.RollOffMode.

}

Optional property overrides for a playing sound, applied by SoundPlayback:UpdateConfig. Every field is optional and only the fields you set are written; the rest keep whatever value the pooled Sound already has from its previous use, so set everything you care about each time. Note that SoundPool:PlaySound accepts a config but this version does not apply it; call UpdateConfig on the returned playback.

Properties​

PooledSoundsFolder​

This item is read only and cannot be modified. Read Only
</>
SoundPool.PooledSoundsFolder: Folder

The Folder in workspace (named after the pool's displayName) that holds every pooled Part.

ObjectPool​

This item is read only and cannot be modified. Read Only
</>
SoundPool.ObjectPool: ObjectPool<PooledSound>

The underlying frqstbite object-pool that hands out and takes back pooled Parts.

Functions​

new​

</>
SoundPool.new(
displayName: string,--

Name of the workspace Folder that holds the pooled Parts.

minimum: number,--

How many pooled sounds to create up front.

maximum: number--

The most pooled sounds the pool may hold.

) → SoundPool--

The new pool.

Creates a SoundPool. A Folder named displayName is created in workspace to hold the pooled Parts, and an object-pool is set up that generates Parts with _GenerateSound, creating minimum of them right away and never holding more than maximum.

PlaySound​

</>
SoundPool:PlaySound(
id: number | string,--

An asset id number, or a full sound id string.

soundConfig: SoundConfig?--

Intended initial properties; not applied in this version (see above).

) → SoundPlayback--

Handle to the playing sound.

Borrows a pooled sound, sets its SoundId and starts playing it, returning a SoundPlayback handle. A number id is formatted as rbxassetid://<id>; a string is used as-is (so any rbxassetid:// string works). The pooled Part is returned to the pool automatically when the sound ends, or when you call Return on the handle.

CAUTION

In this version soundConfig is accepted but never applied. Call UpdateConfig on the returned playback to set volume, position and the other properties. Pooled Sounds keep the properties from their previous use, so always set the ones you rely on.

Errors

TypeDescription
"Sound id given is not a valid string or number"`id` is neither a number nor a string.
"PooledSound is missing Sound instance."The borrowed Part lost its child Sound (e.g. it was destroyed externally).
Show raw api
{
    "functions": [
        {
            "name": "new",
            "desc": "Creates a SoundPool. A Folder named `displayName` is created in `workspace` to hold the pooled\nParts, and an object-pool is set up that generates Parts with `_GenerateSound`, creating\n`minimum` of them right away and never holding more than `maximum`.",
            "params": [
                {
                    "name": "displayName",
                    "desc": "Name of the workspace Folder that holds the pooled Parts.",
                    "lua_type": "string"
                },
                {
                    "name": "minimum",
                    "desc": "How many pooled sounds to create up front.",
                    "lua_type": "number"
                },
                {
                    "name": "maximum",
                    "desc": "The most pooled sounds the pool may hold.",
                    "lua_type": "number"
                }
            ],
            "returns": [
                {
                    "desc": "The new pool.",
                    "lua_type": "SoundPool"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 393,
                "path": "packages/src/SoundPool/init.luau"
            }
        },
        {
            "name": "_GenerateSound",
            "desc": "Generator used by the object-pool: builds one pooled sound, a 1x1x1 invisible anchored Part\n(`CanCollide`, `CanQuery` and `CanTouch` off) at the origin named \"PooledSound\" inside\n`PooledSoundsFolder`, with a child `Sound` named \"Sound\" at volume 1 and an empty `SoundId`.",
            "params": [],
            "returns": [
                {
                    "desc": "The new pooled Part.",
                    "lua_type": "PooledSound"
                }
            ],
            "function_type": "method",
            "private": true,
            "source": {
                "line": 419,
                "path": "packages/src/SoundPool/init.luau"
            }
        },
        {
            "name": "PlaySound",
            "desc": "Borrows a pooled sound, sets its `SoundId` and starts playing it, returning a\n[SoundPlayback](/api/SoundPlayback) handle. A number `id` is formatted as\n`rbxassetid://<id>`; a string is used as-is (so any `rbxassetid://` string works). The\npooled Part is returned to the pool automatically when the sound ends, or when you call\n`Return` on the handle.\n\n:::caution\nIn this version `soundConfig` is accepted but never applied. Call `UpdateConfig` on the returned\nplayback to set volume, position and the other properties. Pooled Sounds keep the properties\nfrom their previous use, so always set the ones you rely on.\n:::",
            "params": [
                {
                    "name": "id",
                    "desc": "An asset id number, or a full sound id string.",
                    "lua_type": "number | string"
                },
                {
                    "name": "soundConfig",
                    "desc": "Intended initial properties; not applied in this version (see above).",
                    "lua_type": "SoundConfig?"
                }
            ],
            "returns": [
                {
                    "desc": "Handle to the playing sound.",
                    "lua_type": "SoundPlayback"
                }
            ],
            "function_type": "method",
            "errors": [
                {
                    "lua_type": "\"Sound id given is not a valid string or number\"",
                    "desc": "`id` is neither a number nor a string."
                },
                {
                    "lua_type": "\"PooledSound is missing Sound instance.\"",
                    "desc": "The borrowed Part lost its child Sound (e.g. it was destroyed externally)."
                }
            ],
            "source": {
                "line": 461,
                "path": "packages/src/SoundPool/init.luau"
            }
        }
    ],
    "properties": [
        {
            "name": "PooledSoundsFolder",
            "desc": "The Folder in `workspace` (named after the pool's `displayName`) that holds every pooled Part.",
            "lua_type": "Folder",
            "readonly": true,
            "source": {
                "line": 96,
                "path": "packages/src/SoundPool/init.luau"
            }
        },
        {
            "name": "ObjectPool",
            "desc": "The underlying frqstbite object-pool that hands out and takes back pooled Parts.",
            "lua_type": "ObjectPool<PooledSound>",
            "readonly": true,
            "source": {
                "line": 102,
                "path": "packages/src/SoundPool/init.luau"
            }
        }
    ],
    "types": [
        {
            "name": "PooledSound",
            "desc": "An invisible, anchored, non-collidable Part with a child `Sound` named \"Sound\". The Part is positioned for 3D playback; the Sound plays the asset.",
            "lua_type": "Part & { Sound: Sound }",
            "source": {
                "line": 88,
                "path": "packages/src/SoundPool/init.luau"
            }
        },
        {
            "name": "SoundConfig",
            "desc": "Optional property overrides for a playing sound, applied by `SoundPlayback:UpdateConfig`. Every\nfield is optional and only the fields you set are written; the rest keep whatever value the\npooled Sound already has from its previous use, so set everything you care about each time.\nNote that `SoundPool:PlaySound` accepts a config but this version does not apply it; call\n`UpdateConfig` on the returned playback.",
            "fields": [
                {
                    "name": "Volume",
                    "lua_type": "number?",
                    "desc": "`Sound.Volume`."
                },
                {
                    "name": "SoundGroup",
                    "lua_type": "SoundGroup?",
                    "desc": "`Sound.SoundGroup` to route the sound through."
                },
                {
                    "name": "PlaybackSpeed",
                    "lua_type": "number?",
                    "desc": "`Sound.PlaybackSpeed` (1 is normal speed)."
                },
                {
                    "name": "TimePosition",
                    "lua_type": "number?",
                    "desc": "`Sound.TimePosition` in seconds to start from."
                },
                {
                    "name": "Looped",
                    "lua_type": "boolean?",
                    "desc": "`Sound.Looped`; `false` is applied too, only `nil` is skipped."
                },
                {
                    "name": "Position",
                    "lua_type": "Vector3?",
                    "desc": "World position of the pooled Part, which makes the sound 3D."
                },
                {
                    "name": "RollOffMinDistance",
                    "lua_type": "number?",
                    "desc": "`Sound.RollOffMinDistance`."
                },
                {
                    "name": "RollOffMaxDistance",
                    "lua_type": "number?",
                    "desc": "`Sound.RollOffMaxDistance`."
                },
                {
                    "name": "RollOffMode",
                    "lua_type": "Enum.RollOffMode?",
                    "desc": "`Sound.RollOffMode`."
                }
            ],
            "source": {
                "line": 199,
                "path": "packages/src/SoundPool/init.luau"
            }
        }
    ],
    "name": "SoundPool",
    "desc": ":::caution Deprecated\nSoundPool is no longer maintained and is kept only for existing projects. There is no direct\nreplacement in this library.\n:::\n\nA pool of reusable, invisible anchored Parts each holding one `Sound`, for playing many short\n3D sound effects (fighting-game SFX, hit sounds) without creating and destroying instances every\ntime. `PlaySound` borrows a part from the pool, points its `Sound` at the asset and plays it,\nhanding you a [SoundPlayback](/api/SoundPlayback) to control it; the part goes back to the pool\nwhen the sound ends or when you call `Return`.\n\nThe pooled parts live in a Folder created in `workspace` and named after the pool. Pooling is\ndone by frqstbite's `object-pool` package (`ObjectPool.new(generator, minimum, maximum)`), so\n`minimum` parts are created up front and the pool never grows past `maximum`.\n\n```lua\nlocal SoundPool = require(path.to.SoundPool)\n\nlocal hitSounds = SoundPool.new(\"HitSounds\", 4, 32)\n\nlocal function playHit(position: Vector3)\n\tlocal playback = hitSounds:PlaySound(9118823101, { Volume = 0.8, Position = position })\n\t-- In this version the config passed to PlaySound is not applied; set it explicitly:\n\tplayback:UpdateConfig({ Volume = 0.8, Position = position })\n\treturn playback\nend\n```\n\nDepends on Sleitnick's [Trove](https://sleitnick.github.io/RbxUtil/api/Trove/) and\n[Signal](https://sleitnick.github.io/RbxUtil/api/Signal/) and on frqstbite's\n[object-pool](https://wally.run/package/frqstbite/object-pool), all installed by Wally.\n\n**Credits:** [Trove](https://sleitnick.github.io/RbxUtil/api/Trove/) and [Signal](https://sleitnick.github.io/RbxUtil/api/Signal/) are by [sleitnick](https://github.com/Sleitnick) ([sleitnick's RbxUtil](https://sleitnick.github.io/RbxUtil/)); the pooling is [object-pool](https://wally.run/package/frqstbite/object-pool) by [frqstbite](https://github.com/frqstbite). Wally installs all three.\n\nInstallation and guide: [SoundPool package page](/docs/packages/sound-pool).",
    "deprecated": {
        "version": "v1.0.0",
        "desc": "No longer maintained; kept for existing projects. There is no direct replacement."
    },
    "source": {
        "line": 79,
        "path": "packages/src/SoundPool/init.luau"
    }
}