@musashishao/agent-kit 1.9.0 → 1.9.1

package/.agent/skills/game-development/game-audio-advanced/SKILL.md

@@ -0,0 +1,646 @@
+---
+name: game-audio-advanced
+description: Advanced game audio systems. Spatial audio, music systems, sound pooling, FMOD/Wwise basics, footstep systems.
+allowed-tools: Read, Write, Edit, Bash, Grep, WebSearch
+---
+
+# Advanced Game Audio Skill
+
+> Create immersive audio experiences for games.
+
+---
+
+## When to Use
+
+- Building audio manager systems
+- Implementing spatial 3D audio
+- Creating adaptive music
+- Setting up sound pooling
+- Designing footstep systems
+
+---
+
+## Audio Manager
+
+### Singleton Pattern
+
+```csharp
+public class AudioManager : MonoBehaviour
+{
+    public static AudioManager Instance { get; private set; }
+    
+    [Header("Mixers")]
+    [SerializeField] private AudioMixerGroup masterGroup;
+    [SerializeField] private AudioMixerGroup musicGroup;
+    [SerializeField] private AudioMixerGroup sfxGroup;
+    [SerializeField] private AudioMixerGroup voiceGroup;
+    
+    [Header("Sources")]
+    [SerializeField] private AudioSource musicSource;
+    [SerializeField] private AudioSource ambienceSource;
+    [SerializeField] private int sfxPoolSize = 20;
+    
+    private List<AudioSource> _sfxPool = new();
+    private Dictionary<string, AudioClip> _clipCache = new();
+    
+    void Awake()
+    {
+        if (Instance != null)
+        {
+            Destroy(gameObject);
+            return;
+        }
+        Instance = this;
+        DontDestroyOnLoad(gameObject);
+        
+        InitializeSFXPool();
+    }
+    
+    private void InitializeSFXPool()
+    {
+        for (int i = 0; i < sfxPoolSize; i++)
+        {
+            var go = new GameObject($"SFX_Source_{i}");
+            go.transform.SetParent(transform);
+            
+            var source = go.AddComponent<AudioSource>();
+            source.outputAudioMixerGroup = sfxGroup;
+            source.playOnAwake = false;
+            
+            _sfxPool.Add(source);
+        }
+    }
+    
+    #region SFX
+    
+    public void PlaySFX(AudioClip clip, float volume = 1f)
+    {
+        if (clip == null) return;
+        
+        var source = GetAvailableSource();
+        if (source != null)
+        {
+            source.clip = clip;
+            source.volume = volume;
+            source.spatialBlend = 0f; // 2D
+            source.Play();
+        }
+    }
+    
+    public void PlaySFX(string clipPath, float volume = 1f)
+    {
+        var clip = LoadClip(clipPath);
+        PlaySFX(clip, volume);
+    }
+    
+    public void PlaySFXAtPosition(AudioClip clip, Vector3 position, float volume = 1f)
+    {
+        if (clip == null) return;
+        
+        var source = GetAvailableSource();
+        if (source != null)
+        {
+            source.transform.position = position;
+            source.clip = clip;
+            source.volume = volume;
+            source.spatialBlend = 1f; // 3D
+            source.Play();
+        }
+    }
+    
+    public AudioSource PlayLoopingAtPosition(AudioClip clip, Vector3 position, float volume = 1f)
+    {
+        var source = GetAvailableSource();
+        if (source != null)
+        {
+            source.transform.position = position;
+            source.clip = clip;
+            source.volume = volume;
+            source.spatialBlend = 1f;
+            source.loop = true;
+            source.Play();
+        }
+        return source;
+    }
+    
+    private AudioSource GetAvailableSource()
+    {
+        foreach (var source in _sfxPool)
+        {
+            if (!source.isPlaying)
+            {
+                source.loop = false;
+                return source;
+            }
+        }
+        
+        // All busy - return oldest
+        Debug.LogWarning("SFX pool exhausted!");
+        return _sfxPool[0];
+    }
+    
+    #endregion
+    
+    #region Music
+    
+    public void PlayMusic(AudioClip clip, float fadeDuration = 1f)
+    {
+        StartCoroutine(CrossfadeMusic(clip, fadeDuration));
+    }
+    
+    private IEnumerator CrossfadeMusic(AudioClip newClip, float duration)
+    {
+        float startVolume = musicSource.volume;
+        
+        // Fade out
+        float elapsed = 0f;
+        while (elapsed < duration / 2f)
+        {
+            elapsed += Time.deltaTime;
+            musicSource.volume = Mathf.Lerp(startVolume, 0f, elapsed / (duration / 2f));
+            yield return null;
+        }
+        
+        // Switch clip
+        musicSource.clip = newClip;
+        musicSource.Play();
+        
+        // Fade in
+        elapsed = 0f;
+        while (elapsed < duration / 2f)
+        {
+            elapsed += Time.deltaTime;
+            musicSource.volume = Mathf.Lerp(0f, startVolume, elapsed / (duration / 2f));
+            yield return null;
+        }
+    }
+    
+    public void StopMusic(float fadeDuration = 1f)
+    {
+        StartCoroutine(FadeOutMusic(fadeDuration));
+    }
+    
+    private IEnumerator FadeOutMusic(float duration)
+    {
+        float startVolume = musicSource.volume;
+        float elapsed = 0f;
+        
+        while (elapsed < duration)
+        {
+            elapsed += Time.deltaTime;
+            musicSource.volume = Mathf.Lerp(startVolume, 0f, elapsed / duration);
+            yield return null;
+        }
+        
+        musicSource.Stop();
+    }
+    
+    #endregion
+    
+    #region Volume Control
+    
+    public void SetMasterVolume(float volume)
+    {
+        SetMixerVolume("MasterVolume", volume);
+    }
+    
+    public void SetMusicVolume(float volume)
+    {
+        SetMixerVolume("MusicVolume", volume);
+    }
+    
+    public void SetSFXVolume(float volume)
+    {
+        SetMixerVolume("SFXVolume", volume);
+    }
+    
+    private void SetMixerVolume(string parameter, float linearVolume)
+    {
+        // Convert linear (0-1) to dB
+        float dB = linearVolume > 0.001f 
+            ? Mathf.Log10(linearVolume) * 20f 
+            : -80f;
+        
+        masterGroup.audioMixer.SetFloat(parameter, dB);
+    }
+    
+    #endregion
+    
+    private AudioClip LoadClip(string path)
+    {
+        if (_clipCache.TryGetValue(path, out var cached))
+        {
+            return cached;
+        }
+        
+        var clip = Resources.Load<AudioClip>(path);
+        if (clip != null)
+        {
+            _clipCache[path] = clip;
+        }
+        return clip;
+    }
+}
+```
+
+---
+
+## Adaptive Music System
+
+```csharp
+public class AdaptiveMusicManager : MonoBehaviour
+{
+    [System.Serializable]
+    public class MusicLayer
+    {
+        public string Name;
+        public AudioClip Clip;
+        public AudioSource Source;
+        [Range(0, 1)] public float TargetVolume = 1f;
+        public float FadeSpeed = 1f;
+    }
+    
+    [SerializeField] private MusicLayer[] layers;
+    [SerializeField] private float bpm = 120f;
+    
+    private float _beatDuration;
+    private float _nextBeatTime;
+    
+    // Music states
+    public enum MusicState { Exploration, Combat, Danger, Boss }
+    private MusicState _currentState = MusicState.Exploration;
+    
+    void Start()
+    {
+        _beatDuration = 60f / bpm;
+        InitializeLayers();
+        SyncAllLayers();
+    }
+    
+    private void InitializeLayers()
+    {
+        foreach (var layer in layers)
+        {
+            layer.Source.clip = layer.Clip;
+            layer.Source.loop = true;
+            layer.Source.volume = 0f;
+            layer.Source.Play();
+        }
+        
+        // Start with exploration layers
+        SetState(MusicState.Exploration);
+    }
+    
+    void Update()
+    {
+        // Smooth volume transitions
+        foreach (var layer in layers)
+        {
+            layer.Source.volume = Mathf.MoveTowards(
+                layer.Source.volume,
+                layer.TargetVolume,
+                layer.FadeSpeed * Time.deltaTime
+            );
+        }
+        
+        // Keep layers in sync
+        if (Time.time > _nextBeatTime)
+        {
+            _nextBeatTime = Time.time + _beatDuration;
+            OnBeat();
+        }
+    }
+    
+    private void OnBeat()
+    {
+        // Could trigger beat-synced events
+    }
+    
+    public void SetState(MusicState newState)
+    {
+        _currentState = newState;
+        UpdateLayerVolumes();
+    }
+    
+    private void UpdateLayerVolumes()
+    {
+        switch (_currentState)
+        {
+            case MusicState.Exploration:
+                SetLayerVolume("Base", 1f);
+                SetLayerVolume("Melody", 0.5f);
+                SetLayerVolume("Drums", 0f);
+                SetLayerVolume("Intensity", 0f);
+                break;
+                
+            case MusicState.Danger:
+                SetLayerVolume("Base", 1f);
+                SetLayerVolume("Melody", 0.3f);
+                SetLayerVolume("Drums", 0.5f);
+                SetLayerVolume("Intensity", 0.3f);
+                break;
+                
+            case MusicState.Combat:
+                SetLayerVolume("Base", 1f);
+                SetLayerVolume("Melody", 0f);
+                SetLayerVolume("Drums", 1f);
+                SetLayerVolume("Intensity", 0.7f);
+                break;
+                
+            case MusicState.Boss:
+                SetLayerVolume("Base", 1f);
+                SetLayerVolume("Melody", 0.5f);
+                SetLayerVolume("Drums", 1f);
+                SetLayerVolume("Intensity", 1f);
+                break;
+        }
+    }
+    
+    private void SetLayerVolume(string layerName, float volume)
+    {
+        var layer = layers.FirstOrDefault(l => l.Name == layerName);
+        if (layer != null)
+        {
+            layer.TargetVolume = volume;
+        }
+    }
+    
+    private void SyncAllLayers()
+    {
+        float syncTime = layers[0].Source.time;
+        foreach (var layer in layers)
+        {
+            layer.Source.time = syncTime;
+        }
+    }
+}
+```
+
+---
+
+## Footstep System
+
+```csharp
+public class FootstepSystem : MonoBehaviour
+{
+    [System.Serializable]
+    public class SurfaceAudio
+    {
+        public string SurfaceTag;
+        public PhysicMaterial PhysicsMaterial;
+        public AudioClip[] FootstepClips;
+        public AudioClip[] LandingClips;
+        [Range(0, 1)] public float Volume = 1f;
+    }
+    
+    [SerializeField] private SurfaceAudio[] surfaces;
+    [SerializeField] private SurfaceAudio defaultSurface;
+    
+    [Header("Settings")]
+    [SerializeField] private float footstepInterval = 0.5f;
+    [SerializeField] private float runMultiplier = 0.7f;
+    [SerializeField] private LayerMask groundMask;
+    
+    private AudioSource _audioSource;
+    private float _lastFootstepTime;
+    private CharacterController _controller;
+    
+    void Awake()
+    {
+        _audioSource = gameObject.AddComponent<AudioSource>();
+        _audioSource.spatialBlend = 1f;
+        _controller = GetComponent<CharacterController>();
+    }
+    
+    public void PlayFootstep(bool isRunning = false)
+    {
+        float interval = isRunning ? footstepInterval * runMultiplier : footstepInterval;
+        
+        if (Time.time - _lastFootstepTime < interval) return;
+        _lastFootstepTime = Time.time;
+        
+        var surface = GetCurrentSurface();
+        if (surface != null && surface.FootstepClips.Length > 0)
+        {
+            var clip = surface.FootstepClips[Random.Range(0, surface.FootstepClips.Length)];
+            _audioSource.PlayOneShot(clip, surface.Volume);
+        }
+    }
+    
+    public void PlayLanding()
+    {
+        var surface = GetCurrentSurface();
+        if (surface != null && surface.LandingClips.Length > 0)
+        {
+            var clip = surface.LandingClips[Random.Range(0, surface.LandingClips.Length)];
+            _audioSource.PlayOneShot(clip, surface.Volume * 1.2f);
+        }
+    }
+    
+    private SurfaceAudio GetCurrentSurface()
+    {
+        if (Physics.Raycast(transform.position, Vector3.down, out RaycastHit hit, 2f, groundMask))
+        {
+            // Check by tag
+            foreach (var surface in surfaces)
+            {
+                if (hit.collider.CompareTag(surface.SurfaceTag))
+                {
+                    return surface;
+                }
+            }
+            
+            // Check by physics material
+            if (hit.collider.material != null)
+            {
+                foreach (var surface in surfaces)
+                {
+                    if (surface.PhysicsMaterial == hit.collider.material)
+                    {
+                        return surface;
+                    }
+                }
+            }
+        }
+        
+        return defaultSurface;
+    }
+    
+    // Called from animation events
+    public void OnFootstepLeft() => PlayFootstep();
+    public void OnFootstepRight() => PlayFootstep();
+}
+```
+
+---
+
+## Spatial Audio Setup
+
+```csharp
+public class SpatialAudioSource : MonoBehaviour
+{
+    [Header("3D Settings")]
+    [SerializeField] private float minDistance = 1f;
+    [SerializeField] private float maxDistance = 50f;
+    [SerializeField] private AudioRolloffMode rolloffMode = AudioRolloffMode.Logarithmic;
+    
+    [Header("Occlusion")]
+    [SerializeField] private bool useOcclusion = true;
+    [SerializeField] private LayerMask occlusionMask;
+    [SerializeField] private float occlusionDamping = 0.5f;
+    
+    private AudioSource _source;
+    private AudioLowPassFilter _lowPass;
+    private Transform _listener;
+    
+    void Awake()
+    {
+        _source = GetComponent<AudioSource>();
+        _source.spatialBlend = 1f;
+        _source.minDistance = minDistance;
+        _source.maxDistance = maxDistance;
+        _source.rolloffMode = rolloffMode;
+        
+        if (useOcclusion)
+        {
+            _lowPass = gameObject.AddComponent<AudioLowPassFilter>();
+            _lowPass.cutoffFrequency = 22000f;
+        }
+    }
+    
+    void Start()
+    {
+        _listener = Camera.main.transform;
+    }
+    
+    void Update()
+    {
+        if (!useOcclusion || _listener == null) return;
+        
+        Vector3 direction = _listener.position - transform.position;
+        
+        if (Physics.Raycast(transform.position, direction.normalized, direction.magnitude, occlusionMask))
+        {
+            // Occluded - lower frequencies
+            _lowPass.cutoffFrequency = Mathf.Lerp(
+                _lowPass.cutoffFrequency,
+                1000f,
+                occlusionDamping * Time.deltaTime * 10f
+            );
+            _source.volume = Mathf.Lerp(_source.volume, 0.5f, occlusionDamping * Time.deltaTime * 10f);
+        }
+        else
+        {
+            // Clear path
+            _lowPass.cutoffFrequency = Mathf.Lerp(
+                _lowPass.cutoffFrequency,
+                22000f,
+                occlusionDamping * Time.deltaTime * 10f
+            );
+            _source.volume = Mathf.Lerp(_source.volume, 1f, occlusionDamping * Time.deltaTime * 10f);
+        }
+    }
+}
+```
+
+---
+
+## Audio Cue Variations
+
+```csharp
+[CreateAssetMenu(fileName = "New Audio Cue", menuName = "Audio/Cue")]
+public class AudioCue : ScriptableObject
+{
+    [System.Serializable]
+    public class ClipVariant
+    {
+        public AudioClip Clip;
+        [Range(0, 1)] public float Weight = 1f;
+    }
+    
+    public ClipVariant[] Variants;
+    
+    [Header("Pitch")]
+    public float PitchMin = 0.95f;
+    public float PitchMax = 1.05f;
+    
+    [Header("Volume")]
+    public float VolumeMin = 0.9f;
+    public float VolumeMax = 1f;
+    
+    private int _lastPlayedIndex = -1;
+    
+    public void Play(AudioSource source)
+    {
+        if (Variants.Length == 0) return;
+        
+        source.clip = GetRandomClip();
+        source.pitch = Random.Range(PitchMin, PitchMax);
+        source.volume = Random.Range(VolumeMin, VolumeMax);
+        source.Play();
+    }
+    
+    public void PlayOneShot(AudioSource source)
+    {
+        if (Variants.Length == 0) return;
+        
+        var clip = GetRandomClip();
+        float volume = Random.Range(VolumeMin, VolumeMax);
+        
+        // Temporarily adjust pitch
+        float originalPitch = source.pitch;
+        source.pitch = Random.Range(PitchMin, PitchMax);
+        source.PlayOneShot(clip, volume);
+        source.pitch = originalPitch;
+    }
+    
+    private AudioClip GetRandomClip()
+    {
+        // Weighted random, avoiding immediate repeat
+        float totalWeight = Variants.Sum(v => v.Weight);
+        float random = Random.Range(0f, totalWeight);
+        
+        float cumulative = 0f;
+        for (int i = 0; i < Variants.Length; i++)
+        {
+            cumulative += Variants[i].Weight;
+            if (random <= cumulative && i != _lastPlayedIndex)
+            {
+                _lastPlayedIndex = i;
+                return Variants[i].Clip;
+            }
+        }
+        
+        _lastPlayedIndex = 0;
+        return Variants[0].Clip;
+    }
+}
+```
+
+---
+
+## Quick Reference
+
+| System | Key Approach |
+|--------|--------------|
+| **SFX** | Pool audio sources, reuse |
+| **Music** | Crossfade, layer-based |
+| **Spatial** | Set spatialBlend = 1 |
+| **Footsteps** | Surface detection + variations |
+| **Ambience** | Looping, zone-based |
+
+---
+
+## Anti-Patterns
+
+| ❌ Don't | ✅ Do |
+|----------|-------|
+| Create new AudioSource each time | Use pooling |
+| Same clip every time | Add variations |
+| Hard transitions | Crossfade |
+| Ignore occlusion | Use low-pass for walls |
+| Max volume everything | Dynamic mixing |
+
+---
+
+> **Remember:** Audio is 50% of immersion. Invest in it.