# VoiceModFramework

**Slay the Spire 2 向けのキャラクターボイス再生フレームワークです。**

ゲーム内のさまざまなイベントに連動してキャラクターのボイスを自動再生し、字幕を吹き出しで表示します。ボイスパックの追加に DLL は不要で、`voicepack.json` と音声ファイルを置くだけで対応キャラクターのボイスが有効になります。他のモッダーが独自キャラクターのボイスパックを公開する場合も、このフレームワークへの依存だけで完結します。

---

## 機能

- **設定いらずのボイスパック** — `voicepack.json` と音声ファイルを置くだけで自動検出・自動登録。ボイスパック側に DLL 不要。
- **20 種類以上の自動トリガー** — カード使用、HP ダメージ（完全・貫通）、完全ブロック、バフ取得、デバフ受け・付与、スター獲得、敵撃破、戦闘開始・勝利・敗北、低 HP（1 戦闘 1 回）、アイドル（プレイヤーターン中）、ポーション使用、カード強化、ショップ購入、宝箱など。
- **部屋タイプ対応** — `boss_start/`・`elite_start/`・`boss_victory/`・`elite_victory/` の個別フォルダを用意でき、存在しない場合は `combat_start/`・`victory/` に自動フォールバック。
- **カード固有ボイス** — `card_{カードID}/` フォルダを追加すると、そのカード専用ボイスを再生。
- **字幕表示** — キャラクターアイコン付きの吹き出しオーバーレイ。日本語・英語・簡体字中国語・韓国語に対応。
- **ネイティブバブルモード** — ゲーム本来のキャラクター頭上吹き出し（NSpeechBubbleVfx）を使う表示モードも選択可能。
- **カスタムフォント** — 言語別に `.ttf` / `.otf` フォントを指定でき、日本語・中国語・韓国語など各スクリプトを正しく描画。
- **吹き出し画像置換** — ネイティブバブルのスプライトを独自画像（PNG/JPG/WEBP）に差し替え可能。
- **リッチテキスト対応** — 字幕 JSON でゴドー 4 の BBCode タグ（太字・カラー・波・揺れ・虹色など）が使用可能。
- **カテゴリ別アイコン** — カテゴリフォルダ内に `icon.png` を置くと、そのトリガー時だけアイコンを差し替え。
- **タイプライター演出** — 文字を 1 文字ずつ表示するエフェクト。速度は cps（文字/秒）で設定。
- **音声キャッシュ・連続再生回避** — ランの開始時にファイルを事前デコード。同じフォルダから同じファイルは連続して再生しない。
- **ポーズ連動** — ゲームのポーズに合わせて音声を自動停止・再開。
- **充実したゲーム内設定** — 音量（dB）、発動確率（%）、カテゴリ別 ON/OFF、アイドル発動秒数、字幕の表示位置（四隅から選択）、スケール、フェード時間など。

---

## 動作環境

- Slay the Spire 2（早期アクセス）
- 対応 Mod ローダー

---

## インストール

1. `VoiceModFramework` フォルダをゲームの `mods/` ディレクトリに配置します。
2. ゲームを起動します。すべての Mod フォルダが自動スキャンされ、`voicepack*.json` が見つかると自動でロードされます。

追加の設定は不要です。各種設定はゲーム内の Mod 設定パネルから変更できます。

---

## ボイスパックの作り方（簡易版）

DLL 不要で公開できます。

1. `mods/` 内にフォルダを作成します（例：`MyCharacterVoice/`）。
2. `voicepack.json` を作成します：
   ```json
   {
     "character_id": "キャラクターID",
     "voices_dir": "voices"
   }
   ```
3. 音声ファイル（`.ogg` または `.mp3`）をカテゴリサブフォルダに置きます：
   ```
   voices/
     card/          ← どのカードでも再生
     damage/        ← HP ダメージ時
     combat_start/  ← 戦闘開始時
     victory/       ← 勝利時
     ...
   ```
4. ゲームを起動すると自動検出され、対象キャラクターのランで有効になります。

キャラクター ID の確認は**設定 → VoiceMod → ユーティリティ → character_ids.json を出力**で行えます。

フォント置き換え・吹き出し画像置換・リッチテキスト・API フックなど上級機能は **[上級モッダー向けガイド]** を参照してください。

---

## 他のモッダー向け（DLL ベース登録）

DLL を持つ Mod の場合、`ModEntry.Init()` から直接登録することもできます：

```csharp
VoiceModApi.Register(new VoicePackConfig
{
    CharacterId   = "MYCHARACTER",
    VoicesDir     = Path.Combine(modDir, "voices"),
    SubtitleDir   = Path.Combine(modDir, "voices"),
    IconPath      = Path.Combine(modDir, "icon.png"),
    SubtitleColor = "#FFCC88",
});
```

独自の Harmony パッチからボイスを発火することも可能です：
```csharp
VoiceModApi.PlayCurrentPackVoice("my_custom_category");
```

詳細は **[上級モッダー向けガイド]** を参照してください。

---

## 利用規約

このフレームワークに依存するボイスパックの作成・公開は自由です。クレジット表記は任意です。
