Ed_
7169d4533b
- 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
278 lines
6.5 KiB
Markdown
278 lines
6.5 KiB
Markdown
# 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 |
|