# 機能設計書 3-プレイ画面

## 概要

K-Shoot MANIAのメインゲームプレイ画面の機能設計書である。譜面読み込み・ゲームロジック・オーディオ・描画・キー入力を統合するメインゲームプレイ画面であり、ゲーム体験の中核を担う。

### 本機能の処理概要

プレイ画面は、選曲画面で選択された楽曲の譜面データを読み込み、音楽と同期してノートを表示しながら、プレイヤーの入力を判定してスコアを計算するメインゲームプレイ画面である。play_init/play_update/play_draw_frameの3フェーズ構成で14個のサブモジュールに分割されている。

**業務上の目的・背景**：音楽ゲームの最も重要な画面であり、譜面表示・入力判定・スコア計算・エフェクト適用を60fps以上でリアルタイム処理する必要がある。SDVX（Sound Voltex）系のゲームシステムを再現し、BT/FXボタンとアナログレーザーの操作を統合的に扱う。

**機能の利用シーン**：選曲画面で楽曲決定後、スプラッシュ画面を経由してプレイ画面に遷移する。プレイ完了後は結果画面へ、Esc押下時は選曲画面に戻る。コースモード時は次の曲のプレイ画面へ遷移する。

**主要な処理内容**：
1. KSHフォーマット譜面ファイルの読み込みとパース（play_chart_load.hsp）
2. 音楽ファイルの読み込みと同期再生（play_audio.hsp）
3. BT/FXノート判定（play_button_note.hsp）
4. レーザーノート判定（play_laser_note.hsp）
5. スコア計算・ゲージ管理・チェーンカウント（play_game_logic.hsp）
6. ノート・背景・カメラ・エフェクトの3D描画（play_draw_frame.hsp）
7. キーボード・ジョイスティック・アナログ入力処理（play_key_input.hsp）
8. オーディオエフェクト（レーザーエフェクト、VSTエフェクト群）の適用（play_audio_effects.hsp）
9. 動画背景再生（play_video.hsp）
10. スプラッシュ画面表示（play_splash_screen.hsp）

**関連システム・外部連携**：BASS Audio Library、VSTエフェクトDLL群（bitc/flan/phas/pitc/regawo/sich/tstp）、ksmcore.dll（カメラ値計算）、kshlib.dll（Switch Audio・MD5ハッシュ）、HGIMG3（3D描画）

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

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 5 | ゲームプレイ画面 | 主画面 | play_init/play_update/play_draw_frameの3フェーズによるメインゲームプレイの統合管理 |
| 3 | 曲選択画面 | 遷移元/遷移先 | Esc押下で選曲画面へ遷移 |
| 6 | リザルト画面 | 遷移先 | プレイ完了後にSCENE_RESULTへ遷移 |

## 機能種別

リアルタイム処理・入力判定・スコア計算・描画処理・オーディオ制御

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| cnotesfile | str | Yes | 譜面ファイルパス | .ksh拡張子 |
| csongdir | str | Yes | 楽曲ディレクトリパス | 存在するディレクトリ |
| iscourse | int | No | コースモードフラグ | 0 or 1 |
| auto | int | No | オートプレイフラグ | 0 or 1 |
| judgedelay_config | int | No | 入力遅延設定(ms) | 整数 |
| analogdelay_config | int | No | レーザー遅延設定(ms) | 整数 |

### 入力データソース

- .kshファイル（KSH譜面フォーマット）
- 音楽ファイル（OGG/MP3/WAV）
- キーボード・ジョイスティック・アナログ入力デバイス

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| totalscore | int | 合計スコア（最大10,000,000） |
| critical | int | CRITICAL判定数 |
| near | int | NEAR判定数 |
| errorn | int | ERROR判定数 |
| chainmax | int | 最大チェーン数 |
| gaugenow | double | 最終ゲージ値(%) |
| scene | int | 遷移先シーンID |

### 出力先

- 画面表示（3Dノート描画、UI表示）
- グローバル変数（スコア関連変数群）
- 音声出力（楽曲・SE・エフェクト音）

## 処理フロー

### 処理シーケンス

