Refactor audio system to send collection IDs over the network

[sowelipililimute]

This is important groundwork for future features such as captioning, as a caption and other data can be associated with the collection prototype instead of passing extra data everywhere with the sound.

[PJB3005]

This is definitely going to need to be made backwards compatible with content if a full breaking change can be avoided.

[sowelipililimute]

the main pickle w/ backwards compatibility here is that GetAudio here is a public method that allows users to "resolve" a sound specifier. currently, it resolves into a ResPath modelled as a string, but the entire premise of this change is that we want to sometimes resolve it to a collection prototype ID and index in order to accomodate looking up other metadata from the collection. this necessitates a change in what exactly we're returning, which is backwards incompatible no matter how you cut it.

approaches I've considered:

• keep the string return type intact and encode the path or ID+index into it: whilst backwards compatible at the type level, changing from a ResPath-compatible string into a new encoding would almost definitely interfere with third-party code expecting to be able to pass this into a ResPath, and would leave no indication of where the bogus value is coming from in a debugging session. also, instant technical debt.
• try to build an entirely separate codepath for the new resolved type as a path or an ID+index. this kicks down the "resolving a sound is public API" can to everyone else, which turns a relatively small number of changes required from a breaking change into a much larger (from earlier attempts at this, I'd say around 400 changes needed in ss14 vs the 30 lines of the current content PR) effort to port from the old APIs to the slightly different but incompatible APIs, albeit an effort that can be delayed. also raises design concerns for other APIs involved; e.g. the animation sound track APIs. do we leave them on the old thing, or do we then build a new animation sound track type that's slightly incompatible with the previous one and raises the same concerns about the choice between an immediate but small porting effort or a massive but delayable porting effort, and kicks the can down to APIs that depend on it and so on and so forth.
• attempt to be as compatible with possible with current inputs and accept the L on breaking the return type: this is what I ended up going with, as it minimizes the amount of work needed for code that isn't using GetAudio directly (which is most of the code interfacing with the audio system) to zero, leaving the only porting effort required as "if you used GetAudio to get a resource path to play back at a later time for "collapsing RNG" reasons, change your intermediate variables from string to ResolvedSoundSpecifier, and if you really need to get the ResPath of a SoundSpecifier, there is a new GetAudioPath method for that."

i ended up going with the third one, as the first one was obviously untenable and the second one proved to produce too much code churn without any assurances that I caught everything.

[PJB3005]

You can keep the old method, mark it as [Obsolete], and replace it with a new method that does the same thing. The GetAudioPath name is really bad anyways...

[sowelipililimute]

okay, so you want me to go with the second option then? that is going to generate a Lot of code churn so i want to make sure you're fully aware of what that entails before i embark on that refactoring

[PJB3005]

Don't most of the modified APIs have pretty easy conversions to and from the new ResolvedSoundSpecifier? It shouldn't introduce that much code should it?

[sowelipililimute]

hacked in some more backwards compatibility, it compiles with current ss14 but still has breaking changes, including but not limited to:

• SharedAudioSystem has new abstract methods w/o implemereturn RandMan.Pick(soundCollection.PickFiles).ToString();ntations to be overridden by descendant classes
• AnimationPlayTrackSound's Resource field was changed to contain a ResolvedSoundSpecifier instead of a string
• AudioMessage's FileName field was changed to contain a ResolvedSoundSpecifier instead of a string

this also necessitates code churn in downstream code to reference the new ResolvedSound method instead of the GetSound method to actually make use of the new functionality, which is a lot more places in the content than the changes needed to accomodate breaking changes in the engine.

i really don't like where this approach is going code qualitywise (and in terms of porting effort), but if avoiding breaking changes is that important, then I will continue on this path

[sowelipililimute]

after some weeks to think about it, i wasn't particularly happy with what trying to force BC onto this fundamentally incompatible change was looking like, so I dropped that. trying to make it BC ended up spiraling the scope of the code in the toolbox too much in order to build a parallel code path working in ResolvedSoundSpecifiers for every API that dealt with the return value of GetAudio whether directly or indirectly and turned a small amount of required changes that needed to be handled immediately into a much larger pile of deprecation warnings that still needed to be handled immediately for captioning to be a thing. more work on all fronts for less guaranteed results.