> For the complete documentation index, see [llms.txt](https://docs.bestway.com.ua/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.bestway.com.ua/game-settings/user-control-sound.md).

# User control sound

User Control Sound (UCS) allows you to modify playing sounds parameters or start new sounds depending on user control conditions.

UCS provides fine-grained control over sound behavior in real-time by:

* Modifying **listener parameters** (HDR, LPF) based on camera or selection state;
* Applying **conditional sound logic** via includes and operations;
* Grouping sounds for organized control and activation;
* Supporting both **static** and **dynamic** group outputs;
* Integrating with scripts using the `active` flag.

## Listener Control

The `listener` block defines how UCS modifies the audio listener’s parameters in response to user input or state.

> **Template**
>
> ```
> {listener
>     {includes
>         // Conditions that must be met
>     }
>     {operations
>         // Listener parameter modifications
>     }
> }
> ```
>
> * {includes \[...]} : contains conditions (e.g., camera, selection) required to apply the operations block
> * {operations \[...]}: defines parameter modifications such as HDR, LPF, and occlusion.

### Occlusion

Occlusion controls high-frequency dampening of sound:

* **Default value**: `1` (no effect)
* **Range**: `1–10`
* **Higher values** = stronger high-frequency filtering

{% hint style="info" %}
Occlusion works together with the group's **LPF** level. To cancel occlusion, set the LPF level equal to the occlusion value.
{% endhint %}

### HDR

The HDR block modifies how the listener reacts to loud sounds:

* Increasing the **loudness** simulates listener adaptation to intense audio events.
* This is separate from the sound’s own HDR values — the listener’s loudness applies globally when include conditions are met.

{% hint style="info" %}
Listeners Includes and operations examples and description see inside sound/user\_control.set
{% endhint %}

## Group

UCS works with groups. Group is a named set of includes conditions and array of output operations.

To make a sound respond to **User Control Sound (UCS)**, follow these **three steps.**

{% stepper %}
{% step %}
Create a named group in the `sound/user_control.set` file.\
Example:

```c
{group hit
    // includes and outputs
}
```

{% endstep %}

{% step %}
Assign this group to the sound inside the `loudness` block, a `folder.set`, or `composite` parameters.\
Example:

```c
{group "hit"}
```

{% endstep %}

{% step %}
For the script commands you must specify the “active” flag.\
Example:

```c
{start_sound "hit/big/metal_hit" active}
{link_sound "move" "vehicle/groundborne/pz1/pz1_tracks" active}
```

{% endstep %}
{% endstepper %}

### Group options

By default the group is static. It means that outputs select only once before start. At all playback time output is set the same.

To update output set by the way of sound playback you must specify a dynamic flag.

{% hint style="info" %}
Group options see inside sound/user\_control.set
{% endhint %}

### Group includes

By default UCS applies outputs for any sound inside a group.

You can Include only required user control options with Includes block.

All includes related to the user player.

{% hint style="info" %}
See parameters specification inside sound/user\_control.set.
{% endhint %}

### Group outputs

Group output is a set of conditions and operations with sound parameters. Depending on static or dynamic groups parameters modify only when sound starts or continuously all the playback time.

{% hint style="info" %}
Output Includes and operations examples and description see inside sound/user\_control.set
{% endhint %}