HomuraHime-Mods/docs/SETUP_PHASE1.md

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