swiftlys2/docs/api/releases/features/ai/

Sound Events

APISoundEvent lets plugins emit game sound events with custom parameters and recipient filters. There is no Core service for it - you construct the class yourself (SwiftlyS2.Shared.Sounds) and dispose it once you're done.

Creating Sound Events

using var soundEvent = new SoundEvent();
soundEvent.Name = "Weapon_AK47.Single";
soundEvent.Volume = 0.8f;
soundEvent.Pitch = 1.0f;
 
// or initialize name, volume and pitch directly
using var soundEvent2 = new SoundEvent("Weapon_AK47.Single", volume: 0.8f, pitch: 1.0f);
ConstructorDefaults
SoundEvent()Name is "", Volume and Pitch are 1.0f
SoundEvent(string name, float volume = 1.0f, float pitch = 1.0f)name is required, volume and pitch fall back to 1.0f

Both constructors leave SourceEntityIndex at -1, so a new instance has no source entity until you assign one.

Configuring Core Properties

soundEvent.Name = "Weapon_AK47.Single";
soundEvent.Volume = 0.6f;               // float; stored as the public.volume field
soundEvent.Pitch = 1.15f;               // float; stored as the public.pitch field
soundEvent.SourceEntityIndex = -1;      // source entity index; -1 (default) = no source entity
 
soundEvent.SetSourceEntity(entity);     // helper instead of assigning entity.Index yourself

Name is the sound event name as used in the game's scripts and prefabs, e.g. Weapon_AK47.Single. Volume and Pitch are convenience wrappers around the float fields public.volume and public.pitch, so SetFloat("public.volume", 0.6f) does the same thing. Setting a name, a parameter or SourceEntityIndex only changes the instance - the values are sent on the next emit.

Setting Custom Sound Fields

GetX mirrors every SetX 1:1. SetFloat3 also has a Vector overload.

soundEvent.SetBool("public.some_flag", true);
soundEvent.SetInt32("public.team", 2);
soundEvent.SetUInt32("public.seed", 123u);
soundEvent.SetFloat("public.volume_override", 0.7f);
soundEvent.SetFloat3("public.position", 100.0f, 200.0f, 300.0f);
soundEvent.SetFloat3("public.position", position); // Vector overload
 
bool someFlag = soundEvent.GetBool("public.some_flag");
Vector pos = soundEvent.GetFloat3("public.position");

Every setter takes the field name and the value, every getter the field name:

Getter / setterField type
SetBool / GetBoolbool
SetInt32 / GetInt32int
SetUInt32 / GetUInt32uint
SetFloat / GetFloatfloat
SetFloat3 / GetFloat3Vector

Getters return the type's default (false, 0, 0.0f, or a zero Vector) when the field was never set, or was set with a different type. Fields set on an instance stay set, so every later Emit() sends them again.

Configuring Recipients

Recipients are managed through APICRecipientFilter, exposed by the Recipients property - it returns the filter by reference, so you configure the filter of the sound event in place. A newly created SoundEvent has an empty filter, so add the players that should hear it.

// Broadcast to everyone
soundEvent.Recipients.AddAllPlayers();
 
// Or target specific players
soundEvent.Recipients.RemoveAllPlayers();
soundEvent.Recipients.AddRecipient(0);
soundEvent.Recipients.AddRecipient(1);
 
// Remove one player again
soundEvent.Recipients.RemoveRecipient(1);
 
int count = soundEvent.Recipients.GetRecipientCount();
foreach (int slot in soundEvent.Recipients.GetRecipients())
{
    // every slot currently in the filter
}

Because Recipients is returned by reference, you can also assign a whole filter built elsewhere:

soundEvent.Recipients = CRecipientFilter.FromSingle(0);
soundEvent.Recipients = CRecipientFilter.FromMask(0b11UL);

AddRecipient/RemoveRecipient take player slots 0-63 and throw IndexOutOfRangeException outside that range. The filter also exposes RecipientsMask (ulong, the raw mask), ToMask(), BufferType (APINetChannelBufType_t, BUF_RELIABLE for a newly constructed filter), and the InitMessage, DisabledPrediction and PredictedSlot fields - see Network Messages for the filter's static FromMask, FromPlayers and FromSingle factories and the rest of its members.

Emitting Sound Events

uint guid = soundEvent.Emit();             // main thread only
uint guid = await soundEvent.EmitAsync();  // schedules the emit onto the main thread

Emit() returns the uint guid of the started sound event; you can observe the outgoing CMsgSosStartSoundEvent in a server net-message hook (see Network Messages). Calling Emit() again on the same instance starts another event with a new guid.

Emit() is thread-unsafe (APIThreadUnsafeAttribute) and must run on the main thread. Use EmitAsync(), which returns Task<uint> and dispatches the call back onto the game thread, whenever you're not sure execution is on the main thread - see Thread Safety.

Disposing

SoundEvent implements IDisposable - wrap it in using (or call Dispose()) so its native resources are released once you're done emitting.

Members at a Glance

MemberTypeNotes
SoundEvent() / SoundEvent(string name, float volume = 1.0f, float pitch = 1.0f)constructorsVolume/Pitch are 1.0f, SourceEntityIndex is -1
NamestringSound event name to play; empty by default
Volumefloatpublic.volume field, 1.0f by default
Pitchfloatpublic.pitch field, 1.0f by default
SourceEntityIndexintSource entity index, -1 by default (no source entity)
Recipientsref CRecipientFilterRecipient filter, empty by default; assignable
SetSourceEntityvoid (CEntityInstance)Assigns entity.Index to SourceEntityIndex
SetBool / GetBool, SetInt32 / GetInt32, SetUInt32 / GetUInt32, SetFloat / GetFloatbool, int, uint, floatCustom sound fields, by field name
SetFloat3 (three floats or a Vector) / GetFloat3VectorCustom 3D sound fields
EmituintThread-unsafe; returns the started event's guid
EmitAsyncTask<uint>Main-thread dispatch of Emit
DisposevoidIDisposable implementation