Torque 3D 1.1 Alpha SFX Changes
by Rene Damm · in Torque 3D Professional · 11/22/2009 (4:30 pm) · 16 replies
This is a brief write-up of the notable SFX changes for 1.1 Alpha and serves to bridge the gap between now and availability of updated SFX docs.
Since the information here is very technical, I intend to open another thread with some brief how-to information that leaves the technical aspect aside.
//Edit: formatting
//Addition
Since the information here is very technical, I intend to open another thread with some brief how-to information that leaves the technical aspect aside.
Core Changes
- SFXSource is now an abstract base class that serves as a high-level play controller
- SFXSound takes on the previous role of SFXSource
- Sound data is now abstracted as SFXTracks
- Most places that were using SFXProfiles have been converted to use SFXTracks and thus work with the new track types (e.g. ShapeBase audio)
- Unlike other datablocks in Torque, client-only SFX datablocks can (in most places) be referenced in server-side objects
- SFXProfile is now an SFXTrack
- SFXSources are now SimGroups and can be arranged in a hierarchy; a SFXSource will modulate volume, pitch, and priorities of children; hierarchies can be started/stopped/paused in entirety; entire hierarchies can be taken down by deleting the root source
- volume channels are now deprecated; they have been superseded by source hierarchies; internally, channel IDs are translated to SFXSource instances (includes master channel; volume prefs continue to be used as before)
- a complete new fade system has been implemented; it works directly on SFXSource and thus works with entire source hierarchies (I had replaced the direct fade parameters on play/pause/stop in 1.1 Alpha with just a boolean 'immediate?' toogle but intend to revert this; so you can do "AudioChannelMaster.stop( 4.0 );" to fade out and stop all audio in 4 seconds)
- fade-in and fade-out curves can be adjusted graphically in the Datablock Editor (fadeInEase, fadeOutEase)
- fades on looping sources can be restricted to fade-ins when the source starts (fadeLoops)
- SFXSources maintain a live connection to their SFXDescriptions; editing them in the Datablock Editor will automatically trigger updates on connected SFXSources except for those properties that have been assigned custom values on specific SFXSources
- SFXSources can now be prioritized to affect culling for voice virtualization
- with FMOD, voice virtualization is now left to FMOD
- new SFX metrics are: "sfxstates" and "sfxsources" (the latter is more a dump than a metrics display; it excludes group sources by default)
- T3D: listener tracking is now tied to ShapeBase
- T3D: the location of the ears on a given ShapeBase object can be specified by defining an 'ear' node; if not present, the 'eye' node will be used
Playlists
- A new SFXTrack datablock class SFXPlayList is available; as an SFXTrack, playlists can be used wherever SFXProfiles can be used
- playlists can be entirely set up from within the Datablock Editor
- a playlist has 16 slots; longer and more complex playlists can be created by cascading playlists (since they themselves are SFXTracks)
- a playlist cycles through all slots that have valid tracks set on them
- each slot goes through a sequence of stages: delay -> transition-in -> play -> delay -> transition-out
- each stage can be manually configured and randomized
- the stage sequence for a slot can be repeated by setting a loop count on the slot
- volume scale, pitch scale, and min and max distance can be set per-slot and randomized
- like any other SFXTrack, playlists use SFXDescriptions for configuration; a 3D playlist or a looping playlist can be set up by configuring the SFXDescription accordingly
- two slot order randomization patterns are available at the moment
- SFXStates can be tied to playlist slots for interactive audio
- a new SFXSource type SFXController implements playlist execution
Interactive Audio
- a new SFXParameter object type is available that represents a single dynamic SFXSource property
- an arbitrary number of SFXSources can be tied to a SFXParameter by configuring their SFXDescriptions and SFXTracks accordingly (or attaching the parameters manually)
- value changes of SFXParameter will automatically propagate to all connected SFXSources
- the keyable channels of SFXSources at the moment are: volume, pitch, priority, position X/Y/Z, rotation X/Y/Z, velocity X/Y/Z, min/max distance, cone inside/outside angle and volume, playback cursor, status (play, pause, stop), and 4 channels for custom semantics
- SFXParameters are updated periodically and updates may be redirected to script if desired
- SFXParameters can be created, adjusted, and monitored through the editor (Edit -> Audio Parameters...)
- SFXParameters are identified by their internalNames
- SFXParameters are exclusively client-side
- SFXParameter values are currently all global; per-source parameter values are planned for 1.2
- a new SFXState object type is available that represents on/off states
- SFXStates can be configured to include and/or exclude other states
- SFXStates can be manually activated (SFXState.activate()) or disabled (SFXState.disable())
- playlists will automatically skip slots that have an inactive state assigned
- playlists can be configured to automatically transition out of slots when their associated state is deactivated
- a number of generally useful states are implemented in core/scripts/client/audioStates.cs; these also serve as examples
- SimGroup AudioLocation contains: AudioLocationOutside, AudioLocationUnderwater, AudioLocationInside (most useful with ambient audio)
- SimGroup AudioMood contains: AudioMoodAggressive, AudioMoodTense, AudioMoodVictory, AudioMoodCalm
- the above states are configured to be exclusive (i.e. when activated, a state will automatically deactivate other states in its group)
FMOD Designer Integration
- FMOD Designer support is available when the requisite DLLs have been installed in game/ (fmodex.dll and fmod_event.dll or libfmodex.dylib and libfmodevent.dylib on Mac)
- a compiled Designer project (.fev) can be easily added through the editor (File -> Add FMOD Designer Audio...)
- the FMOD SFX datablocks can be either server-side or client-side; the editor's wizard will create client-side datablocks which is preferable as otherwise the entire Designer project gets purged and reloaded during every mission transition
- FMOD paths are mapped to TorqueScript object names: a Designer event 'MyGroup/MySubGroup/MyEvent' contained in an SFXFMODProject datablock called MyProject will be available as MyProject_MyGroup_MySubGroup_MyEvent
- data loading is automatic; however, for optimization, data can be explicitly loaded for individual groups (e.g. 'MyProject_MyGroup.loadData();'; this is reference-counted)
- the FMOD datablocks are automatically cached in a TorqueScript file alongside the .fev project and will be regenerated automatically when the .fev is modified
- the FMOD datablocks can be used on servers that don't have FMOD running and will correctly relay to clients
- SFXSource properties are automatically mapped to FMOD event properties wherever applicable
- FMOD event parameters are automatically mapped to SFXParameters on channel User0
- IMPORTANT: all event parameters thus become global in Torque!! this also allows to key several events to the same parameter in Torque; for independent parameters, use unique names
- SFXFMODEvents are SFXTracks and can be used just like the other track types (SFXProfiles and SFXPlayLists)
- support for FMOD Designer interactive music will likely be available with 1.2
Ambient Audio
- a new SFXAmbience datablock describes ambient audio spaces
- currently, audio spaces consist of a reverb environment (SFXEnvironment), a soundtrack (SFXTrack), and a sequence of automatic SFXState activations (this is very useful to set AudioLocation states)
- a new soundscape mixing system allows to activate and blend multiple audio spaces simultaneous
- each SFXAmbience instance is a unique space and thus will not have more than one simultaneous activation regardless of how many objects have the space assigned
- the global audio space can be set on the LevelInfo object
- a tracking system follows listener movement and automatically activates ambient audio spaces that the listener moves into
- currently all WaterObjects (WaterBlock, WaterPlane, River) and Zones can be assigned ambient audio spaces; more object types will be coupled to the system in 1.2
- this system is only just starting to emerge; more functionality will be available in 1.2
Reverb
- a new SFXEnvironment datablock describes global reverb environments
- a range of reverb presets are available in core/scripts/client/audioEnvironments.cs
- per-sound reverb properties can be set on SFXDescriptions (useCustomReverb to activate)
- NOTE: reverb in 1.1 Alpha is still broken; it is expected to be fully functional in 1.1 Beta
- NOTE: reverb in 1.1 is FMOD only
//Edit: formatting
//Addition
- the FMOD profiler can now be used with Torque by starting with $pref::SFX::FMOD::enableProfile=true
About the author
#4
Hehe.
On a general note, while FMOD really is worth every penny and a truly awesome package, all of the functionality described above except FMOD Designer integration (well, obviously) and reverb do work with all other SFX providers (DSound, OAL, and XAudio... and even Null, though it somehow seems to me that people won't appreciate being able to hear fully distance attenuated, elegantly faded, and accurately prioritized silence much).
11/22/2009 (6:28 pm)
Hehe.
On a general note, while FMOD really is worth every penny and a truly awesome package, all of the functionality described above except FMOD Designer integration (well, obviously) and reverb do work with all other SFX providers (DSound, OAL, and XAudio... and even Null, though it somehow seems to me that people won't appreciate being able to hear fully distance attenuated, elegantly faded, and accurately prioritized silence much).
#5
11/22/2009 (7:57 pm)
Thanks for all this Rene ... now there's else I've got to learn ... 
#6
11/22/2009 (10:16 pm)
I have been trying to get the SFXEnvironments working with no luck. Do they currently not work or are there special requirements for them? 
#7
11/23/2009 (9:03 am)
@Adam: are you using FMOD?
#8
Yep, like mentioned, reverb isn't really working yet. The settings are all passed on to FMOD but for some reason I have yet to pinpoint, they don't take effect and FMOD never attaches reverb to the sounds. Expect this to be solved for 1.1 Beta.
11/23/2009 (12:15 pm)
Yep, like mentioned, reverb isn't really working yet. The settings are all passed on to FMOD but for some reason I have yet to pinpoint, they don't take effect and FMOD never attaches reverb to the sounds. Expect this to be solved for 1.1 Beta.
#9
Change the line in sfxFMODDevice.cpp that says
to
and reverb will work.
11/24/2009 (2:54 am)
Ok, fixed the problem with reverb. Turns out I was setting up FMOD_REVERB_PROPERTIES incorrectly and was too blind to find this later on.Change the line in sfxFMODDevice.cpp that says
prop.Environment = -1;
to
prop.Environment = 0;
and reverb will work.
#10
11/24/2009 (3:25 pm)
Impressive work on the SFX system Rene!
#11
Thanks, Novack :)
With FMOD, sound now sounds seriously awesome. Software HRTF (head-related transfer function) is now also enabled by default and it gives a great sense of locality.
The only thing really left missing from the picture now is sound occlusion, but the foundations for it are already laid out and it will come in 1.2.
11/24/2009 (8:42 pm)
Thanks, Novack :)
With FMOD, sound now sounds seriously awesome. Software HRTF (head-related transfer function) is now also enabled by default and it gives a great sense of locality.
The only thing really left missing from the picture now is sound occlusion, but the foundations for it are already laid out and it will come in 1.2.
#12
11/26/2009 (8:34 am)
What is the limit on playlists? For example if I take a bunch of wave files(each one representing a note from a piano) and I put them in a sequence like a sheet music piece. And then I hit play on the playlist how would that work out? Would I only be able to queue 128 or 256 wave files or does each one have to be unique.
#13
Except for the limitation of 16 slots per list, there are not really limitations on playlists otherwise. They can be cascaded and by using a playlist with each slot linked to another playlist, you would get 256 slots in total.
The example you describe would definitely work though the system will not guarantee gapless playback there, i.e. there may be slight variations in the delay between sounds due to the periodic updating of the system. Using it for sort of dynamically composing a tune out of individual notes would thus not be ideal.
For what you describe, you may be better off using FMOD Designer.
As a mostly unrelated sidenote: one thing that isn't obvious from my description above is that, unlike their counterparts in iTunes and such, playlists need not be sequential in nature. A playlist may, for example, very well be used to overlay one-shot sounds on top of an ambient base track that is continually running in the same playlist.
11/26/2009 (8:11 pm)
Except for the limitation of 16 slots per list, there are not really limitations on playlists otherwise. They can be cascaded and by using a playlist with each slot linked to another playlist, you would get 256 slots in total.
The example you describe would definitely work though the system will not guarantee gapless playback there, i.e. there may be slight variations in the delay between sounds due to the periodic updating of the system. Using it for sort of dynamically composing a tune out of individual notes would thus not be ideal.
For what you describe, you may be better off using FMOD Designer.
As a mostly unrelated sidenote: one thing that isn't obvious from my description above is that, unlike their counterparts in iTunes and such, playlists need not be sequential in nature. A playlist may, for example, very well be used to overlay one-shot sounds on top of an ambient base track that is continually running in the same playlist.
#15
Definitely. Being on the road is holding me up a little but I'm currently writing up some simple instructions on how to do the common tasks one would use the various features for.
11/28/2009 (3:07 am)
Definitely. Being on the road is holding me up a little but I'm currently writing up some simple instructions on how to do the common tasks one would use the various features for.
Torque 3D Owner Nicolas Buquet
Very good work.
Nicolas Buquet
www.buquet-net.com/cv/