Lou Montana: Text replacement - "\{\{GameCategory\|armaR\|Modding\|(Guidelines|Tutorials)\|([^=↵]*)\}\}" to "{{GameCategory|armaR|Modding|$2|$1}}"

2025-02-26T12:31:52Z

Text replacement - "\{\{GameCategory\|armaR\|Modding\|(Guidelines|Tutorials)\|([^=↵]*)\}\}" to "{{GameCategory|armaR|Modding|$2|$1}}"

← Older revision		Revision as of 14:31, 26 February 2025
Line 177:		Line 177:


	{{GameCategory\|armaR\|Modding\|Guidelines~~\|Audio~~}}		{{GameCategory\|armaR\|Modding\|Audio\|Guidelines}}

Lou Montana: Page creation

2025-02-20T15:44:34Z

Page creation

New page

{{TOC|side}}
At the most basic level, Sound Components are Components that give an Entity the ability to play sounds defined in ACP files.
The ACP files available to the Entity are defined in the Filenames section of its SoundComponent.

Via GameCode or a Script, the {{Link/Enfusion|armaR|SoundComponent}} can receive the instruction to play a Sound. This instruction will contain a string with the desired Sound Event Name.
The SoundComponent will then search through its connected ACP files and play the first Sound whose name matches the Sound Event Name provided by the instruction.

There are different SoundComponents: Some are generic, like the {{Link/Enfusion|armaR|BaseSoundComponent}} and {{Link/Enfusion|armaR|SimpleSoundComponent}},
and some are meant to be used for a specific purpose, e.g the {{Link/Enfusion|armaR|WeaponSoundComponent}} or {{Link/Enfusion|armaR|VehicleSoundComponent}}.

The main reason for having multiple different SoundComponents is performance.
More "advanced" SoundComponents perform a variety of checks and calculations that might not be needed in every use case, such as interior detection or listening in on animations for sound events.

It is therefore recommended to familiarise oneself with the different SoundComponent types and use that one that matches the required featureset the closest.

The most common feature of "advanced" SoundComponent variations is it to read Signal values from an Entity's SignalsManagerComponent as well as the Gameworld's {{Link/Enfusion|armaR|GameSignalsManager}}.

== SoundComponent Variants ==

