From 658709ebcec4a66745cfe8b32047ea20d0ef185d Mon Sep 17 00:00:00 2001
From: Storm Dragon <stormdragon2976@gmail.com>
Date: Sun, 2 Feb 2025 17:04:04 -0500
Subject: [PATCH] Random play functions for positional audio and positional
 falling audio.

---
 __init__.py | 59 +++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 59 insertions(+)

diff --git a/__init__.py b/__init__.py
index 5f3f778..9c2951b 100755
--- a/__init__.py
+++ b/__init__.py
@@ -369,6 +369,65 @@ def play_random(sounds, soundName, pause = False, interrupt = False):
     if pause == True:
         time.sleep(sounds[randomKey].get_length())
     
+def play_random_positional(sounds, soundName, playerX, objectX):
+    """Play a random sound with positional audio.
+    
+    Args:
+        sounds: Dictionary of sound objects
+        soundName: Base name of sound (e.g. 'falling_skull' will match 'falling_skull1', 'falling_skull2', etc.)
+        playerX: Player's x position for audio panning
+        objectX: Object's x position for audio panning
+    
+    Returns:
+        The sound channel object for updating position
+    """
+    keys = [k for k in sounds.keys() if k.startswith(soundName)]
+    if not keys:
+        return None
+    
+    randomKey = random.choice(keys)
+    volume, left, right = calculate_volume_and_pan(playerX, objectX)
+    if volume == 0:
+        return None
+        
+    channel = sounds[randomKey].play()
+    if channel:
+        channel.set_volume(volume * left, volume * right)
+    return channel
+
+def play_random_falling(sounds, soundName, playerX, objectX, startY, currentY=0, maxY=20):
+    """Play a random sound with positional audio that increases in volume as it 'falls'.
+    
+    Args:
+        sounds: Dictionary of sound objects
+        soundName: Base name of sound (e.g. 'falling_skull' will match 'falling_skull1', 'falling_skull2', etc.)
+        playerX: Player's x position for audio panning
+        objectX: Object's x position for audio panning
+        startY: Starting Y position (0-20, higher = quieter start)
+        currentY: Current Y position (0 = ground level)
+        maxY: Maximum Y value (default 20)
+    
+    Returns:
+        The sound channel object for updating position/volume
+    """
+    keys = [k for k in sounds.keys() if k.startswith(soundName)]
+    if not keys:
+        return None
+        
+    randomKey = random.choice(keys)
+    # Calculate horizontal positioning
+    volume, left, right = calculate_volume_and_pan(playerX, objectX)
+    if volume == 0:
+        return None
+        
+    # Calculate vertical fall volume multiplier (0 at maxY, 1 at y=0)
+    fallMultiplier = 1 - (currentY / maxY)
+    
+    channel = sounds[randomKey].play()
+    if channel:
+        channel.set_volume(volume * left * fallMultiplier, volume * right * fallMultiplier)
+    return channel
+
 def instructions():
     # Read in the instructions file
     try: