# 機能設計書 47-Retrigger

## 概要

本ドキュメントは、K-ShootMania のプレイ画面におけるRetrigger（リトリガー）エフェクト機能の設計を記述する。regawo.dllを使用し、8/12/16/24/32分音符単位のリトリガーエフェクトを楽曲にリアルタイムで適用する機能である。

### 本機能の処理概要

**業務上の目的・背景**：Retriggerは音楽のある短い区間を繰り返し再生（スタッター）するエフェクトであり、EDM等のジャンルで頻繁に使用される。FXロングノートに割り当てられ、プレイヤーがFXボタンを押下している間にエフェクトが適用されることで、ゲームプレイと楽曲演出の連動を実現する。

**機能の利用シーン**：プレイ画面でFXロングノートにRetriggerエフェクト（FX_RE8〜FX_RE32）が割り当てられている場合、ノート押下中にregawo.dllのVSTプラグインとしてリトリガーエフェクトが適用される。

**主要な処理内容**：
1. applyVSTEffects関数でfl_Retr=1の場合、regawo.dllをVSTプラグインとしてロード（BASS_VST_ChannelSetDSP）
2. 初期パラメータ設定: パラメータ1=0.0（周期）、パラメータ2=0.70（ゲイン減衰）、パラメータ29=1.0（ByPass）
3. FXエフェクト開始時: ByPassを0.0に解除し、周期をBPMに基づいて設定
4. 周期計算: `60.0*4.0*1000.0/bpmfx/10.0/retr_now`（retr_nowは音符分割数）
5. リトリガートリガー更新: 拍の半分間隔（UNIT_MEASURE_2）でパラメータ19にタイミング差分を設定
6. FXエフェクト終了時: ByPassを1.0に設定し、周期を0にリセット

**関連システム・外部連携**：regawo.dll（VSTプラグイン）、BASS Audio Library、bass_vst.dll

**権限による制御**：特になし。譜面にRetriggerエフェクトが含まれる場合に自動的に有効化。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 5 | ゲームプレイ画面 | 主画面 | regawo.dllによる8/12/16/24/32分音符単位のリトリガーエフェクト適用 |

## 機能種別

リアルタイムオーディオエフェクト処理

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| fl_Retr | 整数 | Yes | Retriggerエフェクト使用フラグ | 0または1 |
| feffectnow | 整数配列 | Yes | L/R各レーザーの現在FXエフェクトID | FX_RE8〜FX_RE32の範囲 |
| feffectparam | 整数配列 | Yes | FXエフェクトのパラメータ（音符分割数） | 8,12,16,24,32 |
| bpmfx | 整数 | Yes | 現在のBPM*1000 | 正の整数 |
| retr_now | 整数 | No | 現在のRetrigger音符分割数 | 0=無効, 8/12/16/24/32 |

### 入力データソース

- 譜面ファイル（.ksh）のFXロングノート定義
- processAudioEffects関数でのFXエフェクト状態

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| hFX_Retr | 整数 | RetriggerのVSTハンドル |
| retr_now | 整数 | 現在のRetrigger分割数 |

### 出力先

- BASSオーディオエンジンのVSTエフェクトチェーン

## 処理フロー

### 処理シーケンス

```
1. VSTプラグインロード（applyVSTEffects）
   └─ hFX_Retr = BASS_VST_ChannelSetDSP(mid.0, regawo.dll, 0, 25)
   └─ パラメータ初期設定: 1=0.0, 2=0.70, 29=1.0(ByPass)
2. BPM変化時の周期更新
   └─ retr_now>0の場合: パラメータ1 = 60*4*1000/bpmfx/10/retr_now
3. トリガー更新（拍の半分間隔）
   └─ retr_beat変化時: パラメータ19にタイミング差分dstatを設定
   └─ dstat = c2tf(拍頭位置) - double(t+laserdelay0+tfx_diff)
4. FXエフェクト開始
   └─ feffectnow.cnt >= FX_RE8 かつ <= FX_RE32 の場合
   └─ ByPass(29) = 0.0, パラメータ1 = 周期値, retr_now = feffectparam.cnt
5. FXエフェクト終了
   └─ 前フレームがRetriggerで現フレームがRetriggerでない場合
   └─ ByPass(29) = 1.0, パラメータ1 = 0, retr_now = 0
```

### フローチャート

