Bro_Audio icon indicating copy to clipboard operation
Bro_Audio copied to clipboard

Update AudioEntity to be a ScriptableObject and have SoundID use that as a reference

Open Zallist opened this issue 2 months ago • 1 comments

This is a giant change to how BroAudio stores all of its data and it'll mean some kind of non-backwards compatible update for all existing projects, which should be automated by SoundIDUpgrader. Basically all SoundIDs need to be updated across the entire project, as well as the creation of scriptableobjects of every AudioEntity.

There's also some commits in here that handle automatic loading of addressable audioclips if they're not already loaded, since it makes more sense to load (& then unload after no longer used for {configurable number of seconds, default = 60s}) than to straight up error.

ISSUES RESOLVED

  • IDs potentially causing unwanted conflicts and needing resolution, and the general codebase around managing integer IDs
  • ID-Entity resolution, since the ID now contains the Entity it can just be directly pulled by BroAudio, allowing better non-playmode integration
  • There was hidden functionality inside the actual integer ID relating to AudioType, which is now just a raw property in the actual AudioEntity
  • All AudioClips managed by BroAudio were always loaded into memory at all times no matter if they were referenced by the current scene
  • All AudioClips ended up in builds regardless of actually being used, since they were all included in the Resources SoundManager
  • The explicit requirement that all entities had to be modified via the BroAudio library - This now makes it so the individual scriptableobjects can be managed externally, and developers can wrap additional functionality without library modification.
  • It's now possible to have an AudioEntity without an AudioAsset, allowing more flexibility for copying sounds to other projects and changing what they belong to
  • AudioEntities now allow much simpler version control conflict resolution, since you compare the individual entities and now an internal list
  • There's no "Temp" AudioAsset when dragging in new files, we can just create them all immediately and potentially allow moving stuff around after
  • Audio Entities can be loaded dynamically via the addressables system as a whole, allowing string-based keys for entities (useful for external integration with Yarn or other tools, where we have rare audio that we want to dynamically choose which to play)
  • The BroAudio Core Data no longer needs to exist, since audio assets don't need to be directly loaded at all times, the only thing left was a version number, which can just be stored as a plain string in /ProjectSettings/BroAudio/version (handled now by BroVersion.cs)

POTENTIAL UNWANTED CHANGES

  • It's no longer possible to "sort" the entities & assets in the library, since it's just in whatever order Unity returns it via AssetDatabase.FindAssets
  • Every AudioEntity now creates a ScriptableObject, which means potentially hundreds of new assets in each project (this not a performance issue for unity, just potential clutter)
  • The deletion of AssetFieldUsageFinder - Since an integer SoundID doesn't exist anymore, it allows something like the generic AssetUsageFinder tool to simply map up dependencies in future, since individual integers don't need to be parsed.
  • You can no longer call a generic BroAudio.ResetSequence() or BroAudio.ResetShuffle(), they're both absorbed into BroAudio.ResetMultiClipStrategy(SoundID), but we need the ID to be passed in since there's no global multi clip strategy object to interact with anymore
  • SoundID exposes _entity as an AudioEntity Entity instead of an IAudioEntity Entity
  • If someone was previously hardcoding the INTEGER IDs in for dynamic loading of assets, they need to swap out to a different key mechanism, but they can also just directly create a new SoundID by passing in the relevant AudioEntity in future.

STUFF TO BE CHECKED MORE THOROUGHLY

  • I'm not 100% sure if the demo assets are correct for a .unitypackage build, so that needs to be tested for the two methods of getting the demo sample (from .unitypackage and from upm git Samples screen)
  • The SoundIDUpgrader process could do with a more thorough test to make sure it's drilling through every possible asset properly and remapping the IDs to the entities correctly
  • Potentially some kind of blatant warning before ANY conversion is done to say "HEY, MAKE SURE ABSOLUTELY EVERYTHING IS BACKED UP / USING VERSION CONTROL" in case something goes wrong, since some developers somehow make games without version control

FURTHER NOTES

  • The SoundIDUpgrader is currently set to check if Version.Major < 3 and then warn the developer that they must do the potentially slow upgrade of all existing assets, if this is included in a 3.1 or 4.0 then this check needs to be updated to cater for said update - This is a big enough change to warrant a semantic major upgrade since it's non backwards compatible.
  • There's a lot of code for doing upgrades under the hood which potentially needs to be stripped out in later versions, it's all marked with [System.Obsolete]

Zallist avatar Nov 01 '25 12:11 Zallist

This pull request is now ready. Take notice of the STUFF TO BE CHECKED MORE THOROUGHLY and FURTHER NOTES after reviewing.

I'm also fine with this just not being merged, but it might be better for future changes to just take the plunge sooner rather than later, since this enables much easier upgrading of entities in the future.

Zallist avatar Nov 01 '25 21:11 Zallist