feat: Add SoundEvent API for emitting sounds with parameters

[makadore]

EmitSound takes volume and pitch arguments that never reach the client. It goes through CBaseEntity::EmitSoundFilter, and the CMsgSosStartSoundEvent that comes out of it carries no packed_params at all, so there is nothing for the client to apply. Captured from a live server, this is the whole message the current path sends:

soundevent_guid=347 soundevent_hash=3838664315 source_entity_index=5 seed=347

The source already says as much: m_nPitch is annotated "not working, can't fix, i think the game abandon it", and m_flVolume is a volume_atten rather than a volume. This was raised in #919, and #126 is still open.

This adds a SoundEvent that builds the message directly, so sound operator parameters can be chosen per emit.

using var sound = new SoundEvent("Weapon_AK47.Single");
sound.SourceEntityIndex = (int)player.PlayerPawn.Value!.Index;
sound.SetParam(SoundEvent.Volume, 0.5f);
sound.SetParam(SoundEvent.Pitch, 1.5f);
sound.EmitToAll();

Emit returns the guid, which SoundEvent.Stop takes to end a sound early. Recipients come from a RecipientFilter, so a sound can go to one player, one team, or everyone.

SourceEntityIndex decides where the sound plays from: -1, the default, plays it at each recipient; 0 plays it at public.position in the world; any other index attaches it to that entity. For a player that is the pawn, which is what the game's own messages name.

SetParam takes any public.* parameter name, not a fixed set, so anything the sound's operator stack reads can be driven from a plugin without a change here first:

sound.SetParam("public.velocity", 250f);
sound.SetParam(SoundEvent.Position, new Vector(0, 0, 0));

Volume, pitch and position are the three this was tested against. Whether any other parameter does something depends on the stack behind the sound, which is noted in the API documentation.

Implementation

Built on the core side using net messages, which is the approach suggested in the discussion.

packed_params is a flat sequence of parameters, each one a 32 bit hash of the parameter name, a type tag, a 16 bit length, then the value. The types that appear in game traffic are 0x02 for integers, 0x08 for floats and 0x0A for vectors. Parsing the parameters of the game's own messages leaves no remainder: 365 of them in August, and 1235 from 644 messages on 1.41.8.8.

Two seeds are in play, and both go through the SDK's own MurmurHash2LowerCase: sound event names hash with 0x53524332, parameter names with STRINGTOKEN_MURMURHASH_SEED. Nothing about hashing is reimplemented here.

SetParam replaces an earlier value for the same parameter rather than appending one, so a reused sound event does not grow its blob.

EmitSound is left alone, so no existing behaviour changes.

Verification

Rebased onto v1.0.376 and run again on game build 1.41.8.8, Linux dedicated server:

• css_smoke_test on a fresh server: 119 passed, 0 failed, 4 skipped, the same four that are skipped on main
• the hash this produces for a sound name is identical to the one the game puts in its own message for that name
• what goes out on the wire is what was set: every parameter with its type, a parameter set twice sent once with the later value, no blob when nothing was set
• 2500 emits, half of them deliberately abandoned to the finalizer: resident memory did not grow

Checked by ear in August and not repeated since: volume and pitch are audibly different across values, where the existing EmitSound path plays 1.0 and 0.05 identically; a sound placed in the world is heard from its direction and falls off with distance; Stop cuts a sound short. css_itest AudibleSoundTest plays the sweep for anyone who wants to hear it.

SoundEventTests.cs exercises the API and checks that the server survives it: handles, guids, every value type, the same parameter twice, emitting to one player, stopping, disposing twice. It knows nothing about how parameters are packed; the wire checks above come from a separate local plugin that hooks the message.

Builds on both platforms with no warnings in the new files: gcc 13 on Linux, and MSVC 19.44 through the same vsdevcmd and CMake steps CI uses on windows-latest. The Windows build was run on a server in August; after the rebase it was only compiled.

Not covered

CMsgSosSetSoundEventParams would let a playing sound be changed rather than only started and stopped, which is what a smooth fade needs. It reuses the same parameter blob and would be a small follow-up, left out here to keep this reviewable.

A sound name is resolved by the client, so a name that does not exist plays nothing and reports no error. The existing EmitSound behaves the same way. This is called out in the API documentation.

The discussion and the research behind it are @samyycX's, including the finding that the parameters are entirely net message based.

[roflmuffin]

I think this test file should have all of the implementation knowledge of how the parameters are packed removed, so it's just testing the API and that running the tests do not crash the server.

What might be useful is to create a test that emits a specific sound audible to all players using all of the available parameters. i.e. play the AK sound pitched down in a loop increasing in volume pitch and distance, and then a player can connect to the test server to verify the results manually (if needed) by running css_itest AudibleSoundTest (example name)

[makadore]

Done, and testing it turned up something worth having in the documentation.

The test file no longer knows anything about how parameters are packed. No hashes, no type tags, no unpacking, no message id, no hooks. It exercises the API and checks a server survives it: handles, guids, every value type, setting the same parameter twice, emitting to one player, stopping, disposing twice.

AudibleSoundTest plays a sound to everyone with volume, then pitch, then position swept, announcing each step in chat, so it can be checked by ear on its own with css_itest AudibleSoundTest.

Checking the sweep by ear is what caught the interesting part. Position appeared to do nothing, and I nearly wrote it up as delivered but inert, until I noticed I had been attaching the sound to the listener and then trying to move it away from them. SourceEntityIndex is what decides this, and it has three modes rather than two:

-1, the default	plays at each recipient, public.position is ignored
0	plays at public.position in the world
any entity index	attached to that entity and follows it

Zero is how the game emits placed sounds, which is visible in its own messages: they carry an entity index of 0 together with real map coordinates. With that, volume, pitch and position are all audible, including direction and falloff. That is now on SourceEntityIndex rather than left for the next person to work out.

The follow-up I mentioned, CMsgSosSetSoundEventParams for changing a sound while it plays, is ready whenever you want it. Say the word and I will open it separately rather than growing this one.

[makadore]

Rebased onto main (v1.0.376). The only conflict was the generated API.cs, which I regenerated with CodeGen.Natives.

Two things changed besides the rebase:

• The smoke suite from fix: for update 1.41.8.2 #1433 starts on an empty server, and two of the sound tests assumed a player was already there. They take a bot from CreateTestPlayerAsync now, like the game and ray trace tests do. AudibleSoundTest returns straight away when no human is connected, so it does not hold a smoke run for eleven seconds; with someone on the server css_itest AudibleSoundTest plays the sweep as before.
• The example attached the sound to the controller. The game's own messages name the pawn for everything a player emits, so the example and the note on SourceEntityIndex say that now.

On 1.41.8.8, Linux, css_smoke_test on a fresh server gives 119 passed, 0 failed, 4 skipped, the same four that are skipped on main. Builds clean with gcc 13 and MSVC 19.44.

I also had the runner problem backwards in the description. It printed nothing for me in August because I had copied the plugin without Spectre.Console.dll, not because of anything in the repo. With the whole output folder deployed it reports fine, and the description is corrected.

Unrelated to this PR, in case it is useful: on main EnsureNativeHandle_IsFreed_Vector3 fails for me from the second or third smoke run within one server session, and passes on a fresh server.