diff --git a/.gitignore b/.gitignore index dc7a30c..7d783d9 100644 --- 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 diff --git a/docs/AUDIO_ANALYSIS.md b/docs/AUDIO_ANALYSIS.md new file mode 100644 index 0000000..dde85b6 --- /dev/null +++ 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 diff --git a/docs/SETUP_PHASE1.md b/docs/SETUP_PHASE1.md new file mode 100644 index 0000000..9da1554 --- /dev/null +++ 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 | diff --git a/src/HomuraHimeAudioMod/HomuraHimeAudioMod.csproj b/src/HomuraHimeAudioMod/HomuraHimeAudioMod.csproj new file mode 100644 index 0000000..7c1394c --- /dev/null +++ b/src/HomuraHimeAudioMod/HomuraHimeAudioMod.csproj @@ -0,0 +1,33 @@ + + + + net48 + HomuraHimeAudioMod + HomuraHimeAudioMod + 1.0.0 + Ed + Audio improvements mod for HomuraHime - fixes glitches and improves enemy indicators + C:\apps\steam\steamapps\common\Homura Hime\HomuraHime_Data\Managed + + + + + + + + + + $(GameAssemblyPath)\FMODUnity.dll + false + + + $(GameAssemblyPath)\UnityEngine.AudioModule.dll + false + + + $(GameAssemblyPath)\Assembly-CSharp.dll + false + + + + diff --git a/src/HomuraHimeAudioMod/Patches/AudioDuckingPatch.cs b/src/HomuraHimeAudioMod/Patches/AudioDuckingPatch.cs new file mode 100644 index 0000000..897dfac --- /dev/null +++ b/src/HomuraHimeAudioMod/Patches/AudioDuckingPatch.cs @@ -0,0 +1,19 @@ +using HarmonyLib; + +namespace HomuraHimeAudioMod.Patches +{ + /// + /// Patches for audio ducking system improvements. + /// TO BE IMPLEMENTED AFTER PHASE 2 CODE ANALYSIS + /// + 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 + } + } +} diff --git a/src/HomuraHimeAudioMod/Patches/EnemyAudioPatch.cs b/src/HomuraHimeAudioMod/Patches/EnemyAudioPatch.cs new file mode 100644 index 0000000..1c83f55 --- /dev/null +++ b/src/HomuraHimeAudioMod/Patches/EnemyAudioPatch.cs @@ -0,0 +1,19 @@ +using HarmonyLib; + +namespace HomuraHimeAudioMod.Patches +{ + /// + /// Patches for enemy behavior audio indicator improvements. + /// TO BE IMPLEMENTED AFTER PHASE 2 CODE ANALYSIS + /// + 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 + } + } +} diff --git a/src/HomuraHimeAudioMod/Patches/VoiceManagerPatch.cs b/src/HomuraHimeAudioMod/Patches/VoiceManagerPatch.cs new file mode 100644 index 0000000..25beaad --- /dev/null +++ b/src/HomuraHimeAudioMod/Patches/VoiceManagerPatch.cs @@ -0,0 +1,19 @@ +using HarmonyLib; + +namespace HomuraHimeAudioMod.Patches +{ + /// + /// Patches for voice limit and voice manager improvements. + /// TO BE IMPLEMENTED AFTER PHASE 2 CODE ANALYSIS + /// + 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 + } + } +} diff --git a/src/HomuraHimeAudioMod/Plugin.cs b/src/HomuraHimeAudioMod/Plugin.cs new file mode 100644 index 0000000..8dbc58b --- /dev/null +++ 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(); + } + } +} diff --git a/src/HomuraHimeAudioMod/Properties/AssemblyInfo.cs b/src/HomuraHimeAudioMod/Properties/AssemblyInfo.cs new file mode 100644 index 0000000..ed5d2c3 --- /dev/null +++ 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")]