{| class="wikitable align-center-col-2 align-center-col-3 align-center-col-4 align-center-col-5 align-center-col-6"
! SoundComponent Type
! Dynamic Simulation
! Trigger Update
! Can read Signals from Signals Manager
! Sound position's dynamic update
! Listen to animation events
! Dedicated features
|-
| {{Link/Enfusion|armaR|BaseSoundComponent}}
| {{Icon|unchecked}}
| {{Icon|checked}}<br>but must be called manually via UpdateTrigger
| {{Icon|unchecked}}
| {{Icon|unchecked}}
| {{Icon|unchecked}}
| {{n/a}}
|-
| {{Link/Enfusion|armaR|SimpleSoundComponent}}
| {{Icon|checked}}
| {{Icon|checked}}<br>but must be called manually via UpdateTrigger
| {{Icon|unchecked}}
| {{Icon|unchecked}}<br>but UpdateSoundJob is called when any of assigned {{hl|.acp}}s is in the audibility range.
| {{Icon|unchecked}}
| {{n/a}}
|-
| {{Link/Enfusion|armaR|SoundComponent}}
| {{Icon|checked}}
| {{Icon|checked}}
| {{Icon|checked}}
| {{Icon|checked}}
| {{Icon|checked}}
|
* Reads local signals from the SignalsManagerComponent.
* Reads Global Signals from the GameSignalsManager.
* Listens to Animation Events (BaseItemAnimationComponent or BaseAnimPhysComponent).
* EOnFrame flag enables calling UpdateSoundJob() from entity EOnFrame.
* Manages sound transformation offset using bone, vector offset, and sound points.
* Manages Component activation based of the presence of playing sound.
* Updates sound position to entity position.
* Updates triggers for sound nodes.
|-
| {{Link/Enfusion|armaR|WeaponSoundComponent}}
| {{Icon|checked}}
| {{Icon|checked}}
| {{Icon|checked}}
| {{Icon|checked}}
| {{Icon|checked}}
|
* Manages Signals for the SOUND_SHOT Event when using speed of sound simulation. On a shot event, a signal snapshot with current signal values is created and this snapshot is used once shot sound is triggered.
|-
| {{Link/Enfusion|armaR|CharacterSoundComponent}}
| {{Icon|checked}}
| {{Icon|checked}}
| {{Icon|checked}}
| {{Icon|checked}}
| {{Icon|checked}}
|
* Updates Surface signals for footstep Eound Events. An Animation Event is considered as Footstep Event if its bone name contains the "foot" string.
|-
| {{Link/Enfusion|armaR|VehicleSoundComponent}}
| {{Icon|checked}}
| {{Icon|checked}}
| {{Icon|checked}}
| {{Icon|checked}}
| {{Icon|checked}}
|
* Dedicated slots for wheel sound. Sound position offset is defined directly on the component. The Surface signal for each wheel is tied to this position.
|-
| {{Link/Enfusion|armaR|CommunicationSoundComponent}}
| {{Icon|checked}}
| {{Icon|checked}}
| {{Icon|checked}}
| {{Icon|checked}}
| {{Icon|checked}}
|
* See {{Link|#CommunicationSoundComponent}}
|}

== Components ==

=== CommunicationSoundComponent ===

For purposes of the communication protocol, the dedicated Communication Sound Component was created. Simplified, this component have two main purposes.
Based on input signals, it is able to construct a sentence that is represented as
* a list of {{hl|.wav}} files that the audio system can play in sequence
* a string array that is used for displaying subtitles.

The sentence definition is done in one place in audio project, so it should keep the whole configuration and maintenance of the system manageable.

==== Animation Sound Priority Ranges ====
{| class="wikitable"
! Range
! Description
|-
| '''< 0'''
| Discarded - Negative values are not allowed and used by the priority queue.
|-
| '''0..99'''
| Queued if current playing sound has a higher priority
|-
| '''100..199'''
| Discarded if current playing sound has a higher priority

100 = IgnoreQueue, 1XX = Priority (Example: 199 = Priority Queue with 99 Priority)
|-
| '''> 199'''
| Discarded - Values higher than 199 are not allowed and used by the priority queue.
|}

=== SCR_AmbientSoundComponent ===

==== HandleQueryEntities() ====

* By default {{Link/Enfusion|armaR|SCR_AmbientSoundsComponent}} performs sphere queries over entities and stores the output into appropriate data structures. Those can be then used by any configured SCR_AmbientSoundsEffects.
* From script, we can access counts of the {{Link/Enfusion|armaR|EQueryType}} types
* On engine side references to entities of the following types are stored. There is no script API to access them directly.

==== Looped Sounds System ====
* System for playing looped sounds with posibility to create multiple instances of the same event and without need for a signal for each sound instance
* System keeps a pool of triggered sounds and check if, they are playing or tries to trigger them.
* Used only by insects particles
* API: see {{Link/Enfusion|armaR|SCR_AmbientSoundsComponent}}<enforce>
SCR_AudioHandleLoop SoundEventLooped(string soundEvent, vector transformation[4])
void TerminateLooped(SCR_AudioHandleLoop audioHandleLoop)
void UpdateLoopedSounds()
</enforce>

== Activeness ==

For certain features like position update, or trigger functionality, the {{hl|SoundComponent}} needs to be active.
That means that the {{hl|SoundComponent}} is added to the {{Link/Enfusion|armaR|SndSystem}} and <enforce inline>SoundComponent.UpdateSoundJob()</enforce> is called.

=== Rules ===

* If any sound is playing on the SoundComponent, it is added to SndSystem. When the sound finishes playing, the SoundComponent is removed from SndSystem, unless additional flags on the SoundComponent are used.
* If any ACP on the SoundComponent uses triggers, the SoundComponent is always automatically added to SndSystem. There it is handled by the Dynamic Simulation, meaning the SndSystem checks the SoundComponent's distance from the listener, and if the listener is in the audible distance of the triggered sound with the largest audible range, it will start calling <enforce inline>SoundComponent.UpdateSoundJob()</enforce>
* Distance management flag enables addition of any SoundComponent to Dynamic simulation on SndSystem. In that case largest audible distance (evaluated from both triggered and not-triggered events is used).
* Include Inactive flag makes sure, that SoundComponent is not removed from SndSystem when the entity is deactivated.
** If there is a trigger sound on the component and you are not sure, if EOnActivate/EOnDeactivate are called on the entity, set to true.
** If there is a trigger sound on the component and you know EOnActivate/EOnDeactivate events are called and you want to use them to improve SndSystem performance, set to false.
* If <enforce inline>SoundComponent.UpdateSoundJob()</enforce> is supposed to be always called, no matter how far is listener is from the component, use OnFrameUpdate flag

=== OnPostInit SndSystem Components ===

Components are added to {{hl|SndSystem}} in <enforce inline>OnPostInit()</enforce> if one of the following:
* any ACP on the SoundComponent uses triggers
* OnFrameUpdate is set to true
* Distance management is set to true

; EOnActivate
: SoundComponent is added to SndSystem

; EOnDeactivate
: SoundComponent is removed from SndSystem unless '''Include Inactive''' is set to true

{{GameCategory|armaR|Modding|Guidelines|Audio}}

Arma Reforger:Audio: Sound Components - Revision history

Lou Montana: Text replacement - "\{\{GameCategory\|armaR\|Modding\|(Guidelines|Tutorials)\|([^=↵]*)\}\}" to "{{GameCategory|armaR|Modding|$2|$1}}"

Lou Montana: Page creation