Playback Group
Introduction
Playback Group is a set of rules that can be used to manage the playback behavior of multiple sounds as a group. It determines whether a sound can be played and can also stop playback when certain conditions are met.
How To Use?
Creating a Playback Group
Playback Groups are ScriptableObjects that can be created by right-clicking in the Project Winodw, and selecting Create > BroAudio > PlaybackGroup.
Assigning a Playback Group
Once created, a playback group can be assigned to AudioAsset, AudioEntity, or even passed directly when calling BroAudio.Play(), which overrides any pre-existed groups assigned to the sound.
The Hierarchical Design
Playback Groups follow a hierarchy that aligns with AudioAssets and AudioEntities, plus a system-level group (Global Playback Group) above them and an optional override when calling BroAudio.Play(). The hierarchy is as follows:
This means that if no group is assigned at a specific level, the system will look for an avaliable group from its upper level until it reaches to the top level, which is the Global Playback Group. This top group is never null and typically have the least restrictive rules.
The Globabl Playback Group can be customized in Tools > BroAudio > Preferences.
Not only does this hierarchy apply to groups, but it also applies to individual rules within a group. Each rule can choose to override or inherit its behavior from an upper-level group. (More details in the Override section.)
What it does?
A Playback Group contains a set of rules that are evaluated whenever a sound is cued for playback. If all rules pass, the sound plays; otherwise, playback is canceled.
When selecting the asset file of a Playback Group, the Inspector displays a table with three columns. Let’s take the built-in GlobalPlaybackGroup.asset as an example to explain these columns:
Override
The first column, marked with a ✏️ icon, represents the Override option.
When enabled, the rule is applied within this group.
When disabled, the rule is ignored, and the system searches for an applicable rule in the upper levels of the hierarchy.
Since GlobalPlaybackGroup.asset is at the system level (assigned in Tools > BroAudio > Preferences), all override options are typically enabled here
Rule and Value
Max Playable Count This rule tracks the number of playing sounds managed by the group. If it reaches the specified limit (the value), any additional play requests will be canceled. This is useful for controlling large numbers of sounds in a scene and maintaining balance between different sound types. The default value is Infinity, meaning there's no limit.
Comb Filtering Time This rule prevents sounds playing in a short period of time from producing the Comb-Filtering effect. The default value is 0.04 seconds, but you can adjust it as needed or set it to 0 to disable this prevention.
Rules can have more properties to assist it when evaluating, these are called the "Derivative properties". For example, Comb-Filtering Time has: Ignore If Same Frame Bypasses the rule if sounds are played within the exact same frame..
Log Warning If Occurs Logs a warning if a sound is played within the prevention time.
Custom Rules
The built-in GlobalPlaybackGroup and any groups created via Create > BroAudio > PlaybackGroup are made by the DefaultPlaybackGroup script, which include rules like Max Playable Count and Comb-Filtering Time by default. However, you can also create a new one from scratch or inherit the DefaultPlaybackGroup to extend its functionality!
Creating Custom Rules and Playback Groups
To add custom rules, create a new class that inherit from either:
DefaultPlaybackGroupto retain BroAudio’s pre-configured rulesPlaybackGroupto create a new group from scratch
This allows you to define new rules by declaring values and overriding methods.
The API
Rule<T>
A generic abstract class representing a rule in a Playback Group. It stores a value and a method that used for evaluating playbacks.
Creation
Define a class that inherits from Rule<T>:
// Example from DefaultPlaybackGroup
[Serializable]
public class MaxPlayableCountRule : Rule<int>
{
public MaxPlayableCountRule(int value) : base(value)
{
}
// Optional: Allow implicit conversion from int
public static implicit operator MaxPlayableCountRule(int value) => new MaxPlayableCountRule(value);
}Declaration Declare the Rule in the PlaybackGroup
// Example from DefaultPlaybackGroup
[SerializedField] private MaxPlayableCountRule _maxPlayableCount = new Rule<int>(-1);
// or _maxPlayableCount = -1; if the implicit operator is implementedPlaybackGroup
An abstract class that defines the rules. It inherits from ScriptableObject and implements IPlayableValidator.
Defining Rules in a Playback Group
InitializeRules()
A method that should be overridden to initialize all the rules. Please use the Initialize(IRule, IsPlayableDelegate) method in conjunction to setup the rules.
// Example from DefaultPlaybackGroup
protected override IEnumerable<IRule> InitializeRules()
{
yield return Initialize(_maxPlayableCount, IsPlayableLimitNotReached);
yield return Initialize(_combFilteringTime, CheckCombFiltering);
}Initialize(IRule, IsPlayableDelegate)
Assigns a method to a rule for evaluating playback.
IPlayableValidator
IsPlayable(SoundID)
Whether the sound can be played or not.
OnGetPlayer(IAudioPlayer player)
Triggered when the player passes the rule and is about to play. You can cache the player for further control.
Attributes
There are attributes available for Rule<T> and PlaybackGroup.
Saves the value in the asset and exposes it in the Inspector.
Displays a tooltip when hovering over a rule.
[InspectorName]
Changes the display name of a rule in the inspector.
[ValueButton]
Adds a button for modifying the rule’s value.
[DerivativeProperty]
ForDraws a connection line in the Inspector to show rule relationships. Use isEnd to specify the endpoint.
[CustomDrawing
Method]
Uses a custom method for drawing the rule in the Inspector. parameters: Type className, string methodName
Adds a header above some fields in the Inspector.
Adds spacing in the Inspector.
Last updated