PlaySound3D: Difference between revisions
m (Changed syntax) |
|||
(21 intermediate revisions by 17 users not shown) | |||
Line 1: | Line 1: | ||
__NOTOC__ | __NOTOC__ | ||
{{Client function}} | {{Client function}} | ||
Creates a [[sound]] [[element]] in the GTA world and plays it immediately after creation for the local player. [[setElementPosition]] can be used to move the [[sound]] element around after it has been created. Remember to use [[setElementDimension]] after creating the sound to play it outside of dimension 0. | Creates a [[sound]] [[element]] in the GTA world and plays it immediately after creation for the local player. [[setElementPosition]] can be used to move the [[sound]] element around after it has been created. Remember to use [[setElementDimension]] after creating the sound to play it outside of dimension 0. | ||
{{Added feature/item|1.6.0|1.5.9|21034|Added the feature of playing WebM files.}} | |||
{{Note| | |||
*The only supported audio formats are MP3, WAV, OGG, FLAC, RIFF, MOD, WEBM, XM, IT and S3M. | |||
*For performance reasons, when using playSound3D for effects that will be played lots (i.e. weapon fire), it is recommend that you convert your audio file to a one channel (mono) WAV with sample rate of 22050 Hz or less. Also consider adding a limit on how often the effect can be played e.g. once every 50ms.}} | |||
==Syntax== | ==Syntax== | ||
<syntaxhighlight lang="lua">element playSound3D ( string soundPath, float x, float y, float z, [ bool looped = false ] )</syntaxhighlight> | <syntaxhighlight lang="lua"> | ||
{{OOP||[[Sound|Sound3D]] | element playSound3D ( string soundPath, float x, float y, float z, [ bool looped = false, bool throttled = true ] ) | ||
===Required Arguments=== | </syntaxhighlight> | ||
*'''soundPath:''' | {{OOP||[[Sound|Sound3D]]}} | ||
===Required Arguments=== | |||
*'''soundPath:''' raw data or [[filepath]] to the sound file you want to play. ('''Note:''' Playing sound files from other resources requires the target resource to be in the running state) | |||
*'''soundURL:''' the URL (http://, https:// or ftp://) of the sound file you want to play. (In this version the file does not have to be predefined in the [[meta.xml]]) | |||
*'''x:''' a [[float]]ing point number representing the X coordinate on the map. | *'''x:''' a [[float]]ing point number representing the X coordinate on the map. | ||
*'''y:''' a [[float]]ing point number representing the Y coordinate on the map. | *'''y:''' a [[float]]ing point number representing the Y coordinate on the map. | ||
Line 16: | Line 21: | ||
===Optional Arguments=== | ===Optional Arguments=== | ||
{{OptionalArg}} | {{OptionalArg}} | ||
*'''looped:''' | *'''looped:''' a [[boolean]] representing whether the sound will be looped. To loop the sound, use ''true''. | ||
{{New feature/item|3.0150|1.5|| | |||
*'''throttled:''' a [[boolean]] representing whether the sound will be throttled (i.e. given reduced download bandwidth). To throttle the sound, use ''true''. | |||
}} | |||
===Returns=== | ===Returns=== | ||
Line 22: | Line 30: | ||
==Example== | ==Example== | ||
This example creates a looping sound within a pizza shop. | This example creates a looping sound within a pizza shop. It's located in San Fierro near Pier 69. | ||
<section name="Example" class="client" show="true"> | <section name="Example" class="client" show="true"> | ||
<syntaxhighlight lang="lua"> | <syntaxhighlight lang="lua"> | ||
Line 28: | Line 36: | ||
local sound = playSound3D("sounds/song.mp3", 373.14, -125.21, 1001, true) | local sound = playSound3D("sounds/song.mp3", 373.14, -125.21, 1001, true) | ||
end | end | ||
addEventHandler("onClientResourceStart", | addEventHandler("onClientResourceStart", resourceRoot, onResourceStart) | ||
</syntaxhighlight> | </syntaxhighlight> | ||
</section> | </section> | ||
This example | |||
This example plays internet radio at Grove street. | |||
<section name="Example 2" class="client" show="true" > | <section name="Example 2" class="client" show="true" > | ||
<syntaxhighlight lang="lua"> | <syntaxhighlight lang="lua"> | ||
addEventHandler( 'onClientResourceStart', resourceRoot, | addEventHandler('onClientResourceStart', resourceRoot, | ||
function( ) | function() | ||
local uSound = playSound3D( 'http:// | local uSound = playSound3D('http://977music.com/itunes/80s.pls', 2498, -1659, 12) | ||
setSoundMaxDistance( uSound, 100 ) | setSoundMaxDistance(uSound, 100) | ||
end | end | ||
) | ) | ||
Line 45: | Line 54: | ||
==See Also== | ==See Also== | ||
{{Client_audio_functions}} | {{Client_audio_functions}} | ||
[[HU:playSound3D]] | |||
[[AR:playSound3D]] | [[AR:playSound3D]] | ||
[[DE:playSound3D]] | [[DE:playSound3D]] | ||
[[RU:playSound3D]] | [[RU:playSound3D]] | ||
[[PT-BR:playSound3D]] |
Latest revision as of 12:44, 17 June 2024
Creates a sound element in the GTA world and plays it immediately after creation for the local player. setElementPosition can be used to move the sound element around after it has been created. Remember to use setElementDimension after creating the sound to play it outside of dimension 0. Added the feature of playing WebM files.
Syntax
element playSound3D ( string soundPath, float x, float y, float z, [ bool looped = false, bool throttled = true ] )
OOP Syntax Help! I don't understand this!
- Method: Sound3D(...)
Required Arguments
- soundPath: raw data or filepath to the sound file you want to play. (Note: Playing sound files from other resources requires the target resource to be in the running state)
- soundURL: the URL (http://, https:// or ftp://) of the sound file you want to play. (In this version the file does not have to be predefined in the meta.xml)
- x: a floating point number representing the X coordinate on the map.
- y: a floating point number representing the Y coordinate on the map.
- z: a floating point number representing the Z coordinate on the map.
Optional Arguments
NOTE: When using optional arguments, you might need to supply all arguments before the one you wish to use. For more information on optional arguments, see optional arguments.
- looped: a boolean representing whether the sound will be looped. To loop the sound, use true.
- throttled: a boolean representing whether the sound will be throttled (i.e. given reduced download bandwidth). To throttle the sound, use true.
Returns
Returns a sound element if the sound was successfully created, false otherwise.
Example
This example creates a looping sound within a pizza shop. It's located in San Fierro near Pier 69.
function onResourceStart() local sound = playSound3D("sounds/song.mp3", 373.14, -125.21, 1001, true) end addEventHandler("onClientResourceStart", resourceRoot, onResourceStart)
This example plays internet radio at Grove street.
addEventHandler('onClientResourceStart', resourceRoot, function() local uSound = playSound3D('http://977music.com/itunes/80s.pls', 2498, -1659, 12) setSoundMaxDistance(uSound, 100) end )
See Also
- getRadioChannel
- getRadioChannelName
- getSFXStatus
- getSoundBPM
- getSoundBufferLength
- getSoundEffectParameters
- getSoundEffects
- getSoundFFTData
- getSoundLength
- getSoundLevelData
- getSoundMaxDistance
- getSoundMetaTags
- getSoundMinDistance
- getSoundPan
- getSoundPosition
- getSoundProperties
- getSoundSpeed
- getSoundVolume
- getSoundWaveData
- isSoundLooped
- isSoundPanningEnabled
- isSoundPaused
- playSFX3D
- playSFX
- playSound3D
- playSound
- setRadioChannel
- setSoundEffectEnabled
- setSoundEffectParameter
- setSoundLooped
- setSoundMaxDistance
- setSoundMinDistance
- setSoundPan
- setSoundPanningEnabled
- setSoundPaused
- setSoundPosition
- setSoundProperties
- setSoundSpeed
- setSoundVolume
- stopSound
- Shared
- playSoundFrontEnd