HeroEngine Audio System
|
- For other audio-related pages, see Sound.
The Sound System is a collection of useful client-side methods and functions for playing sounds via HSL scripts. These functions are accessible via the $SOUND prototype and reside in the SoundClassMethods script.
SoundClassMethods script
To see the entire script:
- In HeroBlade, open the Script Editor with CTRL-H
- In the Script Editor, File > Open > Client Script (or CTRL-SHIFT-C)
- Check the "Show Engine" checkbox at the bottom of the Script Picker panel
- Type "sound" into the filter box at the bottom of the Script Picker panel
- Double-click on SoundClassMethods to open it (be sure that you are looking at the client scripts, not server)
- CTRL-SHIFT-F to open a list of the script's Functions and Methods
A more detailed description of the various methods in the script is as follows:
$SOUND Methods that play sounds
Play
method Play(snd as String) as NodeRef
The Play method uses the PlaySound function to play the specified sound at full volume with no fade in.
Play3D
method Play3D(snd references Class Sound3D) as NodeRef of Class HBNode
Plays the sound specified in the Sound3D class. If the resource has not yet been loaded (downloaded to the client) it will wait up to 10 seconds for it to load. If it loads before the 10 second time limit, it will play, otherwise it does not attempt to play it.
The Sound3D Class
This class is used to define everything about a 3D sound, including size, shape and positioning.
| Field Name | Type | Description |
| sndAmbientType | enum AmbientSoundTypes | Sets the shape of the sound. OMNI a spherical sound, DIRECTIONAL a cone shaped sound. |
| sndAttachBone | string | Name of a bone (if any) to attach to when attaching to a character |
| sndAttachTo | id | If an id of an instance or character is specified, the sound will be attached to this instance on creation. |
| sndCutoffDistance | float | Determines the threshold distance from the center of the sound where this sound will be cutoff (silenced). The listener's distance from the sound must be less than the cutoff distance to hear the sound. |
| sndDelay | timeinterval | If a time inteval is specified here, the playing of the sound will be delayed by this interval |
| sndDelayTimer | timer | Used by system Handles delayed playing of the sound |
| sndFadeInLength | float | Sets the time it takes to fade in the sound from inaudible to its correct volume when the listener enters the audible area of the sound |
| sndFadeOutLength | float | Sets the time it takes to fade out the sounf from current volume to inaudible when the listener leaves the audible area of the sound. |
| sndInnerAngle | float | Sets the size of the inner cone on a DIRECTIONAL sound, specified in degrees 0-360. |
| sndIs3D | boolean | When True, the sound is played on a 3D channel and all 3D settings apply. When False, the sound is played on a stereo channel, ignore all 3D settings except position. The volume of a sound played on the stereo channel is still determined by the listeners distance from the position of the sound. |
| sndLoader | timer | Used by system when the sound to be played has not yet been loaded to the client |
| sndMaxDistance | float | Distance from center of sound representing the farthest away you can be from the sound and still hear it |
| sndMinDistance | float | Distance from the center of the sound that defines the sphere within which the sound is heard at full volume |
| sndOuterAngle | float | Sets the size of the outer cone on a DIRECTIONAL sound, specified in degrees 9-360 |
| sndPosition | vector3 | Sets the position of the sound in 3d space |
| sndResource | string | The path and file name (FQN) of the sound file to be played |
| sndRotation | vector3 | Sets the rotation of the sound in 3d space. Only significant for DIRECTIONAL sounds |
| sndSoundSize | enum soundSizes | Sets the sound to a pre-defined shape and size. Options are TINY, SMALL, MEDIUM, LARGE, EXTRALARGE, MASSIVE and CUSTOM. If set to CUSTOM, then sndAmbientType, sndMinDistance, sndMaxDistance and sndCutoffDistance are used to determine the size and shape of sound. |
| sndSpecID | id | Used by system to store the spec id of the sound to be played |
| sndStartOffset | float | Offsets the starting point of the sound by the time in seconds specified |
| sndVolume | float | Sets the volume of the sound. 1.0 = full volume 0.0 = inaudible |
| sndVolumeOutsideCones | float | If DIRECTIONAL, this is the max volume of the sound when outside of the center cone |
Using the Sound3D Class
Although the Sound3D class looks complex, it is simple to use.
Example
var s = $Sound.GetNewSound3D() s.sndResource = "world\livecontent\audio\boom.sgt" s.sndPosition = "(0,0,0)" $Sound.Play3D(s)
In this example, the boom sound will be played at position (0,0,0). The first line creates a Sound3D class variable with default options already set. Next line we specify what file to play and the next sets where to position the sound in 3d space. The final line plays the sound.
More Useful $SOUND Methods
Method GetNewSound3D
method GetNewSound3D() as Class Sound3D
This methods returns a Sound3D class variable with the most commonly used settings. It is usually best to use this method to create your Sound3D class variable, then tweak settings to your needs.
Method GetSoundLocForCharacter()
method GetSoundLocForCharacter(actor as NodeRef of Class HBNode) as Vector3
This method returns a vector3 which will be the position of a character's head. Specifically, it looks for a bone in the character named "Bip01 Head" and returns that position if it exists, otherwise it sends the base position of the character.
Note: You're implementation of character's may not include this bone name.
Method GetFootLocForCharacter()
method GetFootLocForCharacter(actor as NodeRef of Class HBNode) as Vector3
This method returns a vector3 which is the position of a character where it stands on the ground. Particularly useful for placing footstep sounds.
Remote Function ServerSaysPlay()
remote function ServerSaysPlay(rci as Class RemoteCallServerIn)
This function is called via a RemoteCallClient from the server allowing a server script to be able to call the client and play a sound. It expects the following arguments to be passed in args.
| path | The full path to the sound resource |
| resource | The file name of the sound resource |
| size | The sound size from enum soundSizes to be used |
| position | The position at which to place the sound |
| actor | ID of an instance or character. If given, the sound will be placed at the location of this instance instead of the location passed in position. |
Example of a Server-Side script used to play a sound
function PlayASoundOnPlayersClient(playerID as ID, sndPath as string, sndFileName as string) rco as class RemoteCallClientOut rco.toPlayer = playerID rco.toScript = "SoundClassMethods" rco.toFunction = "ServerSaysPlay" rco.args["path"] = sndPath rco.args["resource"] = sndFileName rco.args["size"] = "MEDIUM" rco.args["position"] = SomeOtherScript:GetLocationOfPlayer(playerID) // returns a vector3 // Tell client to play the sound RemoteCallClient(rco) .
