# 機能設計書 94-レーザースラム音

## 概要

本ドキュメントは、K-Shoot MANIAにおける直角レーザー（スラム）操作時に再生される5種類の効果音管理・再生機能の設計を記述する。

### 本機能の処理概要

本機能は、直角レーザー（スラム）操作時に通常/下向き/上向き/スウィング/ミュートの5種類の効果音を再生する機能である。laser_slam_soundモジュールとして独立しており、キー音と同様にksmcore.dllのKeySound機構を利用する。

**業務上の目的・背景**：K-Shoot MANIAのプレイ画面でレーザーの直角操作(スラム)が行われた際に、操作の種類に応じた適切な効果音を再生することで、プレイヤーへの聴覚フィードバックを提供する。

**機能の利用シーン**：ゲームプレイ画面(SCENE_PLAY)において、レーザーノートの判定処理で直角レーザーが検出された際にplayLaserSlamSoundが呼び出される。

**主要な処理内容**：
1. initLaserSlamSoundModule: モジュール初期化(dir_default保存)
2. loadLaserSlamSounds: 5種類の効果音ファイル読み込み(バージョン別ポリフォニー制御)
3. playLaserSlamSound: 指定種別の効果音を指定音量で再生
4. destroyLaserSlamSounds: 全効果音の破棄(onexit自動呼び出し)

**関連システム・外部連携**：ksmcore.dllのCreateKeySound/DestroyKeySound/PlayKeySound関数を使用。

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

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 5 | ゲームプレイ画面 | 主画面 | loadLaserSlamSoundsによる通常/下向き/上向き/スウィング/ミュートの直角レーザー音再生 |

## 機能種別

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

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| p1 (initLaserSlamSoundModule) | str | Yes | dir_defaultパス | なし |
| p1 (loadLaserSlamSounds) | int | Yes | ksh譜面のverフィールド整数値 | なし |
| p1 (playLaserSlamSound) | int | Yes | スラム音種別ID(0-4) | 範囲外の場合は無視 |
| p2 (playLaserSlamSound) | double | Yes | 音量(0.0~1.0) | なし |

### 入力データソース

- バージョン情報: 譜面ファイルのverフィールドから取得
- スラム種別: レーザー判定処理から取得
- 音声ファイル: se\ディレクトリ内の.wavファイル

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| s_laserSlamKeySounds | int配列(5要素) | 5種類のKeySoundオブジェクトポインタ |
| 音声出力 | オーディオストリーム | スピーカーへの音声出力 |

### 出力先

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

## 処理フロー

### 処理シーケンス

```
1. initLaserSlamSoundModule(dir_default): モジュール初期化
   └─ s_dirDefaultとs_maxPolyphony(-1)を設定
2. loadLaserSlamSounds(ver): 効果音読み込み
   └─ 前回と異なるポリフォニーの場合のみ再読み込み
   └─ 5つの.wavファイルをCreateKeySoundで生成
3. playLaserSlamSound(typeId, volume): 効果音再生
   └─ 範囲チェック後にPlayKeySoundで再生
4. destroyLaserSlamSounds: 全破棄(onexit)
   └─ 全要素をDestroyKeySoundで破棄
```

### フローチャート

