# Hack23 Blacktrigram Audio Game Integration

> Audio Game Integration Skill

- Skill: `tomevault-io/hack23-blacktrigram-audio-game-integration` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tomevault-io/hack23-blacktrigram-audio-game-integration`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/hack23-blacktrigram-audio-game-integration/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Integrations & APIs
- Author: tomevault-io (https://skillmd.com/u/tomevault-io)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tomevault-io/hack23-blacktrigram-audio-game-integration

---


# Audio Game Integration Skill

## Purpose

Ensures all audio in Black Trigram uses Howler.js effectively, implements spatial 3D audio for immersion, optimizes performance, provides clear combat feedback, creates authentic Korean-themed soundscapes, and manages audio resources properly.

## When to Apply

**Automatically trigger when:**
- Adding audio effects or music
- Implementing spatial 3D audio
- Creating combat sound feedback
- Managing audio resources
- Optimizing audio performance
- Adding Korean-themed audio
- Implementing audio settings (volume, mute)
- Debugging audio issues

## Core Principles

### 1. Howler.js Global Audio Management

✅ **Proper Audio Manager Pattern**
```typescript
import { Howl, Howler } from 'howler';

export class AudioManager {
  private sounds = new Map<string, Howl>();
  private music: Howl | null = null;
  
  load(id: string, src: string, options?: HowlOptions): void {
    const sound = new Howl({
      src: [src],
      volume: options?.volume ?? 0.7,
      loop: options?.loop ?? false,
      preload: true,
      ...options,
    });
    this.sounds.set(id, sound);
  }
  
  playSFX(id: string): void {
    this.sounds.get(id)?.play();
  }
  
  playMusic(id: string, fadeIn = 1000): void {
    if (this.music) this.stopMusic();
    const sound = this.sounds.get(id);
    if (!sound) return;
    
    this.music = sound;
    this.music.volume(0);
    this.music.play();
    this.music.fade(0, 0.5, fadeIn);
  }
  
  setSFXVolume(volume: number): void {
    this.sounds.forEach(sound => {
      if (sound !== this.music) {
        sound.volume(volume);
      }
    });
  }
}
```

### 2. Spatial 3D Audio with PositionalAudio

✅ **3D Spatial Audio Pattern**
```typescript
import { PositionalAudio } from '@react-three/drei';

export const Combat3DAudio: React.FC<{ position: Vector3 }> = ({ position }) => {
  return (
    <group position={position}>
      <PositionalAudio
        url="/audio/combat-ambient.mp3"
        distance={10}
        loop
        autoplay
      />
    </group>
  );
};
```

### 3. Combat Audio Feedback

✅ **Combat Sound System**
```typescript
export const useCombatAudio = () => {
  const audio = useAudio();
  
  const playStrikeSound = useCallback((
    strikeType: StrikeType,
    hit: boolean,
    critical: boolean
  ) => {
    if (!hit) {
      audio.playSFX('strike_miss');
      return;
    }
    
    if (critical) {
      audio.playSFX('strike_critical');
    } else {
      audio.playSFX(`strike_${strikeType}`);
    }
  }, [audio]);
  
  return { playStrikeSound };
};
```

### 4. Korean-Themed Soundscape

✅ **Cultural Audio Integration**
```typescript
export const KOREAN_AUDIO_THEMES = {
  MENU: {
    music: '/audio/korean-traditional-menu.mp3',
    ambient: '/audio/dojang-atmosphere.mp3',
  },
  COMBAT: {
    music: '/audio/korean-percussion-combat.mp3',
    strikes: {
      GEON: '/audio/thunder-strike.mp3',  // Heaven
      GAM: '/audio/water-flow.mp3',       // Water
      LI: '/audio/fire-strike.mp3',       // Fire
    },
  },
} as const;
```

## Enforcement Rules

### Rule 1: Howler.js for Global Audio
```
IF (using Web Audio API directly OR HTML5 audio)
THEN (use Howler.js AudioManager for consistency)
ELSE (verify preloading and resource management)
```

### Rule 2: Spatial Audio for 3D Scenes
```
IF (3D combat scene WITHOUT positional audio)
THEN (add PositionalAudio for attacks, impacts, movement)
ELSE (verify audio distance falloff is realistic)
```

### Rule 3: Combat Feedback Clarity
```
IF (strike sound without hit/miss/critical distinction)
THEN (implement distinct audio for each outcome)
ELSE (verify audio timing matches visual feedback)
```

## Anti-Patterns to REJECT

❌ **Synchronous Loading** - Always preload audio
❌ **No Volume Controls** - Must support mute and volume adjustment
❌ **Memory Leaks** - Clean up audio on unmount
❌ **No Spatial Audio** - 3D games need positional audio

## Compliance Framework

- **ISO 27001 A.8.1**: Audio asset management
- **NIST CSF ID.AM**: Audio resource inventory
- **CIS Control 2**: Audio asset tracking

## Remember

**소리의 예술 (Art of Sound)**

Audio enhances immersion and provides critical combat feedback. Proper spatial audio and Korean-themed soundscapes bring Black Trigram to life.

**흑괘의 길을 걸어라** - _Walk the Path of the Black Trigram_

---
> Converted and distributed by [TomeVault](https://tomevault.io/claim/hack23) — claim your Tome and manage your conversions.
<!-- tomevault:4.0:skill_md:2026-04-12 -->