```mermaid
flowchart TD
    A[applyVSTEffects: regawo.dllロード] --> B[初期パラメータ設定]
    B --> C[毎フレーム: processAudioEffects]
    C --> D{BPM変化?}
    D -->|Yes| E[周期パラメータ更新]
    D -->|No| F{retr_beat変化?}
    E --> F
    F -->|Yes| G[パラメータ19にdstat設定]
    F -->|No| H{feffectnow変化?}
    G --> H
    H -->|開始| I[ByPass=0.0, 周期設定]
    H -->|終了| J[ByPass=1.0, 周期=0]
    H -->|変化なし| K[次フレームへ]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-47-01 | 周期計算 | period = 60*4*1000/bpmfx/10/retr_now | retr_now > 0 |
| BR-47-02 | ByPass制御 | エフェクト有効時0.0、無効時1.0 | パラメータ29 |
| BR-47-03 | VSTプライオリティ | Retriggerのプライオリティは25 | applyVSTEffects |
| BR-47-04 | ゲイン減衰 | 初期パラメータ2=0.70 | 初期設定時 |
| BR-47-05 | トリガー間隔 | UNIT_MEASURE_2（半拍）間隔でトリガー更新 | processAudioEffects |

### 計算ロジック

- Retrigger周期（パラメータ1）: `60.0 * 4.0 * 1000.0 / bpmfx / 10.0 / retr_now`
- トリガータイミング差分: `dstat = c2tf(拍頭カウント位置) - double(t + laserdelay0 + tfx_diff)`
- パラメータ19への設定: `maxf(minf(dstat / 10000.0, 1.0), 0.0)`

## データベース操作仕様

本機能ではデータベース操作は発生しない。

## エラー処理

### エラーケース一覧

BASS_VST_SetParam_Rはエラー時に最大5回リトライする（bass_vst.as 16-21行目）。

### リトライ仕様

BASS_VST_SetParam_R内で、BASS_ErrorGetCode()!=0の場合に最大5回リトライする。

## トランザクション仕様

該当なし。

## パフォーマンス要件

- VSTプラグインの処理はオーディオスレッドで実行されるため、DSP処理が音切れを起こさないこと

## セキュリティ考慮事項

特になし。

## 備考

- regawo.dllはRetrigger/Gate/Echo/Wobbleの4種類のエフェクトを兼用するVSTプラグインである
- パラメータ29はregawo.dllのByPassパラメータとして共通的に使用される
- パラメータ19はトリガータイミング同期用のパラメータ
- FX_RE8=8分音符, FX_RE12=12分音符, FX_RE16=16分音符, FX_RE24=24分音符, FX_RE32=32分音符

---

## コードリーディングガイド

本機能を理解するために参照すべきファイルと、推奨する読み解き順序を以下に示す。

### 推奨読解順序

#### Step 1: VSTプラグインロードを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | play_audio_effects.hsp | `src/scene/play/play_audio_effects.hsp` | applyVSTEffects関数内のRetrigger初期化（228-233行目） |

**主要処理フロー**:
- **229行目**: `hFX_Retr=BASS_VST_ChannelSetDSP(mid.0,dir_default+"\\lib\\regawo.dll",0,25)` でVSTロード
- **230-232行目**: 初期パラメータ設定（周期0.0、ゲイン0.70、ByPass 1.0）

#### Step 2: BPM連動更新を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | play_audio_effects.hsp | `src/scene/play/play_audio_effects.hsp` | processAudioEffects内のBPM変化時処理（401-407行目） |

**主要処理フロー**:
- **405-407行目**: BPM変化時にretr_now>0であれば、周期パラメータを再計算

#### Step 3: FXエフェクト切替を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | play_audio_effects.hsp | `src/scene/play/play_audio_effects.hsp` | feffectnow変化時のRetrigger ON/OFF処理（617-718行目） |

**主要処理フロー**:
- **617-621行目**: Retrigger終了時（feffectp=RE*かつfeffectnow!=RE*）: ByPass=1.0、周期=0、retr_now=0
- **714-718行目**: Retrigger開始時（feffectnow=RE*）: ByPass=0.0、周期設定、retr_now設定

### プログラム呼び出し階層図

```
start_play
    +-- applyVSTEffects
    |       +-- BASS_VST_ChannelSetDSP(regawo.dll, priority=25) -> hFX_Retr
    |       +-- 初期パラメータ設定
    |
    +-- on_update_play (毎フレーム)
            +-- processAudioEffects
                    +-- BPM変化: 周期再計算
                    +-- retr_beat変化: パラメータ19更新
                    +-- feffectnow変化: ON/OFF切替
```

### データフロー図

```
[入力]                      [処理]                           [出力]

譜面FXロングノート          feffectnow判定                   regawo.dll VSTパラメータ
  FX_RE8-FX_RE32 -------->  Retrigger ON/OFF

BPM値                       周期計算                         パラメータ1(周期)
  bpmfx ------------------>  60*4*1000/bpmfx/10/retr_now     パラメータ19(トリガー)
                                                             パラメータ29(ByPass)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| play_audio_effects.hsp | `src/scene/play/play_audio_effects.hsp` | ソース | applyVSTEffects, processAudioEffects |
| bass_vst.as | `src/bass_vst.as` | ソース | BASS_VST_ChannelSetDSP, BASS_VST_SetParam_R APIバインディング |
| regawo.dll | `lib/regawo.dll` | DLL | Retrigger/Gate/Echo/Wobble VSTプラグイン |