```mermaid
flowchart TD
    A[initLaserSlamSoundModule] --> B[loadLaserSlamSounds]
    B --> C{ポリフォニー変更?}
    C -->|Yes| D[5種類のwavをCreateKeySound]
    C -->|No| E[スキップ]
    D --> F[プレイ中: 直角レーザー検出]
    E --> F
    F --> G[playLaserSlamSound: typeId, volume]
    G --> H{typeId範囲内?}
    H -->|Yes| I{ポインタ != 0?}
    H -->|No| J[無視]
    I -->|Yes| K[PlayKeySound]
    I -->|No| J
    K --> L[オーディオ出力]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-94-01 | 5種類のスラム音 | chokkaku.wav(通常), chokkaku_down.wav(下向き), chokkaku_up.wav(上向き), chokkaku_swing.wav(スウィング), chokkaku_mute.wav(ミュート) | loadLaserSlamSounds時 |
| BR-94-02 | バージョン別ポリフォニー | ver>=171: 最大1音、ver<171: 最大10音 | CreateKeySound時 |
| BR-94-03 | 再読み込み条件 | 前回と異なるポリフォニー数の場合のみ再読み込み | s_maxPolyphonyの比較 |
| BR-94-04 | 範囲外チェック | typeId < 0 または >= 5 の場合は再生しない | playLaserSlamSound内 |

### 計算ロジック

- スラム音種別ID: 0=通常, 1=下向き, 2=上向き, 3=スウィング, 4=ミュート

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

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

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| N/A | 読み込みエラー | CreateKeySoundが失敗した場合 | エラーダイアログ表示 |
| N/A | 範囲外ID | typeIdが0-4の範囲外 | 無視して処理続行 |

### リトライ仕様

特になし。

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

特になし。

## パフォーマンス要件

直角レーザー操作の判定から音声出力までの遅延を最小限に保つ必要がある。

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

特になし。

## 備考

- スラム音ファイルはse\ディレクトリ直下に配置される(se\note\ではない)
- laser_slam_soundモジュールは#moduleでカプセル化されている

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | laser_slam_sound.as | `src/audio/laser_slam_sound.as` | s_laserSlamKeySounds配列(46行目): 5要素のKeySoundポインタ配列 |
| 1-2 | laser_slam_sound.as | `src/audio/laser_slam_sound.as` | s_maxPolyphony(12行目): 現在のポリフォニー設定値 |
| 1-3 | ksmcore.as | `src/ksmcore.as` | CreateKeySound/PlayKeySoundの定義(9-11行目) |

**読解のコツ**: `notesel`/`noteget`はHSP3のメモ帳命令で、改行区切りの文字列を行単位で操作する。filenamesStrに5行分のファイル名を入れ、ループで各行を取り出す。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | laser_slam_sound.as | `src/audio/laser_slam_sound.as` | initLaserSlamSoundModule(10-13行目): 初期化 |

**主要処理フロー**:
1. **11行目**: s_dirDefaultにパス保存
2. **12行目**: s_maxPolyphony = -1（初回読み込みを強制）

#### Step 3: 効果音読み込み処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | laser_slam_sound.as | `src/audio/laser_slam_sound.as` | loadLaserSlamSounds(32-60行目): 5種類の音声ファイル読み込み |

**主要処理フロー**:
- **34行目**: ポリフォニー変更チェック
- **38-42行目**: 5つのファイル名をnotesel用文字列に定義
- **47-58行目**: 各ファイルに対してCreateKeySoundを実行

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | laser_slam_sound.as | `src/audio/laser_slam_sound.as` | playLaserSlamSound(68-78行目): 種別IDと音量で再生 |
| 4-2 | laser_slam_sound.as | `src/audio/laser_slam_sound.as` | destroyLaserSlamSounds(80-85行目): onexit時の破棄 |

**主要処理フロー**:
- **70行目**: typeIDの範囲チェック(0~length-1)
- **75-76行目**: ポインタ!=0の場合にPlayKeySoundを呼び出し

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

```
プレイ画面初期化
    |
    +-- initLaserSlamSoundModule(dir_default)
    |
    +-- loadLaserSlamSounds(ver)
    |       +-- getMaxPolyphonyForVersion(ver)
    |       └── CreateKeySound(filename, maxPoly, &ptr) x5
    |
    +-- playLaserSlamSound(typeId, volume)  ※プレイ中
    |       └── PlayKeySound(ptr, volume)
    |
    +-- destroyLaserSlamSounds()  ※onexit時
            └── DestroyKeySound(ptr) x5
```

### データフロー図

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

se\chokkaku*.wav ───────> loadLaserSlamSounds ──────> s_laserSlamKeySounds[5]
(5種類のWAV)               |
                           v
レーザー判定結果 ─────> playLaserSlamSound ──────> オーディオデバイス
(typeId, volume)          |
                     PlayKeySound(ksmcore.dll)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| laser_slam_sound.as | `src/audio/laser_slam_sound.as` | ソース | レーザースラム音管理モジュール本体 |
| ksmcore.as | `src/ksmcore.as` | ソース | CreateKeySound/PlayKeySound/DestroyKeySoundの定義 |
| ksmcore.dll | `ksmcore.dll` | DLL | キー音オブジェクトの実装 |
| chokkaku.wav | `se/chokkaku.wav` | 音声ファイル | 通常スラム音 |
| chokkaku_down.wav | `se/chokkaku_down.wav` | 音声ファイル | 下向きスラム音 |
| chokkaku_up.wav | `se/chokkaku_up.wav` | 音声ファイル | 上向きスラム音 |
| chokkaku_swing.wav | `se/chokkaku_swing.wav` | 音声ファイル | スウィングスラム音 |
| chokkaku_mute.wav | `se/chokkaku_mute.wav` | 音声ファイル | ミュートスラム音 |
