diff --git a/docs/FMOD_MODIFICATION_GUIDE_PHASE3.md b/docs/FMOD_MODIFICATION_GUIDE_PHASE3.md new file mode 100644 index 0000000..6682436 --- /dev/null +++ b/docs/FMOD_MODIFICATION_GUIDE_PHASE3.md @@ -0,0 +1,264 @@ +# Phase 3: FMOD Bank Modifications Guide + +## Overview +This phase covers extracting and modifying FMOD audio banks using FMOD Studio and AssetRipper. + +**Prerequisites:** +- FMOD Studio 2.02.x installed (free from fmod.com) +- AssetRipper installed +- Game installed at: `C:\apps\steam\steamapps\common\Homura Hime\` + +--- + +## Step 1: Extract FMOD Banks with AssetRipper + +### 1.1 Launch AssetRipper +``` +Location: C:\projects\HomuraHime-Mods\tools\AssetRipper\AssetRipper.exe +``` + +### 1.2 Load HomuraHime +1. Click **File** → **Load** (or drag folder) +2. Navigate to: `C:\apps\steam\steamapps\common\Homura Hime\HomuraHime_Data\` +3. Select the folder and click **Open** + +### 1.3 Export Settings +1. Click **File** → **Export** +2. Choose **Resources** (not Asset Directories) +3. Set output path: `C:\projects\HomuraHime-Mods\extracted_assets\` + +### 1.4 Locate FMOD Banks +After export, find banks at: +``` +C:\projects\HomuraHime-Mods\extracted_assets\StreamingAssets\FMOD\Desktop\ +``` + +--- + +## Step 2: Open Banks in FMOD Studio + +### 2.1 Launch FMOD Studio +``` +Location: C:\Program Files\FMOD Studio\FMOD Studio.exe +``` + +### 2.2 Open Project (or Banks Directly) +**Option A:** If you have the original FMOD project (unlikely for commercial game): +- File → Open Project → Select `.fprojekt` file + +**Option B:** Open bank files directly: +- File → Open Bank → Select `Master.bank` from the extracted folder +- FMOD will automatically load related banks + +### 2.3 Bank Organization +In FMOD Studio, you'll see: +- **Events**: Sound events (grouped by banks: SFX, Ambience, BGM, Voice) +- **Audio Tables**: Banks, VCA groups, snapshots +- **Mixer**: Master output with routing + +--- + +## Step 3: Voice Limit Improvements + +### 3.1 Find Problematic Events +Search for events with high polyphony: +1. In FMOD Studio, select **SFX.bank** in the Banks panel +2. Look at event properties in the Inspector +3. Check **Maximum Instances** ( polyphony) + +### 3.2 Adjust Voice Aging +For events that cause glitches: + +1. Right-click event → **Properties** +2. Go to **Voices** tab +3. Settings to adjust: + ``` + Max Instances: 16 (from default 32) + Voice Stealing: Steal Oldest + Voice Aging: 1.0 seconds (faster cleanup) + ``` + +### 3.3 Key Events to Check +In `SFX.bank`: +- Attack impact sounds (often triggered rapidly) +- Footstep/landing sounds (PreLoad banks) +- Enemy alert/warning sounds +- UI feedback sounds + +--- + +## Step 4: Audio Ducking Improvements + +### 4.1 Access Mixer +1. Click **Mixer** tab in FMOD Studio +2. You'll see VCA groups and the Master bus + +### 4.2 Configure Ducking Groups +Look for: +- **Speech** (Voice channel) +- **SFX** (Sound effects) +- **Music** (BGM) + +### 4.3 Adjust Ducking Parameters +For the Master or speech bus: +1. Right-click → **Add Effect** → **Duck** +2. Configure: + ``` + Threshold: -20 dB (triggers at this volume) + Rate: 100% (fade speed) + Attack: 10 ms (fast attack) + Release: 200 ms (slower release) + ``` + +### 4.4 Create/Modify Snapshots +Snapshots control ducking behavior: +1. In the **Audio Tables** panel, select **Snapshots** +2. Find existing battle/start snapshots +3. Modify duck amounts: + ``` + Music Duck Amount: -12 dB (not too aggressive) + SFX Duck Amount: -6 dB + ``` + +--- + +## Step 5: Enemy Behavior Indicator Improvements + +### 5.1 Locate Enemy Audio Events + +**In `Ambience.bank`:** +- `enemy_idle_loop` - Enemy ambient when not engaged +- `enemy_alert` - Enemy noticing player +- `enemy_chase` - Enemy pursuing + +**In `SFX.bank`:** +- Attack indicator sounds +- Danger/warning cues + +### 5.2 Increase Volume on Behavior Sounds + +1. Find enemy-related events +2. Select the event → Inspector +3. **Volume** slider: Increase by 3-6 dB + ``` + Before: 0.0 dB + After: +3.0 dB to +6.0 dB + ``` + +### 5.3 Add Pitch Variation + +For more distinct enemy states: + +1. Select enemy event (e.g., alert) +2. Add **Pitch** automation or randomizer +3. Set variation: + ``` + Center: 0 semitones + Range: ±2 semitones random + ``` + +### 5.4 Add 3D Positioning + +For directional audio: + +1. Select event → **3D** checkbox +2. Configure: + ``` + Min Distance: 1.0 m + Max Distance: 20.0 m + Rolloff: Linear + ``` +3. This makes enemy sounds come from their position + +### 5.5 Create State Layers + +For distinct enemy behavior indicators, add parameters: + +1. Right-click event → **Add Parameter** +2. Name: `EnemyState` +3. Values: `0=Idle, 1=Alert, 2=Attacking` +4. Add automation for volume/effect per state + +--- + +## Step 6: Reimport Modified Banks + +### 6.1 Save Changes +1. In FMOD Studio: **File** → **Save** +2. Banks will auto-update in the project folder + +### 6.2 Export Banks +1. **File** → **Export** → **banks** +2. Choose the extracted `Desktop\` folder +3. Confirm overwrite + +### 6.3 Verify Export +Check that modified `.bank` files have new timestamps. + +--- + +## Step 7: Backup Original Banks + +**CRITICAL - Before testing:** +``` +mkdir "C:\projects\HomuraHime-Mods\backup_banks_original" +copy "C:\projects\HomuraHime-Mods\extracted_assets\StreamingAssets\FMOD\Desktop\*.bank" + "C:\projects\HomuraHime-Mods\backup_banks_original\" +``` + +--- + +## File Locations Reference + +### Game Banks (Read-Only Backup) +``` +C:\apps\steam\steamapps\common\Homura Hime\HomuraHime_Data\StreamingAssets\FMOD\Desktop\ +``` + +### Extracted for Editing +``` +C:\projects\HomuraHime-Mods\extracted_assets\StreamingAssets\FMOD\Desktop\ +``` + +### Modified Banks (Copy to Game) +``` +C:\projects\HomuraHime-Mods\modified_banks\FMOD\Desktop\ +``` + +### Backup Original +``` +C:\projects\HomuraHime-Mods\backup_banks_original\ +``` + +--- + +## Banks to Prioritize + +| Priority | Bank | Reason | +|----------|------|--------| +| HIGH | `SFX.bank` | Contains attack/impact sounds that glitch | +| HIGH | `Ambience.bank` | Enemy behavior indicators | +| MEDIUM | `Master.bank` | Contains mixer and routing | +| MEDIUM | `Voice.bank` | May need voice limit adjustments | +| LOW | `BGM*.bank` | Background music - less critical | + +--- + +## Verification Checklist + +After modifications: +- [ ] Banks export successfully from FMOD Studio +- [ ] New bank files are in `modified_banks\` +- [ ] Original banks backed up +- [ ] Test game loads without FMOD errors +- [ ] Audio glitches reduced in combat +- [ ] Enemy indicators more audible + +--- + +## Next Steps + +After completing FMOD modifications: +- Phase 4: BepInEx plugin deployment +- Phase 5: Testing and iteration +- Phase 6: Distribution diff --git a/tools/ExtractBanks.ps1 b/tools/ExtractBanks.ps1 new file mode 100644 index 0000000..46b9f89 --- /dev/null +++ b/tools/ExtractBanks.ps1 @@ -0,0 +1,103 @@ +# HomuraHime Audio Mod - Bank Extraction Script +# Run this after installing AssetRipper to extract FMOD banks + +param( + [string]$GamePath = "C:\apps\steam\steamapps\common\Homura Hime", + [string]$OutputPath = "C:\projects\HomuraHime-Mods\extracted_assets", + [string]$BackupPath = "C:\projects\HomuraHime-Mods\backup_banks_original" +) + +$ErrorActionPreference = "Stop" + +Write-Host "HomuraHime Audio Mod - Bank Extraction Script" -ForegroundColor Cyan +Write-Host "=" * 50 + +# Check if AssetRipper exists +$AssetRipperPath = "C:\projects\HomuraHime-Mods\tools\AssetRipper\AssetRipper.exe" +if (-not (Test-Path $AssetRipperPath)) { + Write-Host "[ERROR] AssetRipper not found at: $AssetRipperPath" -ForegroundColor Red + Write-Host "Please install AssetRipper first (see docs/SETUP_PHASE1.md)" -ForegroundColor Yellow + exit 1 +} + +# Check if game path exists +$GameDataPath = Join-Path $GamePath "HomuraHime_Data\StreamingAssets\FMOD\Desktop" +if (-not (Test-Path $GameDataPath)) { + Write-Host "[ERROR] Game FMOD banks not found at: $GameDataPath" -ForegroundColor Red + Write-Host "Please verify game installation" -ForegroundColor Yellow + exit 1 +} + +Write-Host "[INFO] Game path: $GameDataPath" -ForegroundColor Green + +# Create directories +$OutputBanksPath = Join-Path $OutputPath "StreamingAssets\FMOD\Desktop" +$BackupBanksPath = $BackupPath + +New-Item -ItemType Directory -Force -Path $OutputBanksPath | Out-Null +New-Item -ItemType Directory -Force -Path $BackupBanksPath | Out-Null + +Write-Host "[INFO] Output path: $OutputBanksPath" -ForegroundColor Green +Write-Host "[INFO] Backup path: $BackupBanksPath" -ForegroundColor Green + +# List current banks +$banks = Get-ChildItem -Path $GameDataPath -Filter "*.bank" +Write-Host "[INFO] Found $($banks.Count) FMOD bank files" -ForegroundColor Cyan + +# Step 1: Backup original banks +Write-Host "`n[STEP 1] Backing up original banks..." -ForegroundColor Yellow +foreach ($bank in $banks) { + $dest = Join-Path $BackupBanksPath $bank.Name + Copy-Item -Path $bank.FullName -Destination $dest -Force + Write-Host " Backed up: $($bank.Name)" -ForegroundColor Gray +} +Write-Host "[OK] Original banks backed up" -ForegroundColor Green + +# Step 2: Launch AssetRipper for extraction +Write-Host "`n[STEP 2] Launching AssetRipper..." -ForegroundColor Yellow +Write-Host " In AssetRipper:" -ForegroundColor Cyan +Write-Host " 1. File -> Load -> Select HomuraHime_Data folder" -ForegroundColor Cyan +Write-Host " 2. File -> Export -> Resources" -ForegroundColor Cyan +Write-Host " 3. Export to: $OutputPath" -ForegroundColor Cyan +Write-Host " 4. Wait for export to complete" -ForegroundColor Cyan +Write-Host " 5. Close AssetRipper" -ForegroundColor Cyan + +Start-Process $AssetRipperPath +Write-Host "`n[PAUSE] Press Enter when AssetRipper export is complete..." -ForegroundColor Yellow +Read-Host + +# Step 3: Verify extraction +$extractedBanksPath = Join-Path $OutputPath "StreamingAssets\FMOD\Desktop" +if (Test-Path $extractedBanksPath) { + $extractedBanks = Get-ChildItem -Path $extractedBanksPath -Filter "*.bank" + Write-Host "[OK] Found $($extractedBanks.Count) extracted bank files" -ForegroundColor Green + + # List key banks + $keyBanks = @("SFX.bank", "Ambience.bank", "Master.bank", "Voice.bank") + foreach ($keyBank in $keyBanks) { + $found = $extractedBanks | Where-Object { $_.Name -eq $keyBank } + if ($found) { + Write-Host " [OK] $keyBank found ($([math]::Round($found.Length / 1MB, 2)) MB)" -ForegroundColor Green + } else { + Write-Host " [WARN] $keyBank not found" -ForegroundColor Yellow + } + } +} else { + Write-Host "[ERROR] Extraction failed - path not found: $extractedBanksPath" -ForegroundColor Red + exit 1 +} + +# Summary +Write-Host "`n" + "=" * 50 +Write-Host "Extraction Complete!" -ForegroundColor Cyan +Write-Host "" +Write-Host "Next steps:" -ForegroundColor Yellow +Write-Host " 1. Open FMOD Studio 2.02.x" -ForegroundColor Cyan +Write-Host " 2. Open banks from: $extractedBanksPath" -ForegroundColor Cyan +Write-Host " 3. Edit banks for voice limits, ducking, enemy cues" -ForegroundColor Cyan +Write-Host " 4. See docs/FMOD_MODIFICATION_GUIDE_PHASE3.md for details" -ForegroundColor Cyan +Write-Host "" +Write-Host "Current project structure:" -ForegroundColor Gray +Write-Host " extracted_assets\StreamingAssets\FMOD\Desktop\ <- Edit these banks" -ForegroundColor Gray +Write-Host " backup_banks_original\ <- Original banks (backup)" -ForegroundColor Gray +Write-Host " modified_banks\ <- Create this folder for modified banks" -ForegroundColor Gray