```
1. プレイ初期化（play_init.hsp: start_play）
   ├─ ジョイスティック初期化
   ├─ タイミング計算変数の初期化
   ├─ ゲームプレイ変数の初期化（initGamePlayVariables）
   ├─ 譜面変数の初期化（initChartVariables）
   ├─ TURN設定適用（prepareTurnOptions）
   ├─ ノートモード設定適用（prepareModeOptions）
   ├─ 譜面ファイル読み込み（loadKSHChartFile）
   ├─ 譜面パラメータ解析（parseKSHChartParamLines）
   ├─ レーザースラム音読み込み
   ├─ 音楽ファイル読み込み・再生開始
   ├─ オーディオエフェクト初期化
   └─ スプラッシュ画面表示
2. プレイメインループ（play_update.hsp）
   ├─ タイミング同期処理
   ├─ キー入力処理（play_key_input.hsp）
   ├─ ノート判定処理
   │   ├─ BTノート判定（play_button_note.hsp）
   │   ├─ FXノート判定（play_button_note.hsp）
   │   └─ レーザーノート判定（play_laser_note.hsp）
   ├─ スコア・ゲージ・チェーン更新（play_game_logic.hsp）
   ├─ オーディオエフェクト処理（play_audio_effects.hsp）
   └─ 描画処理（play_draw_frame.hsp）
3. プレイ終了
   ├─ 通常終了 → SCENE_RESULT
   ├─ Esc終了 → SCENE_SELECT
   └─ コースモード → 次の曲のSCENE_PLAY
```

### フローチャート

```mermaid
flowchart TD
    A[プレイ画面開始] --> B[譜面ファイル読み込み]
    B --> C[音楽ファイル読み込み]
    C --> D[スプラッシュ画面表示]
    D --> E[メインループ開始]
    E --> F[タイミング同期]
    F --> G[キー入力処理]
    G --> H[ノート判定]
    H --> I[スコア更新]
    I --> J[描画処理]
    J --> K{楽曲終了?}
    K -->|No| L{Esc押下?}
    L -->|No| E
    L -->|Yes| M[SCENE_SELECT]
    K -->|Yes| N[SCENE_RESULT]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-01 | 判定窓 | CRITICAL: +-43ms, NEAR: +-113ms, ERROR: +-260ms | BTノート判定時 |
| BR-02 | スコア計算 | CRITICAL=+2, NEAR=+1, ERROR=0, 最大10,000,000点 | 判定確定時 |
| BR-03 | ゲージ種別 | 通常ゲージ(0%)とHARDゲージ(100%開始)の2種類 | effratetype設定 |
| BR-04 | オートプレイ | auto=1時は全ノートを自動判定 | auto変数 |
| BR-05 | コースモード継続 | コースモード時は曲終了後に次の曲へ遷移 | iscourse=1 |

### 計算ロジック

- スコア計算: `totalscore = sum(noteresult) * 10000000 / (notenum * 2)`
- ゲージ増加率: ノート種別・ゲージタイプにより異なる

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

本機能ではデータベース操作は行わない。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | 譜面不在 | cnotesfileが存在しない | エラーダイアログ表示後に選曲画面へ遷移 |
| - | 楽曲ディレクトリ不在 | csongdirが存在しない | エラーダイアログ表示後に選曲画面へ遷移 |

### リトライ仕様

リトライ処理は実装されていない。

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

トランザクション処理は適用されない。

## パフォーマンス要件

- 60fps以上のフレームレートでのリアルタイム描画
- 音楽とゲームタイマーの同期精度: 1ms以内
- 入力遅延: configurable（judgedelay_config）
- バッファ長: configurable（bufferlength, updateperiod）

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

特になし。

## 備考

- 14個のサブモジュール（.hsp）に分割されたモジュラー構造
- 3D描画にHGIMG3プラグインを使用
- VSTエフェクトDLLによるリアルタイムオーディオ処理

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | kshootmania.hsp | `kshootmania.hsp` | UNIT_MEASURE=10000（1小節あたりのカウント値）、判定関連定数 |

**読解のコツ**: `note`配列は多次元配列で、note.i.0がレーン、note.i.1がタイミング、note.i.2が種別を格納。`analog`配列はレーザー位置データ。

- **52-57行目**: UNIT_MEASURE=10000, UNIT_MEASURE_2=5000 等のタイミング定数

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | play.hsp | `src/scene/play.hsp` | 14個のサブモジュールの#include構成 |
| 2-2 | play_init.hsp | `src/scene/play/play_init.hsp` | start_playサブルーチン（初期化の全体フロー） |

**主要処理フロー**:
1. **1行目**: `#deffunc start_play` で定義
2. **3-5行目**: ジョイスティック初期化
3. **38行目**: `initGamePlayVariables` - ゲームプレイ変数初期化
4. **41行目**: `initChartVariables` - 譜面変数初期化
5. **44行目**: `prepareTurnOptions` - MIRROR/RANDOM設定
6. **47行目**: `prepareModeOptions` - ノートモード設定
7. **67行目**: `loadKSHChartFile` - 譜面読み込み
8. **71行目**: `parseKSHChartParamLines` - パラメータ解析

