# 機能設計書 93-キー音再生

## 概要

本ドキュメントは、K-Shoot MANIAにおけるバージョン別最大ポリフォニー制御付きのキー音再生機能の設計を記述する。

### 本機能の処理概要

本機能は、キー音ライブラリ（No.92）に登録されたキー音をプレイ中にリアルタイムで再生する機能である。ksmcore.dllのPlayKeySound関数を介して再生し、譜面バージョンに応じた最大同時発音数（ポリフォニー）制御を行う。

**業務上の目的・背景**：音楽ゲームにおいてボタン押下時にキー音（打鍵音、クラップ音等）を再生することで、プレイヤーの操作に対するフィードバックを提供する。譜面バージョン171以降はポリフォニー数が1に制限され、旧バージョンは最大10の同時発音を許容する。

**機能の利用シーン**：ゲームプレイ画面(SCENE_PLAY)においてBT/FXノートの判定成功時、およびAUTOプレイ時にキー音が再生される。

**主要な処理内容**：
1. getKeySoundFromLibraryでキー音ポインタを取得
2. PlayKeySound(ksmcore.dll)で指定音量で再生
3. ポリフォニー制御はCreateKeySound時に設定された最大同時発音数に基づきDLL側で管理

**関連システム・外部連携**：ksmcore.dllのPlayKeySound関数。キー音ライブラリ管理（No.92）に依存する。

**権限による制御**：特になし。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 5 | ゲームプレイ画面 | 主画面 | バージョン別最大ポリフォニー制御付きのBT/FXキー音再生 |

## 機能種別

オーディオ再生 / リアルタイム処理

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| pKeySound | int | Yes | KeySoundオブジェクトへのポインタ | 0(NULL)の場合は再生しない |
| volume | double | Yes | 再生音量(0.0~1.0) | なし |

### 入力データソース

- キー音ポインタ: getKeySoundFromLibrary（No.92）から取得
- 音量: mastervol変数(マスターボリューム)やcsongvol変数(楽曲ボリューム)から算出

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| 音声出力 | オーディオストリーム | スピーカーへの音声出力 |

### 出力先

オーディオデバイス（スピーカー/ヘッドフォン）

## 処理フロー

### 処理シーケンス

```
1. BT/FXノートの判定成功検出
   └─ play_button_note.hspでCRITICAL/NEAR判定
2. 該当ノートに紐づくキー音名を取得
   └─ 譜面データの配列から取得
3. getKeySoundFromLibraryでポインタ取得
   └─ ハッシュマップから検索
4. PlayKeySound(pKeySound, volume)で再生
   └─ ksmcore.dllが内部でポリフォニー制御
```

### フローチャート

```mermaid
flowchart TD
    A[ノート判定成功] --> B[キー音名取得]
    B --> C[getKeySoundFromLibrary]
    C --> D{ポインタ != 0?}
    D -->|Yes| E[PlayKeySound: ksmcore.dll]
    D -->|No| F[再生スキップ]
    E --> G[ポリフォニー制御: DLL内部]
    G --> H[オーディオ出力]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-93-01 | バージョン別ポリフォニー | ver>=171: 最大1音、ver<171: 最大10音の同時発音 | CreateKeySound時に設定 |
| BR-93-02 | NULL安全性 | ポインタが0の場合は再生をスキップする | PlayKeySound呼び出し前 |

### 計算ロジック

- ポリフォニー数: `ver >= 171 ? 1 : 10`（key_sound.as 42-46行目で決定）

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

本機能ではデータベースは使用しない。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| N/A | NULL参照 | getKeySoundFromLibraryが0を返した場合 | 再生をスキップ |

### リトライ仕様

特になし。

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

特になし。

## パフォーマンス要件

リアルタイムの音声再生が要求される。判定時点から音声出力までの遅延を最小限に保つ必要がある。

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

特になし。

## 備考

- キー音再生はksmcore.dllのPlayKeySound関数で行われ、HSP側からはポインタと音量のみを渡す
- ポリフォニー制御はDLL内部で管理されるため、HSP側での制御は不要

---

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

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

### 推奨読解順序

#### Step 1: データ構造を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | ksmcore.as | `src/ksmcore.as` | PlayKeySound関数の定義(11行目): int pKeySound, double volume |

**読解のコツ**: HSP3の`#func`は返値なしのDLL関数、`#cfunc`は返値ありのDLL関数を定義する。

#### Step 2: エントリーポイントを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | key_sound.as | `src/audio/key_sound.as` | getKeySoundFromLibrary(90-96行目): ライブラリからポインタ取得 |

**主要処理フロー**:
1. **91行目**: HashCheckKeyで存在確認
2. **96行目**: s_keySoundLibraryからポインタ返却

#### Step 3: 再生処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | ksmcore.as | `src/ksmcore.as` | PlayKeySound(11行目): DLL関数の呼び出し |

**主要処理フロー**:
- **11行目**: `#func PlayKeySound "PlayKeySound" int, double` - ポインタと音量でDLL関数呼び出し

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

```
play_button_note.hsp (ノート判定)
    |
    +-- getKeySoundFromLibrary(keySound名)
    |       └── HashCheckKey → ポインタ返却
    |
    └── PlayKeySound(pKeySound, volume)
            └── ksmcore.dll内部処理（ポリフォニー制御含む）
```

### データフロー図

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

ノート判定結果 ──────> キー音名取得 ───────> getKeySoundFromLibrary
                                                  |
                                                  v
音量パラメータ ──────> PlayKeySound ──────> オーディオデバイス
                      (ksmcore.dll)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| key_sound.as | `src/audio/key_sound.as` | ソース | getKeySoundFromLibraryによるポインタ取得 |
| ksmcore.as | `src/ksmcore.as` | ソース | PlayKeySoundのDLL定義 |
| ksmcore.dll | `ksmcore.dll` | DLL | キー音再生の実装（ポリフォニー制御含む） |
| play_button_note.hsp | `src/scene/play/play_button_note.hsp` | ソース | BT/FXノート判定時のキー音再生呼び出し元 |
