You can place positional sound sources in Polycode entities that are attenuated based on the listener's position and orientation.

Contents

Positional sound overview.

To create sounds in 3D (or 2D!) space, you can place positional sounds inside of Polycode's entities using the SceneSound class. The SceneSound class is a wrapper for the regular Sound class, but subclasses the Entity class and can be placed inside of other entities. The sound is attenuated based on the distance to the instance of the SceneSoundListener class, of which there can only be one active at a time. The distance attenuation is based on two parameters set in each SceneSound class, Reference Distance, which defines the distance at which the sound's volume is at 50% and Maximum distance, which defines the distance at which the sound is no longer heard.

Placing positional sounds in the IDE.

To add a positional sound in the IDE entity editor, click on the add entity button in the top left corner of the editor screen and select "Sound". After creating the sound, you can choose the sound file to play from this location as well as edit its settings in the entity properties to the right.

If the Loop on load checkbox is enabled in the sound properties, this sound will play automatically on a loop when the entity s loaded. This is useful for ambient sound sources that are always playing.

If you need to manually trigger the sound playback, you will have to give this sound a tag or an id and play it manually from code by calling the Play method of the Sound class, which you can access by calling getSound on the SceneSound instance.

Placing positional sounds in code.

To place a positional sound in code, you need to create an instance of the SceneSound class and add it to your scene, passing it the reference and maximum distance values. You can use the setReferenceDistance and setMaxDistance of the Sound class contained within the SceneSound to adjust its distance attenuation properties after you create it as well.

C++
SceneSound *testSound = new SceneSound("demo.ogg", 5.0, 10.0);
testSound->getSound()->Play(true);
testSound->getSound()->setReferenceDistance(2.0);
testSound->getSound()->setMaxDistance(4.0);
scene->addChild(testSound);
Lua
testSound = SceneSound("demo.ogg", 5.0, 10.0)
testSound:getSound():Play(true)
testSound:getSound():setReferenceDistance(2.0)
testSound:getSound():setMaxDistance(4.0)
scene:addChild(testSound)

Setting the listener position.

To set the position and orientation that all active positional sounds attenuate in relation to, you need to create a SceneSoundListener class and add it to your scene. There can only be one SceneSoundListener active at any time and if you have multiple ones added to active scenes, Polycode will use whatever the last SceneSoundListener is updated in the loop.

SceneSoundListener is just like any other entity and can be positioned and rotated to set the sound engine's listening position. You may attach the SceneSoundListener to a game's player entity or manually set its transform depending on your needs.

C++
SceneSoundListener *soundListener = new SceneSoundListener();
scene->addEntity(soundListener);
Lua
soundListener = SceneSoundListener()
scene:addEntity(soundListener)