Merge branch 'dev-6.0'

README.md

@@ -1,5 +1,5 @@
 <p align="center"><img src="https://raw.githubusercontent.com/JujuAdams/vinyl/master/LOGO.png" style="display:block; margin:auto; width:300px"></p>
-<h1 align="center">Vinyl 6.0.6 (beta)</h1>
+<h1 align="center">Vinyl 6.0.7 (beta)</h1>
 
 <p align="center">Audio tooling for GameMaker 2024.4 (and later)</p>
 

scripts/VinylPlay/VinylPlay.gml

@@ -25,14 +25,14 @@ function VinylPlay(_pattern, _loop = undefined, _gain = 1, _pitch = 1, _duckerNa
 
     if (is_handle(_pattern))
     {
-        return struct_get_from_hash(_soundDict, int64(_pattern)).__Play(_loop, _gain, _pitch, _duckerName, _duckPrio);
+        return struct_get_from_hash(_soundDict, int64(_pattern)).__Play(undefined, _loop, _gain, _pitch, _duckerName, _duckPrio);
     }
     else if (is_string(_pattern))
     {
         var _patternStruct = _patternDict[$ _pattern];
         if (_patternStruct != undefined)
         {
-            return _patternStruct.__Play(_loop, _gain, _pitch, _duckerName, _duckPrio);
+            return _patternStruct.__Play(undefined, _loop, _gain, _pitch, _duckerName, _duckPrio);
         }
         else
         {

scripts/VinylPlayOn/VinylPlayOn.gml

@@ -0,0 +1,47 @@
+// Feather disable all
+
+/// Plays a sound or pattern. Sound playback works the same as native GameMaker functions. If you
+/// are playing a pattern, the exact playback behaviour will change depending on the type of
+/// pattern:
+/// 
+///   - Shuffle chooses a random sound from an array of sounds
+///   - Blend plays multiple sounds whose balance can be adjusted by setting the blend factor
+///   - Head-Loop-Tail plays a head, then a loop (until the end loop function is called), then a tail
+/// 
+/// This function returns a voice index which can be used with other Vinyl functions to adjust
+/// playback and trigger pattern behaviours where relevant.
+/// 
+/// @param emitter
+/// @param sound/pattern
+/// @param [loop]
+/// @param [gain=1]
+/// @param [pitch=1]
+/// @param [duckerName]
+/// @param [duckPriority=0]
+
+function VinylPlayOn(_emitter, _pattern, _loop = undefined, _gain = 1, _pitch = 1, _duckerName = undefined, _duckPrio = undefined)
+{
+    static _soundDict   = __VinylSystem().__soundDict;
+    static _patternDict = __VinylSystem().__patternDict;
+
+    if (is_handle(_pattern))
+    {
+        return struct_get_from_hash(_soundDict, int64(_pattern)).__Play(_emitter, _loop, _gain, _pitch, _duckerName, _duckPrio);
+    }
+    else if (is_string(_pattern))
+    {
+        var _patternStruct = _patternDict[$ _pattern];
+        if (_patternStruct != undefined)
+        {
+            return _patternStruct.__Play(_emitter, _loop, _gain, _pitch, _duckerName, _duckPrio);
+        }
+        else
+        {
+            __VinylError("Pattern \"", _pattern, "\" not found");
+        }
+    }
+    else
+    {
+        __VinylError("Datatype not supported (", typeof(_pattern), ")");
+    }
+}

scripts/VinylQueueCreate/VinylQueueCreate.gml

@@ -22,8 +22,9 @@
 /// @oaram behaviour
 /// @param loopQueue
 /// @param [gain=1]
+/// @param [emitter]
 
-function VinylQueueCreate(_behaviour, _loopQueue, _gain = 1)
+function VinylQueueCreate(_behaviour, _loopQueue, _gain = 1, _emitter = undefined)
 {
-    return (new __VinylClassVoiceQueue(_behaviour, _loopQueue, _gain)).__voiceReference;
+    return (new __VinylClassVoiceQueue(_behaviour, _loopQueue, _gain, _emitter)).__voiceReference;
 }

scripts/__VinylClassPatternBlend/__VinylClassPatternBlend.gml

@@ -36,9 +36,9 @@ function __VinylClassPatternBlend(_patternName, _soundArray, _loop, _gain, _anim
 
 
 
-    static __Play = function(_loopLocal, _gainLocal, _pitchLocal, _duckerNameLocal, _duckPrioLocal)
+    static __Play = function(_emitter, _loopLocal, _gainLocal, _pitchLocal, _duckerNameLocal, _duckPrioLocal)
     {
-        return (new __VinylClassVoiceBlend(self, _loopLocal, _gainLocal, _pitchLocal, _duckerNameLocal, _duckPrioLocal, __mixName)).__voiceReference;
+        return (new __VinylClassVoiceBlend(_emitter, self, _loopLocal, _gainLocal, _pitchLocal, _duckerNameLocal, _duckPrioLocal, __mixName)).__voiceReference;
     }
 
     static __UpdateSetup = function(_soundArray, _loop, _gain, _animCurve, _mixName, _duckerName, _duckPrio, _metadata)

scripts/__VinylClassPatternHLT/__VinylClassPatternHLT.gml

@@ -30,9 +30,9 @@ function __VinylClassPatternHLT(_patternName, _soundHead, _soundLoop, _soundTail
 
 
 
-    static __Play = function(_loopLocal__UNUSED, _gainLocal, _pitchLocal, _duckerNameLocal, _duckPrioLocal)
+    static __Play = function(_emitter, _loopLocal__UNUSED, _gainLocal, _pitchLocal, _duckerNameLocal, _duckPrioLocal)
     {
-        return (new __VinylClassVoiceHLT(self, _gainLocal, _pitchLocal, _duckerNameLocal, _duckPrioLocal)).__voiceReference;
+        return (new __VinylClassVoiceHLT(_emitter, self, _gainLocal, _pitchLocal, _duckerNameLocal, _duckPrioLocal)).__voiceReference;
     }
 
     static __UpdateSetup = function(_soundHead, _soundLoop, _soundTail, _gain, _mixName, _duckerName, _duckPrio, _metadata)

scripts/__VinylClassPatternShuffle/__VinylClassPatternShuffle.gml

@@ -57,7 +57,7 @@ function __VinylClassPatternShuffle(_patternName, _soundArray, _gainMin, _gainMa
 
 
 
-    static __Play = function(_loopLocal, _gainLocal, _pitchLocal, _duckerNameLocal, _duckPrioLocal)
+    static __Play = function(_emitter, _loopLocal, _gainLocal, _pitchLocal, _duckerNameLocal, _duckPrioLocal)
     {
         if (__soundCount < 1)
         {
@@ -145,7 +145,14 @@ function __VinylClassPatternShuffle(_patternName, _soundArray, _gainMin, _gainMa
             var _gainDuck     = 1;
         }
 
-        var _voice = audio_play_sound(_sound, 0, _loopFinal, _gainSound*_gainPattern*_gainLocal*_gainMix*_gainDuck/VINYL_MAX_VOICE_GAIN, 0, _pitchPattern*_pitchLocal);
+        if (_emitter == undefined)
+        {
+            var _voice = audio_play_sound(_sound, 0, _loopFinal, _gainSound*_gainPattern*_gainLocal*_gainMix*_gainDuck/VINYL_MAX_VOICE_GAIN, 0, _pitchPattern*_pitchLocal);
+        }
+        else
+        {
+            var _voice = audio_play_sound_on(_emitter, _sound, _loopFinal, 0, _gainSound*_gainPattern*_gainLocal*_gainMix*_gainDuck/VINYL_MAX_VOICE_GAIN, 0, _pitchPattern*_pitchLocal);
+        }
 
         //If we're in live edit mode then always create a struct representation
         if (VINYL_LIVE_EDIT || (_duckerNameFinal != undefined))

scripts/__VinylClassPatternSound/__VinylClassPatternSound.gml

@@ -29,7 +29,7 @@ function __VinylClassPatternSound(_sound, _gain, _pitch, _loop, _mixName, _ducke
 
 
 
-    static __Play = function(_loopLocal, _gainLocal, _pitchLocal, _duckerNameLocal, _duckPrioLocal)
+    static __Play = function(_emitter, _loopLocal, _gainLocal, _pitchLocal, _duckerNameLocal, _duckPrioLocal)
     {
         var _sound      = __sound;
         var _gainSound  = __gain;
@@ -75,7 +75,14 @@ function __VinylClassPatternSound(_sound, _gain, _pitch, _loop, _mixName, _ducke
             var _gainDuck   = 1;
         }
 
-        var _voice = audio_play_sound(_sound, 0, _loopFinal, _gainSound*_gainLocal*_gainMix*_gainDuck/VINYL_MAX_VOICE_GAIN, 0, _pitchSound*_pitchLocal);
+        if (_emitter == undefined)
+        {
+            var _voice = audio_play_sound(_sound, 0, _loopFinal, _gainSound*_gainLocal*_gainMix*_gainDuck/VINYL_MAX_VOICE_GAIN, 0, _pitchSound*_pitchLocal);
+        }
+        else
+        {
+            var _voice = audio_play_sound_on(_emitter, _sound, _loopFinal, 0, _gainSound*_gainLocal*_gainMix*_gainDuck/VINYL_MAX_VOICE_GAIN, 0, _pitchSound*_pitchLocal);
+        }
 
         //If we're in live edit mode then always create a struct representation
         if (VINYL_LIVE_EDIT || (_duckerNameFinal != undefined))

scripts/__VinylClassVoiceBlend/__VinylClassVoiceBlend.gml

@@ -1,5 +1,6 @@
 // Feather disable all
 
+/// @param emitter
 /// @param pattern
 /// @param loopLocal
 /// @param gainLocal
@@ -8,7 +9,7 @@
 /// @param duckPrioLocal
 /// @param mixName
 
-function __VinylClassVoiceBlend(_pattern, _loopLocal, _gainLocal, _pitchLocal, _duckerNameLocal, _duckPrioLocal, _mixName) constructor
+function __VinylClassVoiceBlend(_emitter, _pattern, _loopLocal, _gainLocal, _pitchLocal, _duckerNameLocal, _duckPrioLocal, _mixName) constructor
 {
     static _soundDict        = __VinylSystem().__soundDict;
     static _mixDict          = __VinylSystem().__mixDict;
@@ -19,6 +20,7 @@ function __VinylClassVoiceBlend(_pattern, _loopLocal, _gainLocal, _pitchLocal, _
 
     __inUpdateArray = false;
 
+    __emitter         = _emitter;
     __pattern         = _pattern;
     __gainLocal       = _gainLocal;
     __pitchLocal      = _pitchLocal;
@@ -103,7 +105,7 @@ function __VinylClassVoiceBlend(_pattern, _loopLocal, _gainLocal, _pitchLocal, _
         var _i = 0;
         repeat(__voiceCount)
         {
-            __voiceArray[_i] = audio_play_sound(_soundArray[_i], 0, _loopFinal, __gainArray[_i]*_gainShared, 0, __pitchArray[_i]*_pitchShared);
+            __voiceArray[_i] = __PlaySound(_soundArray[_i], _loopFinal, __gainArray[_i]*_gainShared, __pitchArray[_i]*_pitchShared);
             ++_i;
         }
 
@@ -128,6 +130,18 @@ function __VinylClassVoiceBlend(_pattern, _loopLocal, _gainLocal, _pitchLocal, _
 
 
 
+    static __PlaySound = function(_sound, _loop, _gain, _pitch)
+    {
+        if (__emitter == undefined)
+        {
+            return audio_play_sound(_sound, 0, _loop, _gain, 0, _pitch);
+        }
+        else
+        {
+            return audio_play_sound_on(__emitter, _sound, _loop, 0, _gain, 0, _pitch);
+        }
+    }
+
     static __Update = function(_delta)
     {
         var _changed = false;
@@ -434,7 +448,7 @@ function __VinylClassVoiceBlend(_pattern, _loopLocal, _gainLocal, _pitchLocal, _
                 var _i = 0;
                 repeat(__voiceCount)
                 {
-                    __voiceArray[_i] = audio_play_sound(_soundArray[_i], 0, _loop, _gainShared*__gainArray[_i]/VINYL_MAX_VOICE_GAIN, 0, _pitchShared*__pitchArray[_i]);
+                    __voiceArray[_i] = __PlaySound(_soundArray[_i], _loop, _gainShared*__gainArray[_i]/VINYL_MAX_VOICE_GAIN, _pitchShared*__pitchArray[_i]);
                     ++_i;
                 }
 

scripts/__VinylClassVoiceHLT/__VinylClassVoiceHLT.gml

@@ -1,18 +1,20 @@
 // Feather disable all
 
+/// @param emitter
 /// @param pattern
 /// @param gainLocal
 /// @param pitchLocal
 /// @param duckerNameLocal
 /// @param duckPrioLocal
 
-function __VinylClassVoiceHLT(_pattern, _gainLocal, _pitchLocal, _duckerNameLocal, _duckPrioLocal) constructor
+function __VinylClassVoiceHLT(_emitter, _pattern, _gainLocal, _pitchLocal, _duckerNameLocal, _duckPrioLocal) constructor
 {
     static _mixDict          = __VinylSystem().__mixDict;
     static _voiceToStructMap = __VinylSystem().__voiceToStructMap;
     static _voiceUpdateArray = __VinylSystem().__voiceUpdateArray;
     static _toUpdateArray    = __VinylSystem().__toUpdateArray;
 
+    __emitter    = _emitter;
     __pattern    = _pattern;
     __gainLocal  = _gainLocal;
     __pitchLocal = _pitchLocal;
@@ -79,7 +81,7 @@ function __VinylClassVoiceHLT(_pattern, _gainLocal, _pitchLocal, _duckerNameLoca
         __gainSound  = __VinylSoundGetGain(_soundHead);
         __pitchSound = __VinylSoundGetPitch(_soundHead);
 
-        __voiceCurrent = audio_play_sound(_soundHead, 0, false, __VINYL_VOICE_GAIN_SxPxLxMxD/VINYL_MAX_VOICE_GAIN, 0, __VINYL_VOICE_PITCH_SxL);
+        __voiceCurrent = __PlaySound(_soundHead, false, __VINYL_VOICE_GAIN_SxPxLxMxD/VINYL_MAX_VOICE_GAIN, __VINYL_VOICE_PITCH_SxL);
         __state = __VINYL_HLT_STATE.__HEAD;
     }
     else
@@ -90,7 +92,7 @@ function __VinylClassVoiceHLT(_pattern, _gainLocal, _pitchLocal, _duckerNameLoca
             __gainSound  = __VinylSoundGetGain(_soundLoop);
             __pitchSound = __VinylSoundGetPitch(_soundLoop);
 
-            __voiceCurrent = audio_play_sound(_soundLoop, 0, true, __VINYL_VOICE_GAIN_SxPxLxMxD/VINYL_MAX_VOICE_GAIN, 0, __VINYL_VOICE_PITCH_SxL);
+            __voiceCurrent = __PlaySound(_soundLoop, true, __VINYL_VOICE_GAIN_SxPxLxMxD/VINYL_MAX_VOICE_GAIN, __VINYL_VOICE_PITCH_SxL);
             __state = __VINYL_HLT_STATE.__LOOP;
         }
         else
@@ -103,7 +105,7 @@ function __VinylClassVoiceHLT(_pattern, _gainLocal, _pitchLocal, _duckerNameLoca
                 __gainSound  = __VinylSoundGetGain(_soundTail);
                 __pitchSound = __VinylSoundGetPitch(_soundTail);
 
-                __voiceCurrent = audio_play_sound(_soundTail, 0, false, __VINYL_VOICE_GAIN_SxPxLxMxD/VINYL_MAX_VOICE_GAIN, 0, __VINYL_VOICE_PITCH_SxL);
+                __voiceCurrent = __PlaySound(_soundTail, false, __VINYL_VOICE_GAIN_SxPxLxMxD/VINYL_MAX_VOICE_GAIN, __VINYL_VOICE_PITCH_SxL);
             }
             else
             {
@@ -133,6 +135,18 @@ function __VinylClassVoiceHLT(_pattern, _gainLocal, _pitchLocal, _duckerNameLoca
 
 
 
+    static __PlaySound = function(_sound, _loop, _gain, _pitch)
+    {
+        if (__emitter == undefined)
+        {
+            return audio_play_sound(_sound, 0, _loop, _gain, 0, _pitch);
+        }
+        else
+        {
+            return audio_play_sound_on(__emitter, _sound, _loop, 0, _gain, 0, _pitch);
+        }
+    }
+
     static __Update = function(_delta)
     {
         var _changed = false;
@@ -168,7 +182,7 @@ function __VinylClassVoiceHLT(_pattern, _gainLocal, _pitchLocal, _duckerNameLoca
                         __gainSound  = __VinylSoundGetGain(_pattern.__soundLoop);
                         __pitchSound = __VinylSoundGetPitch(_pattern.__soundLoop);
 
-                        __voiceCurrent = audio_play_sound(_pattern.__soundLoop, 0, true, __VINYL_VOICE_GAIN_SxPxLxMxD/VINYL_MAX_VOICE_GAIN, 0, __VINYL_VOICE_PITCH_SxL);
+                        __voiceCurrent = __PlaySound(_pattern.__soundLoop, true, __VINYL_VOICE_GAIN_SxPxLxMxD/VINYL_MAX_VOICE_GAIN, __VINYL_VOICE_PITCH_SxL);
                         __state = __VINYL_HLT_STATE.__LOOP;
                     }
                     else
@@ -180,7 +194,7 @@ function __VinylClassVoiceHLT(_pattern, _gainLocal, _pitchLocal, _duckerNameLoca
                             __gainSound  = __VinylSoundGetGain(_pattern.__soundTail);
                             __pitchSound = __VinylSoundGetPitch(_pattern.__soundTail);
 
-                            __voiceCurrent = audio_play_sound(_pattern.__soundTail, 0, false, __VINYL_VOICE_GAIN_SxPxLxMxD/VINYL_MAX_VOICE_GAIN, 0, __VINYL_VOICE_PITCH_SxL);
+                            __voiceCurrent = __PlaySound(_pattern.__soundTail, false, __VINYL_VOICE_GAIN_SxPxLxMxD/VINYL_MAX_VOICE_GAIN, __VINYL_VOICE_PITCH_SxL);
                         }
                         else
                         {
@@ -198,7 +212,7 @@ function __VinylClassVoiceHLT(_pattern, _gainLocal, _pitchLocal, _duckerNameLoca
                         __gainSound  = __VinylSoundGetGain(_pattern.__soundTail);
                         __pitchSound = __VinylSoundGetPitch(_pattern.__soundTail);
 
-                        __voiceCurrent = audio_play_sound(_pattern.__soundTail, 0, false, __VINYL_VOICE_GAIN_SxPxLxMxD/VINYL_MAX_VOICE_GAIN, 0, __VINYL_VOICE_PITCH_SxL);
+                        __voiceCurrent = __PlaySound(_pattern.__soundTail, false, __VINYL_VOICE_GAIN_SxPxLxMxD/VINYL_MAX_VOICE_GAIN, __VINYL_VOICE_PITCH_SxL);
                     }
                     else
                     {
@@ -326,7 +340,7 @@ function __VinylClassVoiceHLT(_pattern, _gainLocal, _pitchLocal, _duckerNameLoca
                 if (_pattern.__changedHead)
                 {
                     audio_stop_sound(__voiceCurrent);
-                    __voiceCurrent = audio_play_sound(_pattern.__soundHead, 0, false, __VINYL_VOICE_GAIN_SxPxLxMxD/VINYL_MAX_VOICE_GAIN, 0, __VINYL_VOICE_PITCH_SxL);
+                    __voiceCurrent = __PlaySound(_pattern.__soundHead, false, __VINYL_VOICE_GAIN_SxPxLxMxD/VINYL_MAX_VOICE_GAIN, __VINYL_VOICE_PITCH_SxL);
                 }
                 else
                 {
@@ -343,7 +357,7 @@ function __VinylClassVoiceHLT(_pattern, _gainLocal, _pitchLocal, _duckerNameLoca
                 {
                     var _loop = audio_sound_get_loop(__voiceCurrent);
                     audio_stop_sound(__voiceCurrent);
-                    __voiceCurrent = audio_play_sound(_pattern.__soundLoop, 0, _loop, __VINYL_VOICE_GAIN_SxPxLxMxD/VINYL_MAX_VOICE_GAIN, 0, __VINYL_VOICE_PITCH_SxL);
+                    __voiceCurrent = __PlaySound(_pattern.__soundLoop, _loop, __VINYL_VOICE_GAIN_SxPxLxMxD/VINYL_MAX_VOICE_GAIN, __VINYL_VOICE_PITCH_SxL);
                 }
                 else
                 {
@@ -359,7 +373,7 @@ function __VinylClassVoiceHLT(_pattern, _gainLocal, _pitchLocal, _duckerNameLoca
                 if (_pattern.__changedTail)
                 {
                     audio_stop_sound(__voiceCurrent);
-                    __voiceCurrent = audio_play_sound(_pattern.__soundTail, 0, false, __VINYL_VOICE_GAIN_SxPxLxMxD/VINYL_MAX_VOICE_GAIN, 0, __VINYL_VOICE_PITCH_SxL);
+                    __voiceCurrent = __PlaySound(_pattern.__soundTail, false, __VINYL_VOICE_GAIN_SxPxLxMxD/VINYL_MAX_VOICE_GAIN, __VINYL_VOICE_PITCH_SxL);
                 }
                 else
                 {