Merge branch 'chore/prerelease'

README.md

@@ -1,6 +1,6 @@
 # audioware
 
-![Cyberpunk 2077 version compatibility](https://img.shields.io/badge/Cyberpunk_2077-patch_2.12a-yellow) [![Nexus](https://img.shields.io/badge/Nexus-Audioware-orange)](https://www.nexusmods.com/cyberpunk2077/mods/12001) [![download](https://img.shields.io/github/v/release/cyb3rpsych0s1s/audioware?display_name=tag&label=Download)](https://github.com/cyb3rpsych0s1s/audioware/releases/latest) [![build](https://github.com/cyb3rpsych0s1s/audioware/actions/workflows/quality.yml/badge.svg)](https://github.com/cyb3rpsych0s1s/audioware/actions) [![docs](https://github.com/cyb3rpsych0s1s/audioware/actions/workflows/pages.yml/badge.svg)][BOOK]
+![Cyberpunk 2077 version compatibility](https://img.shields.io/badge/Cyberpunk_2077-patch_2.2-yellow) [![Nexus](https://img.shields.io/badge/Nexus-Audioware-orange)](https://www.nexusmods.com/cyberpunk2077/mods/12001) [![download](https://img.shields.io/github/v/release/cyb3rpsych0s1s/audioware?display_name=tag&label=Download)](https://github.com/cyb3rpsych0s1s/audioware/releases/latest) [![build](https://github.com/cyb3rpsych0s1s/audioware/actions/workflows/quality.yml/badge.svg)](https://github.com/cyb3rpsych0s1s/audioware/actions) [![docs](https://github.com/cyb3rpsych0s1s/audioware/actions/workflows/pages.yml/badge.svg)][BOOK]
 
 ![Cover image](https://cyb3rpsych0s1s.github.io/audioware/assets/cover.webp)
 

book/pages/AUDIO_SETTINGS_EXT.md

@@ -4,41 +4,14 @@ Earlier we saw that [settings](./SETTINGS.md) can be defined in [manifest](./MAN
 but these settings can also be specified in scripts:
 
 ```swift
-// builder is a mutable ref
-let builder: ref<AudioSettingsExtBuilder> = AudioSettingsExtBuilder.Create();
-// it supports the same settings as definable in manifest, except start_position
-builder.SetFadeInTween(ElasticTween.ImmediateIn(5.0, 0.25));
-builder.SetPanning(0.3);
-builder.SetPlaybackRate(1.1);
-builder.SetVolume(0.9);
-// once built it returns an immutable ref with different type
-let settings: ref<AudioSettingsExt> = builder.Build();
+let ext = new AudioSettingsExt();
+ext.fadeIn = LinearTween.Immediate(2.0);
 
 GameInstance
 .GetAudioSystemExt(game)
 .Play(n"still_dre", GetPlayer(game).GetEntityID(), n"V", scnDialogLineType.Regular, settings);
 ```
 
-~~~admonish hint collapsible=true, title='Alternate builder shorter syntax <span style="color: hotpink; font-size: 0.75em">click to open</span>'
-The `AudioSettingsExtBuilder` also accepts a shorter syntax:
-```swift
-GameInstance
-    .GetAudioSystemExt(game)
-    .Play(
-        n"still_dre",
-        GetPlayer(game).GetEntityID(),
-        n"V",
-        scnDialogLineType.Regular, 
-        AudioSettingsExtBuilder.Create()
-            .WithFadeInTween(ElasticTween.ImmediateIn(5.0, 0.25))
-            .WithPanning(0.3)
-            .WithPlaybackRate(1.1)
-            .WithVolume(0.9)
-            .Build()
-    );
-```
-~~~
-
 ```admonish youtube title="YouTube demo"
 <iframe width="100%" height="420" src="https://www.youtube.com/embed/1JWgtmSyGg8?si=-t9C7K4KkJuySHpW" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen></iframe>
 ```

book/pages/AUDIO_SYSTEM.md

@@ -16,5 +16,10 @@ Currently all these methods are supported:
 - [Play](https://nativedb.red4ext.com/gameGameAudioSystem#Play)
 - [Stop](https://nativedb.red4ext.com/gameGameAudioSystem#Stop)
 - [Switch](https://nativedb.red4ext.com/gameGameAudioSystem#Switch)
-- [PlayOnEmitter](https://nativedb.red4ext.com/gameGameAudioSystem#PlayOnEmitter)
 - [Parameter](https://nativedb.red4ext.com/gameGameAudioSystem#Parameter): see [Parameters](./PARAMETERS.md)
+
+```admonish warning title="Breaking changes in 1.3.0+"
+Support for [PlayOnEmitter](https://nativedb.red4ext.com/gameGameAudioSystem#PlayOnEmitter) since there's no way to associate a `tag_name` when called from vanilla.
+
+Likewise, the methods above can only be used to play sounds on tracks, not on spatial emitters.
+```

book/pages/INTEGRATION.md

@@ -32,6 +32,12 @@ As previously stated, audio will dynamically have its frequencies adjusted by [U
 
 This is currently not implemented for cars.
 
+## 🏊‍♂️ Dynamic time dilation
+
+Since `1.3.0`, audio will dynamically have its pitch adjusted whenever time dilation changes (e.g. when using Sandevistan).
+
+You can also opt-out on a per-sound basis.
+
 ## 🧹 Clean game sessions
 
 Spatial scene along with its emitters, every track and currently playing sounds will be completely stopped and reset on every save load.

book/pages/SPATIALIZATION.md

@@ -5,11 +5,10 @@ Thanks to [kira][kira] Audioware supports audio spatialization, which means audi
 ## Registration
 
 Audio emitter(s) must be registered before you can emit audio from them, but they are automatically cleaned up whenever emitter despawns or dies.
+You must provide a `tag_name` which Audioware uses to track emitters internally.
 
 ```swift
-if !GameInstance.GetAudioSystemExt(game).IsRegisteredEmitter(emitterID) {
-    GameInstance.GetAudioSystemExt(game).RegisterEmitter(emitterID);
-}
+GameInstance.GetAudioSystemExt(game).RegisterEmitter(emitterID, n"MyMod");
 ```
 
 ```admonish warning title="Types"
@@ -21,34 +20,9 @@ You don't need to manually unregister your audio emitter(s), even if you can do
 Audioware does it automatically whenever emitter despawns or dies. Dying emitter <span style="color: hotpink">still</span> emit.
 ~~~
 
-<details><summary>How to easily e.g. fade a sound out whenever an Entity is dying <span style="color: hotpink; font-size: 0.75em">click to open</span></summary>
-
-```swift
-/// for Humans
-@wrapMethod(NPCDeathListener)
-protected cb func OnStatPoolCustomLimitReached(value: Float) -> Bool {
-    let wasAlive = !this.npc.m_wasJustKilledOrDefeated;
-    let out = wrappedMethod(value);
-    if wasAlive && this.npc.m_wasJustKilledOrDefeated {
-        let id = this.npc.GetEntityID();
-        let name = this.npc.GetDisplayName(); // or whatever you named it
-        // fades for 2sec, with intensity 0.2
-        let fadeOut = LinearTween.ImmediateOut(2.0, 0.2);
-
-        GameInstance
-            .GetAudioSystemExt(this.npc.GetGame())
-            .Stop(n"my_custom_audio", id, name, fadeOut);
-    }
-    return out;
-}
-/// for Robots
-@wrapMethod(NPCDeathListener)
-protected cb func OnStatPoolMinValueReached(value: Float) -> Bool { ... }
-```
-
-> A courtesy of [Demon9ne](https://next.nexusmods.com/profile/Demon9ne), thanks for the snippet!
-
-</details>
+~~~admonish hint title="Dying emitter (1.3.0+)"
+You don't need to manually fade out or stop your audio on dying emitter(s), even if you can do so: Audioware does it automatically whenever emitter dies (stop) or gets incapacitated / defeated (fade-out).
+~~~
 
 ```admonish hint
 V cannot be an audio emitter because (s)he is the listener.
@@ -60,10 +34,10 @@ Then, simply use the `OnEmitter` variants of the methods:
 
 ```swift
 // ⚠️ emitterID and emitterCName must be both valid and non-default
-GameInstance.GetAudioSystemExt(game).PlayOnEmitter(n"my_custom_audio", emitterID, emitterCName);
+GameInstance.GetAudioSystemExt(game).PlayOnEmitter(n"my_custom_audio", emitterID, n"MyMod");
 
 // if should stop at some point...
-GameInstance.GetAudioSystemExt(game).StopOnEmitter(n"my_custom_audio", emitterID, emitterCName);
+GameInstance.GetAudioSystemExt(game).StopOnEmitter(n"my_custom_audio", emitterID, n"MyMod");
 ```
 
 ```admonish youtube title="YouTube demo"
@@ -103,17 +77,17 @@ public class AutoEmittersSystem extends ScriptableSystem {
         tween.startTime = RandRangeF(1.0, 3.0);
         tween.duration = RandRangeF(3.0, 4.5);
         let emitterID: EntityID;
-        let emitterCName: CName = n"DummyTest";
+        let tagName: CName = n"MyMod";
 
         let game = this.GetGameInstance();
         // get entity V currently looks at (crosshair)
         let target = GameInstance.GetTargetingSystem(game).GetLookAtObject(GetPlayer(game));
         if !IsDefined(target) { return; }
         emitterID = target.GetEntityID();
-        if !GameInstance.GetAudioSystemExt(game).IsRegisteredEmitter(emitterID) {
-            GameInstance.GetAudioSystemExt(game).RegisterEmitter(emitterID);
+        if !GameInstance.GetAudioSystemExt(game).IsRegisteredEmitter(emitterID, tagName) {
+            GameInstance.GetAudioSystemExt(game).RegisterEmitter(emitterID, tagName);
         }
-        GameInstance.GetAudioSystemExt(game).PlayOnEmitter(eventName, emitterID, emitterCName);
+        GameInstance.GetAudioSystemExt(game).PlayOnEmitter(eventName, emitterID, tagName);
     }
 }
 ```

crates/audioware/src/abi/mod.rs

@@ -302,7 +302,7 @@ impl SceneLifecycle for AudioSystemExt {
             }
         };
         let emitter_settings = match TargetFootprint::try_new(emitter_settings, *entity_id) {
-            Ok(emitter_settings) => Some(emitter_settings),
+            Ok(emitter_settings) => emitter_settings,
             Err(e) => {
                 warns!(
                     "{}",

crates/audioware/src/abi/types.rs

@@ -395,13 +395,9 @@ impl TargetFootprint {
     pub fn try_new(
         value: Ref<super::EmitterSettings>,
         entity_id: EntityId,
-    ) -> Result<Self, Vec<ValidationError>> {
+    ) -> Result<Option<Self>, Vec<ValidationError>> {
         use crate::engine::ToDistances;
-        let value = value.into_settings_ext(entity_id.to_distances());
-        if value.is_none() {
-            return Err(vec![ValidationError::InvalidEmitterSettings]);
-        }
-        Ok(Self(value.unwrap()))
+        Ok(value.into_settings_ext(entity_id.to_distances()).map(Self))
     }
 }
 

crates/audioware/src/error.rs

@@ -64,8 +64,6 @@ pub enum ValidationError {
     InvalidTagName,
     #[snafu(display("entity_id cannot be undefined or V."))]
     InvalidTargetId,
-    #[snafu(display("invalid emitter_settings."))]
-    InvalidEmitterSettings,
 }
 
 impl From<InternalError> for Error {

crates/audioware/src/hooks/mod.rs

@@ -10,12 +10,14 @@ mod time_system;
 mod events;
 
 pub fn attach(env: &SdkEnv) {
-    save_handling_controller::attach_hook(env);
     audio_system::attach_hooks(env);
     entity::attach_hook(env);
     time_dilatable::attach_hooks(env);
     time_system::attach_hooks(env);
 
+    #[cfg(debug_assertions)]
+    save_handling_controller::attach_hook(env);
+
     #[cfg(feature = "research")]
     {
         // events::audio::attach_hook(env); // 🌊