Phase 1: Setup project structure and tool installation guide

- Created project directory structure - Added docs/SETUP_PHASE1.md with tool installation instructions - Added docs/AUDIO_ANALYSIS.md with game audio architecture - Added src/HomuraHimeAudioMod/ BepInEx plugin skeleton - Added patch stubs for VoiceManager, AudioDucking, EnemyAudio - Configured .gitignore for build artifacts and game files - Initialized beads issue tracker
2026-03-22 13:35:01 -04:00
parent 05b01ef276
commit 7169d4533b
9 changed files with 640 additions and 1 deletions
--- a/.gitignore
+++ b/.gitignore
@@ -1,4 +1,38 @@
-
 # Dolt database files (added by bd init)
 .dolt/
 *.db
+
+# Build outputs
+bin/
+obj/
+*.dll
+*.pdb
+*.mdb
+
+# IDE
+.vs/
+.vscode/
+*.user
+*.suo
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Game files (should not be in repo)
+# Uncomment if you want to track modified game files
+# HomuraHime_Data/
+
+# BepInEx (runtime generated)
+BepInEx/logs/
+BepInEx/cache/
+BepInEx/config/
+
+# FMOD Studio
+*.cache
+*~
+
+# Temporary files
+*.tmp
+*.bak
+*.swp
--- a/docs/AUDIO_ANALYSIS.md
+++ b/docs/AUDIO_ANALYSIS.md
@@ -0,0 +1,172 @@
+# HomuraHime Audio System Analysis
+
+## Game Overview
+- **Engine**: Unity 2022.3.x
+- **Audio Engine**: FMOD Studio 2.02.x with Google Resonance spatial audio
+- **Voice Manager**: UtageFmodVoiceManager (adapted Utage framework)
+- **Platform**: Steam (uses Steamworks.NET)
+
+## Audio Architecture
+
+### Directory Structure
+```
+HomuraHime_Data\
+├── Managed\
+│   ├── Assembly-CSharp.dll          (7.08 MB - main game logic)
+│   ├── Assembly-CSharp-firstpass.dll (3.92 MB - runtime code)
+│   ├── FMODUnity.dll               (239 KB - FMOD Unity integration)
+│   ├── FMODUnityResonance.dll      (11 KB - FMOD Resonance extension)
+│   └── UnityEngine.AudioModule.dll
+├── Plugins\x86_64\
+│   ├── fmodstudio.dll              (3.16 MB - FMOD core)
+│   └── resonanceaudio.dll          (817 KB - Google Resonance spatial)
+└── StreamingAssets\FMOD\Desktop\
+    └── (49 FMOD bank files - ~1.3 GB total)
+```
+
+### FMOD Bank Files
+
+| Bank | Purpose | Size (streams) |
+|------|---------|----------------|
+| Master.bank | Main mixer and routing | 98.5 KB |
+| BGM.bank | Background music (general) | 63.83 MB |
+| BGM_Default.bank | Default BGM | 224.07 MB |
+| BGM_Hub.bank | Hub area music | 14.67 MB |
+| BGM_Lv0-Lv5, BGM_LvF | Level-specific music | 14-64 MB each |
+| Ambience.bank | Environmental sounds | 150.97 MB |
+| SFX.bank | Sound effects | 188.97 MB |
+| Voice.bank | Character voice | 19.83 MB |
+| PreLoad_Jump.bank | Pre-cached jump sounds | ~533 KB |
+| PreLoad_FootStep_Land.bank | Pre-cached footstep sounds | ~1 MB |
+
+**Total Audio: ~1.3 GB across 49 bank files**
+
+## Key Audio Classes
+
+### Voice Management
+- **UtageFmodVoiceManager** - Main voice manager (Utage framework adapted)
+- **CFVoiceData** / **CFVoiceEventUtility** - Custom voice event system
+- **CharacterVoiceData** - Character voice data handling
+- **FmodVoiceStopper** - Voice stop controller
+- **get_CountVoice** / **get_IsPlayingVoice** - Voice count monitoring
+
+### Sound Management
+- **FMODSoundManager** - Main FMOD sound manager
+- **SoundManager** (Utage base) - Base sound manager
+- **FmodSFXEventSO**, **FmodSFXEventRef**, **FmodSFXEventDispatcher** - Custom SFX system
+- **FMODEventInstance** - FMOD event instance wrapper
+
+### Channel/Volume Control
+- **FMOD_Channel** - Custom FMOD channel wrapper
+- **VCASetting** - Volume control area settings
+- **TaggedMasterVolume** - Per-tag master volume control
+- **BGMChannel** - BGM channel management
+
+### Audio Effects
+- **UpdateDucking** / **DuckVolume** - Audio ducking system
+- **SnapshotManager** - Snapshot management
+- **FmodReverbEventController** - Reverb control
+- **ZoneReverbHandler** - Zone-based reverb
+
+### Spatial Audio
+- **HHFmodListenerPosController** - FMOD listener position controller
+- **resonanceaudio.dll** - Google Resonance spatial audio
+
+### Pooling
+- **SimplePool** / **ObjectPool** - Generic object pooling
+- **DEFAULT_POOL_SIZE**, **VfxObjectPoolSize** - Pool size constants
+
+## Voice Event Constants (CFVOICE Events)
+
+The game triggers voice events for various situations:
+- `CFVOICE_REWARD` - Reward sounds
+- `CFVOICE_CHALLENGEBATTLE` - Challenge battle start
+- `CFVOICE_BATTLE` - Battle start
+- `CFVOICE_NOTE` - Note/commentary
+- `CFVOICE_MHCHASING` - Chasing sequences
+- `CFVOICE_ELECTRIFYING` - Electrifying events
+- `CFVOICE_HH` / `HH_Behaviour` - HomuraHime behavior events
+- `CFVOICE_ENEMY` - Enemy-related voice
+- `CFVOICE_QTE_SHIKIGAMI` - QTE shikigami events
+- `CFVOICE_BATTLERANK` - Battle rank announcements
+- And many more...
+
+## Enemy System
+
+### Enemy Audio Triggers
+- **EnemyBehaviorManger** - Enemy behavior management
+- **EnemyAttackBase**, **EnemyAttackAction**, **EnemyAttackBlockedAction** - Attack handling
+- **EnemyIndicatorController** - Visual indicators for enemies
+- **SetEnemyAI** - AI setting method
+- **EnemyState** - Enemy state tracking
+
+### HUD/Indicator Classes
+- **HUDIndicatorPhase** / **HUDIndicatorPhaseHandler** - Phase indicator handling
+- **CDHUDIndicatorHandler** - Cooldown HUD indicator
+- **IndicatorManager** - Indicator management
+
+## Audio Configuration
+
+### Pool-Related Constants
+- `DEFAULT_POOL_SIZE` - Default pool size
+- `VfxObjectPoolSize` - VFX pool size
+- `ObjectPoolSize` - Generic object pool size
+- `poolPreloadnum` - Pool preload count
+- `preloadCountPerPrefab` - Per-prefab preload count
+
+### FMOD Channel Constants
+- `MAXCHANNELS` - Maximum channel count
+- `ERR_TOOMANYCHANNELS` - Channel overflow error
+- `ERR_CHANNEL_ALLOC` - Channel allocation error
+- `VIRTUALVOICE` - Virtual voice management
+- `CHANNELPRIORITY` - Channel priority setting
+- `MAX_CHANNEL_WIDTH` - Maximum channel width
+
+## Key Findings
+
+1. **No explicit voice limit constants** visible in string analysis - voice limit may be managed internally by FMOD or Utage framework
+2. **Audio ducking system exists** - `UpdateDucking` and `DuckVolume` present
+3. **Voice pooling exists** - Object pooling with `DEFAULT_POOL_SIZE` constants
+4. **Lip-sync support** - Using `uLipSyncFMOD` for voice synchronization
+5. **Priority system** - `CHANNELPRIORITY` and `Priority` fields for channel prioritization
+6. **Event-driven voice system** - Voices triggered via CFVOICE event constants
+
+## Source File Paths (from DLL strings)
+
+These are the original Unity asset paths in the game source:
+- `Assets/4.Developer/Andy/UtageVoiceManager/UtageFmodVoiceManager.cs`
+- `Assets/4.Developer/Andy/UtageVoiceManager/UtageFmodVoiceSetting.cs`
+- `Assets/4.Developer/Andy/UtageVoiceManager/FmodVoiceStopper.cs`
+- `Assets/4.Developer/Andy/UtageVoiceManager/DEAudioFadeManager.cs`
+- `Assets/4.Developer/Andy/UtageVoiceManager/SnapshotManager.cs`
+- `Assets/4.Developer/Andy/UtageVoiceManager/FmodReverbEventController.cs`
+- `Assets/1.HonoHime/Core/FMODUtility/Scripts/FMODSoundManager.cs`
+- `Assets/1.HonoHime/Core/FMODUtility/Scripts/MMFeedbacks/FMOD_Channel.cs`
+- `Assets/1.HonoHime/Core/mLibrary/ObjectPool/SimplePool.cs`
+
+## Game Data Files
+
+Audio-related configuration may exist in:
+- `HomuraHime_Data\StreamingAssets\HomuraHimeData\csv\EnemyData.json`
+- `HomuraHime_Data\StreamingAssets\HomuraHimeData\json\BattleRound.json`
+- `HomuraHime_Data\StreamingAssets\HomuraHimeData\json\EnemyData.json`
+
+## Potential Audio Glitch Causes
+
+Based on architecture analysis:
+
+1. **Voice Limit Exhaustion** - Too many simultaneous FMOD events
+2. **Missing Audio Ducking Rules** - No automatic volume reduction during intense combat
+3. **Improper Event Instance Cleanup** - Voices not being released properly
+4. **CPU Pressure from Spatial Audio** - Resonance audio processing overhead
+5. **Pool Size Limitations** - Object pool too small for audio components
+
+## Enemy Behavior Indicator Issues
+
+Potential causes for unclear enemy audio cues:
+
+1. **Low Mix Volume** - Enemy sounds mixed too low in Master.bank
+2. **Insufficient Spatial Positioning** - Sounds not directional enough
+3. **Lack of State Variation** - Same sounds for all enemy states
+4. **Audio Masking** - Other sounds drowning out enemy cues
+5. **Missing Parameter Changes** - No FMOD parameter automation for enemy state
--- a/docs/SETUP_PHASE1.md
+++ b/docs/SETUP_PHASE1.md
@@ -0,0 +1,277 @@
+# Phase 1: Environment Setup Guide
+
+## Overview
+This phase covers installation of all required modding tools for HomuraHime audio modding.
+
+---
+
+## Tool 1: BepInEx 5.x (Runtime Mod Framework)
+
+### What It Does
+Enables runtime patching of game code without modifying original DLLs. Required for audio voice limit patches.
+
+### Download
+```
+https://github.com/BepInEx/BepInEx/releases
+```
+- Download: **BepInEx 5.4.x** (latest stable)
+- File: `BepInEx_x64_5.4.x.zip`
+
+### Installation Steps
+
+1. **Backup original game files** (optional but recommended)
+   ```
+   C:\apps\steam\steamapps\common\Homura Hime\
+   ```
+
+2. **Extract BepInEx to game directory**
+   ```
+   Extract BepInEx_x64_5.4.x.zip contents to:
+   C:\apps\steam\steamapps\common\Homura Hime\
+   ```
+   
+   After extraction, you should have:
+   ```
+   Homura Hime\
+   ├── BepInEx\
+   ├── HomuraHime.exe
+   ├── HomuraHime_Data\
+   └── winhttp.dll  (BepInEx loader)
+   ```
+
+3. **Run game once to generate configs**
+   ```
+   Launch HomuraHime via Steam
+   Let it run for ~10 seconds until main menu appears
+   Close game
+   ```
+
+4. **Verify installation**
+   ```
+   Check for: BepInEx\LogOutput.log
+   Check for: BepInEx\config\
+   ```
+
+---
+
+## Tool 2: FMOD Studio 2.02.x (Audio Bank Editor)
+
+### What It Does
+Allows editing of FMOD bank files (.bank) to modify audio events, voice limits, ducking, and enemy cue sounds.
+
+### Download
+```
+https://fmod.com/studio
+```
+- Click "Download" → "FMOD Studio" (Windows)
+- **Free for non-commercial use** (per FMOD licensing)
+- You will need to create an account
+
+### Installation Steps
+
+1. **Run the FMOD Studio installer**
+   ```
+   fmod_studio_installer_2.02.x.exe
+   ```
+
+2. **Choose installation location**
+   ```
+   Recommended: C:\Program Files\FMOD Studio\
+   ```
+
+3. **Launch FMOD Studio**
+   ```
+   Start Menu → FMOD Studio 2.02
+   ```
+
+4. **Verify installation**
+   ```
+   Help → About FMOD Studio
+   Should show version 2.02.x
+   ```
+
+### Important Notes
+- HomuraHime uses **FMOD Studio 2.02.x** - using a different major version may cause compatibility issues
+- The game uses FMOD **Desktop** banks (not iOS/Android)
+- Banks are located at: `HomuraHime_Data\StreamingAssets\FMOD\Desktop\`
+
+---
+
+## Tool 3: AssetRipper (Asset Extraction)
+
+### What It Does
+Extracts game assets from Unity games, including FMOD bank files for editing.
+
+### Download
+```
+https://github.com/sRcAss/AssetRipper/releases
+```
+- Download: **AssetRipper_x.x.xx.zip** (latest)
+- File size: ~100 MB
+
+### Installation Steps
+
+1. **Extract to tools directory**
+   ```
+   Extract to: C:\projects\HomuraHime-Mods\tools\AssetRipper\
+   ```
+
+2. **Launch AssetRipper**
+   ```
+   AssetRipper.exe
+   ```
+
+3. **No installation needed** - it's a standalone executable
+
+### Verify Installation
+```
+Run AssetRipper.exe - should open GUI without errors
+```
+
+---
+
+## Tool 4: ILSpy (.NET Decompiler)
+
+### What It Does
+Decompiles .NET assemblies (DLLs) to C# code for analysis. Used to find audio hook points.
+
+### Download
+```
+https://github.com/icsharpcode/ILSpy/releases
+```
+- Download: **ILSpy_x.x.x.zip** or **ILSpy_4_0.msi** (installer)
+- Or use: **ILSpyCmd** (command-line version)
+
+### Installation Steps (GUI Version)
+
+1. **Extract to tools directory**
+   ```
+   Extract to: C:\projects\HomuraHime-Mods\tools\ILSpy\
+   ```
+
+2. **Launch ILSpy**
+   ```
+   ILSpy.exe
+   ```
+
+### Installation Steps (VS Code Extension - Alternative)
+
+1. **In VS Code, press Ctrl+Shift+X**
+2. **Search "ILSpy"**
+3. **Install "ILSpy for Visual Studio Code"**
+
+### Verify Installation
+```
+Run ILSpy.exe - should open GUI
+```
+
+---
+
+## Tool 5: Unity 2022.3.x (Optional - Script Compilation)
+
+### What It Does
+Required only if you need to compile modified C# scripts. Most audio patches can be done via BepInEx without Unity.
+
+### Download
+```
+https://unity.com/download
+```
+- Choose: "Unity 2022.3 LTS"
+- Or: https://unity.com/releases/editor/whats-new/2022.3
+
+### Installation Steps
+
+1. **Run Unity Hub installer**
+   ```
+   UnityHubSetup.exe
+   ```
+
+2. **Install with these components**
+   - Unity 2022.3.x
+   - Microsoft Visual Studio Community (for scripting)
+   - Android Build Support (optional)
+
+3. **Activation**
+   - Use free personal license
+
+### Is This Required?
+**Probably NOT** for audio mods. You likely only need this if:
+- You want to recompile modified game scripts
+- You need to understand game structure deeply
+- BepInEx patches require compilation
+
+---
+
+## Project Directory Structure
+
+After completing Phase 1, your project should look like:
+
+```
+C:\projects\HomuraHime-Mods\
+├── .beads/                     (beads issue tracker)
+├── .git/                       (git repository)
+├── AGENTS.md                   (agent instructions)
+├── docs/
+│   ├── SETUP_PHASE1.md         (this file)
+│   ├── AUDIO_ANALYSIS.md       (from explore agent)
+│   └── (future phase docs)
+├── tools/
+│   ├── BepInEx/                (installed in game folder)
+│   ├── FMOD/                   (installed via installer)
+│   ├── AssetRipper/
+│   │   └── AssetRipper.exe
+│   └── ILSpy/
+│       └── ILSpy.exe
+└── src/                        (future: mod source code)
+    └── HomuraHimeAudioMod/
+```
+
+And your game folder:
+
+```
+C:\apps\steam\steamapps\common\Homura Hime\
+├── BepInEx\                    (NEW - BepInEx framework)
+├── HomuraHime.exe
+├── HomuraHime_Data\
+│   ├── Managed\
+│   │   └── (original DLLs)
+│   └── StreamingAssets\
+│       └── FMOD\
+│           └── Desktop\
+│               ├── SFX.bank
+│               ├── Ambience.bank
+│               └── (other banks)
+├── winhttp.dll                 (NEW - BepInEx loader)
+└── (other game files)
+```
+
+---
+
+## Verification Checklist
+
+After Phase 1 installation, verify each tool:
+
+| Tool | Verification | Expected Result |
+|------|--------------|-----------------|
+| BepInEx | Check `BepInEx\LogOutput.log` | Log file exists after game runs |
+| FMOD Studio | Launch app | Opens without errors, shows version 2.02.x |
+| AssetRipper | Launch `AssetRipper.exe` | GUI opens |
+| ILSpy | Launch `ILSpy.exe` | GUI opens with tree view |
+| Unity 2022.3 | Launch Unity Hub | Lists 2022.3.x as available |
+
+---
+
+## Next Steps
+
+After completing Phase 1:
+- Proceed to **Phase 2: Code Analysis**
+- Use ILSpy to decompile and analyze audio classes
+- Document voice limits and hook points
+
+---
+
+## Phase 1 Issues
+
+| Issue ID | Status |
+|----------|--------|
+| HomuraHime-Mods-9ji | In Progress |
--- a/src/HomuraHimeAudioMod/HomuraHimeAudioMod.csproj
+++ b/src/HomuraHimeAudioMod/HomuraHimeAudioMod.csproj
@@ -0,0 +1,33 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <TargetFramework>net48</TargetFramework>
+    <AssemblyName>HomuraHimeAudioMod</AssemblyName>
+    <RootNamespace>HomuraHimeAudioMod</RootNamespace>
+    <Version>1.0.0</Version>
+    <Authors>Ed</Authors>
+    <Description>Audio improvements mod for HomuraHime - fixes glitches and improves enemy indicators</Description>
+    <GameAssemblyPath>C:\apps\steam\steamapps\common\Homura Hime\HomuraHime_Data\Managed</GameAssemblyPath>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <PackageReference Include="0Harmony" Version="2.2.2" />
+    <PackageReference Include="BepInEx" Version="5.4.21" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <Reference Include="FMODUnity">
+      <HintPath>$(GameAssemblyPath)\FMODUnity.dll</HintPath>
+      <Private>false</Private>
+    </Reference>
+    <Reference Include="UnityEngine.AudioModule">
+      <HintPath>$(GameAssemblyPath)\UnityEngine.AudioModule.dll</HintPath>
+      <Private>false</Private>
+    </Reference>
+    <Reference Include="Assembly-CSharp">
+      <HintPath>$(GameAssemblyPath)\Assembly-CSharp.dll</HintPath>
+      <Private>false</Private>
+    </Reference>
+  </ItemGroup>
+
+</Project>
--- a/src/HomuraHimeAudioMod/Patches/AudioDuckingPatch.cs
+++ b/src/HomuraHimeAudioMod/Patches/AudioDuckingPatch.cs
@@ -0,0 +1,19 @@
+using HarmonyLib;
+
+namespace HomuraHimeAudioMod.Patches
+{
+    /// <summary>
+    /// Patches for audio ducking system improvements.
+    /// TO BE IMPLEMENTED AFTER PHASE 2 CODE ANALYSIS
+    /// </summary>
+    public class AudioDuckingPatch
+    {
+        public static void Apply(ref Harmony harmony)
+        {
+            // TODO: After Phase 2, implement patches for:
+            // - Improve ducking fade times
+            // - Adjust duck amounts for combat
+            // - Add custom ducking rules
+        }
+    }
+}
--- a/src/HomuraHimeAudioMod/Patches/EnemyAudioPatch.cs
+++ b/src/HomuraHimeAudioMod/Patches/EnemyAudioPatch.cs
@@ -0,0 +1,19 @@
+using HarmonyLib;
+
+namespace HomuraHimeAudioMod.Patches
+{
+    /// <summary>
+    /// Patches for enemy behavior audio indicator improvements.
+    /// TO BE IMPLEMENTED AFTER PHASE 2 CODE ANALYSIS
+    /// </summary>
+    public class EnemyAudioPatch
+    {
+        public static void Apply(ref Harmony harmony)
+        {
+            // TODO: After Phase 2, implement patches for:
+            // - Boost enemy indicator volumes
+            // - Improve state change audio cues
+            // - Add debug logging for enemy audio
+        }
+    }
+}
--- a/src/HomuraHimeAudioMod/Patches/VoiceManagerPatch.cs
+++ b/src/HomuraHimeAudioMod/Patches/VoiceManagerPatch.cs
@@ -0,0 +1,19 @@
+using HarmonyLib;
+
+namespace HomuraHimeAudioMod.Patches
+{
+    /// <summary>
+    /// Patches for voice limit and voice manager improvements.
+    /// TO BE IMPLEMENTED AFTER PHASE 2 CODE ANALYSIS
+    /// </summary>
+    public class VoiceManagerPatch
+    {
+        public static void Apply(ref Harmony harmony)
+        {
+            // TODO: After Phase 2, implement patches for:
+            // - Increase max voice count
+            // - Improve voice stealing behavior
+            // - Adjust pooling sizes
+        }
+    }
+}
--- a/src/HomuraHimeAudioMod/Plugin.cs
+++ b/src/HomuraHimeAudioMod/Plugin.cs
@@ -0,0 +1,47 @@
+using BepInEx;
+using BepInEx.Logging;
+using HarmonyLib;
+
+namespace HomuraHimeAudioMod
+{
+    [BepInPlugin(PluginInfo.PLUGIN_GUID, PluginInfo.PLUGIN_NAME, PluginInfo.PLUGIN_VERSION)]
+    public class Plugin : BaseUnityPlugin
+    {
+        public const string PLUGIN_GUID = "com.homurahime.audiomod";
+        public const string PLUGIN_NAME = "HomuraHime Audio Mod";
+        public const string PLUGIN_VERSION = "1.0.0";
+
+        private static Plugin instance;
+        private static ManualLogSource logger;
+        private Harmony harmony;
+
+        public static ManualLogSource Log => logger;
+
+        private void Awake()
+        {
+            instance = this;
+            logger = Logger;
+            
+            harmony = new Harmony(PluginInfo.PLUGIN_GUID);
+
+            ApplyPatches();
+        }
+
+        private void ApplyPatches()
+        {
+            Log.LogInfo($"Applying audio patches...");
+
+            // Phase 2 will populate these patch classes after code analysis
+            // VoiceManagerPatch.Apply(ref harmony);
+            // AudioDuckingPatch.Apply(ref harmony);
+            // EnemyAudioPatch.Apply(ref harmony);
+
+            Log.LogInfo($"Patches applied successfully");
+        }
+
+        private void OnDestroy()
+        {
+            harmony?.UnpatchAll();
+        }
+    }
+}
--- a/src/HomuraHimeAudioMod/Properties/AssemblyInfo.cs
+++ b/src/HomuraHimeAudioMod/Properties/AssemblyInfo.cs
@@ -0,0 +1,19 @@
+using System.Reflection;
+using System.Runtime.CompilerServices;
+using System.Runtime.InteropServices;
+
+[assembly: AssemblyTitle("HomuraHimeAudioMod")]
+[assembly: AssemblyDescription("Audio improvements mod for HomuraHime")]
+[assembly: AssemblyConfiguration("")]
+[assembly: AssemblyCompany("")]
+[assembly: AssemblyProduct("HomuraHimeAudioMod")]
+[assembly: AssemblyCopyright("Copyright © 2026")]
+[assembly: AssemblyTrademark("")]
+[assembly: AssemblyCulture("")]
+
+[assembly: ComVisible(false)]
+
+[assembly: Guid("xxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx")]
+
+[assembly: AssemblyVersion("1.0.0.0")]
+[assembly: AssemblyFileVersion("1.0.0.0")]