HeroEngine Audio System

From HEWIKI
Jump to: navigation, search

Contents

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:

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 NameTypeDescription
sndAmbientTypeenum AmbientSoundTypesSets the shape of the sound. OMNI a spherical sound, DIRECTIONAL a cone shaped sound.
sndAttachBonestringName of a bone (if any) to attach to when attaching to a character
sndAttachToidIf an id of an instance or character is specified, the sound will be attached to this instance on creation.
sndCutoffDistancefloatDetermines 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.
sndDelaytimeintervalIf a time inteval is specified here, the playing of the sound will be delayed by this interval
sndDelayTimertimerUsed by system Handles delayed playing of the sound
sndFadeInLengthfloatSets 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
sndFadeOutLengthfloatSets the time it takes to fade out the sounf from current volume to inaudible when the listener leaves the audible area of the sound.
sndInnerAnglefloatSets the size of the inner cone on a DIRECTIONAL sound, specified in degrees 0-360.
sndIs3DbooleanWhen 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.
sndLoadertimerUsed by system when the sound to be played has not yet been loaded to the client
sndMaxDistancefloatDistance from center of sound representing the farthest away you can be from the sound and still hear it
sndMinDistancefloatDistance from the center of the sound that defines the sphere within which the sound is heard at full volume
sndOuterAnglefloatSets the size of the outer cone on a DIRECTIONAL sound, specified in degrees 9-360
sndPositionvector3Sets the position of the sound in 3d space
sndResourcestringThe path and file name (FQN) of the sound file to be played
sndRotationvector3Sets the rotation of the sound in 3d space. Only significant for DIRECTIONAL sounds
sndSoundSizeenum soundSizesSets 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.
sndSpecIDidUsed by system to store the spec id of the sound to be played
sndStartOffsetfloatOffsets the starting point of the sound by the time in seconds specified
sndVolumefloatSets the volume of the sound. 1.0 = full volume 0.0 = inaudible
sndVolumeOutsideConesfloatIf 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.

pathThe full path to the sound resource
resourceThe file name of the sound resource
sizeThe sound size from enum soundSizes to be used
positionThe position at which to place the sound
actorID 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)
.
Personal tools
Namespaces
Variants
Actions
Navigation
Toolbox