#### Step 3: 各処理層を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | play_chart_load.hsp | `src/scene/play/play_chart_load.hsp` | KSH譜面ファイルの読み込みとパース処理 |
| 3-2 | play_audio.hsp | `src/scene/play/play_audio.hsp` | 音楽ファイルの読み込み・再生・同期処理 |
| 3-3 | play_key_input.hsp | `src/scene/play/play_key_input.hsp` | キーボード・ジョイスティック・アナログ入力処理 |
| 3-4 | play_button_note.hsp | `src/scene/play/play_button_note.hsp` | BT/FXノート判定 |
| 3-5 | play_laser_note.hsp | `src/scene/play/play_laser_note.hsp` | レーザーノート判定 |
| 3-6 | play_game_logic.hsp | `src/scene/play/play_game_logic.hsp` | スコア・ゲージ・チェーン計算 |
| 3-7 | play_draw_frame.hsp | `src/scene/play/play_draw_frame.hsp` | 3Dノート描画・カメラ制御・背景描画 |
| 3-8 | play_audio_effects.hsp | `src/scene/play/play_audio_effects.hsp` | VSTオーディオエフェクト処理 |

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

```
kshootmania.hsp (メインループ: 1028行目 case SCENE_PLAY)
    │
    └─ start_play (src/scene/play/play_init.hsp)
           ├─ initGamePlayVariables (play_game_logic.hsp)
           ├─ initChartVariables (play_chart_load.hsp)
           ├─ prepareTurnOptions (play_game_logic.hsp)
           ├─ prepareModeOptions (play_game_logic.hsp)
           ├─ loadKSHChartFile (play_chart_load.hsp)
           ├─ parseKSHChartParamLines (play_chart_load.hsp)
           ├─ loadLaserSlamSounds (laser_slam_sound.as)
           ├─ play_update (play_update.hsp) [メインループ]
           │      ├─ processPlayTiming (play_audio.hsp)
           │      ├─ processKeyInput (play_key_input.hsp)
           │      ├─ specifyJudgmentTargetOfButtonNotes (play_button_note.hsp)
           │      ├─ specifyJudgmentTargetOfLaserNotes (play_laser_note.hsp)
           │      ├─ updateGameSystem (play_game_logic.hsp)
           │      └─ play_draw_frame (play_draw_frame.hsp)
           └─ play_splash_screen (play_splash_screen.hsp)
```

### データフロー図

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

.kshファイル ────────────────▶ loadKSHChartFile ───────────────▶ note/analog配列
                                    │
音楽ファイル ────────────────▶ BASS_StreamCreateFile ──────────▶ 音楽再生
                                    │
入力デバイス ────────────────▶ processKeyInput ───────────────▶ btkey/fxkey/laser
                                    │
note/analog配列 ────────────▶ 判定処理 ────────────────────▶ noteresult配列
                                    │
noteresult配列 ─────────────▶ updateGameSystem ───────────────▶ totalscore/gauge
                                    │
全データ ───────────────────▶ play_draw_frame ───────────────▶ 画面描画
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| play.hsp | `src/scene/play.hsp` | ソース | プレイ画面サブモジュールのインクルード |
| play_init.hsp | `src/scene/play/play_init.hsp` | ソース | プレイ初期化処理 |
| play_update.hsp | `src/scene/play/play_update.hsp` | ソース | メインループ更新処理 |
| play_key_input.hsp | `src/scene/play/play_key_input.hsp` | ソース | キー入力処理 |
| play_button_note.hsp | `src/scene/play/play_button_note.hsp` | ソース | BT/FXノート判定 |
| play_laser_note.hsp | `src/scene/play/play_laser_note.hsp` | ソース | レーザーノート判定 |
| play_game_logic.hsp | `src/scene/play/play_game_logic.hsp` | ソース | スコア・ゲージ・チェーン計算 |
| play_draw_frame.hsp | `src/scene/play/play_draw_frame.hsp` | ソース | 3Dノート描画・カメラ制御 |
| play_chart_load.hsp | `src/scene/play/play_chart_load.hsp` | ソース | KSH譜面読み込み |
| play_audio.hsp | `src/scene/play/play_audio.hsp` | ソース | 音楽再生・同期 |
| play_audio_effects.hsp | `src/scene/play/play_audio_effects.hsp` | ソース | オーディオエフェクト |
| play_graphics.hsp | `src/scene/play/play_graphics.hsp` | ソース | グラフィックス設定 |
| play_video.hsp | `src/scene/play/play_video.hsp` | ソース | 動画再生 |
| play_splash_screen.hsp | `src/scene/play/play_splash_screen.hsp` | ソース | スプラッシュ画面 |
| play_utils.hsp | `src/scene/play/play_utils.hsp` | ソース | ユーティリティ関数 |
| ksmcore.as | `src/ksmcore.as` | ソース | コアDLLバインディング |
| kshlib.as | `src/kshlib.as` | ソース | ライブラリDLLバインディング |
