# 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 |