# 画面設計書 5-ゲームプレイ画面

## 概要

本ドキュメントは、K-Shoot MANIA のゲームプレイ画面の設計仕様を記述する。メインゲームプレイ画面であり、楽曲を演奏し、ノート判定（BT/FX/Laser）、スコア計算、グラフィクス描画、オーディオ再生を統合管理する。14個のサブモジュールで構成される最も複雑な画面である。

### 本画面の処理概要

ゲームプレイ画面は音楽ゲームのメインプレイ画面であり、楽曲再生と同期してノートを判定し、スコアを計算しながらリアルタイムに描画を行う。

**業務上の目的・背景**：K-Shoot MANIAの本質であるゲームプレイ体験を提供する画面。Sound Voltex風の4つのBTボタン、2つのFXボタン、2つのアナログレーザー入力によるリズムゲームを実現する。譜面ファイル（.ksh）の読み込みから、ノート判定、スコア計算、エフェクト適用、グラフィック描画まで全てを統合管理する。

**画面へのアクセス方法**：プレイ前処理画面（SCENE_BEFORE_PLAY）から、コースファイル解析成功後またはiscourse=0で遷移する。リザルト画面からコースモード次曲として遷移することもある。

**主要な操作・処理内容**：
1. 譜面ファイル（.ksh）の読み込みと解析（loadKSHChartFile）
2. BT/FXノートの判定処理（CRITICAL/NEAR/ERROR）
3. レーザーノートの判定処理（L/R独立アナログ位置追跡・スラム判定）
4. スコア計算（最大10,000,000点、CRITICAL+2/NEAR+1/ERROR0）
5. ゲージ管理（通常ゲージ/HARDゲージの2種類）
6. チェーンカウント（連続成功判定のカウント）
7. 楽曲オーディオ再生（OGG/MP3/WAV対応、デュアルトラック）
8. オーディオエフェクト適用（Retrigger/Gate/Flanger/PitchShift/BitCrusher/Phaser/Wobble/TapeStop/Echo/Sidechain等）
9. ノート描画（BT/FX/レーザーの3D描画）
10. カメラ制御（Zoom/Tilt/Spin/HalfSpin/CenterSplit）
11. 背景描画（30種以上のパターン）
12. 判定エフェクト表示
13. リアルタイムUI表示（コンボ数・スコア・ゲージバー・FPS・タイミング調整値）
14. 一時停止・再開、プレイ中HiSpeed変更、タイミング手動調整
15. キー音再生、レーザースラム音
16. スプラッシュ画面（プレイ直前の楽曲情報表示）

**画面遷移**：
- 遷移先：リザルト画面（SCENE_RESULT、ゲーム完了、行131 of play_key_input.hsp）、曲選択画面（SCENE_SELECT、ESCキー/初期化エラー、行12/62/118/744 of play_init.hsp）
- 遷移元：プレイ前処理画面（SCENE_BEFORE_PLAY）、リザルト画面（コースモード次曲）

**権限による表示制御**：なし。auto変数=1の場合はオートプレイモードで動作する。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 3 | プレイ画面 | 主機能 | play_init/play_update/play_draw_frameの3フェーズによるメインゲームプレイの統合管理 |
| 23 | KSH譜面ファイル読み込み | 主機能 | loadKSHChartFileによるKSHフォーマット譜面ファイルの読み込み |
| 25 | 譜面パラメータ解析 | 主機能 | parseKSHChartParamLinesによるtitle/artist/BPM等のメタデータ解析 |
| 28 | BTノート判定 | 主機能 | specifyJudgmentTargetOfButtonNotesによるBTノートの判定処理 |
| 29 | FXノート判定 | 主機能 | FXボタンのチップ・ロングノートに対する判定処理 |
| 30 | レーザーノート判定 | 主機能 | specifyJudgmentTargetOfLaserNotesによるL/R独立アナログ位置追跡 |
| 31 | スコア計算 | 主機能 | CRITICAL(+2)/NEAR(+1)/ERROR(0)による最大10,000,000点のスコア計算 |
| 32 | ゲージ管理 | 主機能 | 通常ゲージとHARD(ネガティブ)ゲージの2種類 |
| 33 | チェーンカウント | 主機能 | 連続成功判定のチェーン数カウントと最大チェーン(chainmax)の記録 |
| 40 | 音楽ファイル再生 | 主機能 | BASS_StreamCreateFileによるOGG/MP3/WAV形式再生 |
| 41 | デュアルトラック再生 | 主機能 | エフェクトON/OFFの2チャンネル(mid配列)によるデュアルトラック切替再生 |
| 58 | キーボード入力 | 主機能 | play_key_input.hspによるBT/FXキー入力・Enter・Esc処理 |
| 59 | ジョイスティック入力 | 主機能 | play_key_input.hspによるジョイスティックボタン入力処理 |
| 60 | アナログ入力 | 主機能 | play_key_input.hspによる6種類アナログ入力処理 |
| 64 | ノート描画 | 主機能 | play_draw_frame.hspによるBT/FX/レーザーの描画 |
| 65 | カメラ制御 | 主機能 | play_draw_frame.hspによるカメラ制御 |
| 66 | 背景描画 | 主機能 | play_draw_frame.hspによる背景パターン描画 |
| 67 | 判定エフェクト表示 | 主機能 | 判定結果・チェーンエフェクト表示 |
| 68 | リアルタイムUI表示 | 主機能 | コンボ・スコア・ゲージバー・FPSのUI表示 |
| 130 | BASS Audio Library | 主機能 | bass.dll/bass_fx.dllによるオーディオエンジン制御 |
| 131 | VSTエフェクトDLL群 | 補助機能 | bitc/flan/phas/pitc/regawo/sich/tstpのVSTエフェクトDLL |
| 7 | シーン遷移管理 | 遷移先機能 | プレイ完了・Escキー押下によるSCENE_RESULT/SCENE_SELECTへの遷移 |

## 画面種別

ゲームプレイ画面（リアルタイムインタラクティブ）

## URL/ルーティング

デスクトップアプリケーション（HSP3）のため、URLルーティングは存在しない。シーン管理はscene変数（SCENE_PLAY = 4）により制御される。

## 入出力項目

| 項目名 | 入出力 | データ型 | 説明 |
|--------|--------|----------|------|
| cnotesfile | 入力 | string | 譜面ファイルパス |
| csongdir | 入力 | string | 楽曲ディレクトリパス |
| iscourse | 入力 | int | コースモードフラグ |
| auto | 入力 | int | オートプレイフラグ（1:自動判定） |
| note | 内部状態 | int配列 | ノートデータ配列 |
| noteresult | 内部状態 | int配列 | 各ノートの判定結果 |
| totalscore | 出力 | int | 合計スコア（0-10,000,000） |
| critical | 出力 | int | CRITICAL判定数 |
| near | 出力 | int | NEAR判定数 |
| errorn | 出力 | int | ERROR判定数 |
| chainmax | 出力 | int | 最大チェーン数 |
| gauge | 出力 | int | ゲージ値 |
| mid | 内部状態 | int配列 | BASSチャンネルID配列（デュアルトラック） |

## 表示項目

| 項目名 | 表示位置 | 説明 |
|--------|----------|------|
| レーン | 画面中央 | 3D透視投影されたノートレーン。BT4レーン + FX2レーン + Laser2レーン |
| BTノート | レーン上 | 白色のチップ・ロングノート（buffer 42, 53-124） |
| FXノート | レーン上 | オレンジ色のチップ・ロングノート（buffer 1, 43, 150） |
| レーザーノート | レーン上 | 青/赤色のアナログレーザーライン（buffer 4, 6, 7, 154） |
| 判定表示 | レーン下部 | CRITICAL/NEAR/ERROR判定テキスト・エフェクト |
| コンボ数 | 画面上部 | 現在のチェーン数（buffer 21） |
| スコア | 画面上部 | 現在のスコア値 |
| ゲージバー | 画面右端 | エフェクティブレートゲージ（buffer 23, 147） |
| FPS | 画面隅 | フレームレート表示（Image 143） |
| 背景 | レーン背後 | 30種以上のパターン（desert/sky/ocean等） |
| スプラッシュ | プレイ開始前 | ジャケット画像・楽曲情報の表示 |

## イベント仕様

### 1-ゲームプレイ開始

start_play関数により初期化処理が実行される：
1. ジョイスティック初期化（行3-5）
2. タイミング補正値計算（行20-32）
3. ゲームプレイ変数初期化（initGamePlayVariables, 行38）
4. 譜面データ変数初期化（initChartVariables, 行41）
5. MIRROR/RANDOM処理（prepareTurnOptions, 行44）
6. ノートモード設定（prepareModeOptions, 行47）
7. 譜面ファイル読み込み（loadKSHChartFile, 行67）
8. 譜面パラメータ解析（parseKSHChartParamLines, 行70付近）

### 2-ノート判定（毎フレーム）

play_update/play_key_inputにより入力を検出し、ノート位置との時間差から判定を行う：
- **CRITICAL**：スコア+2（最高判定）
- **NEAR**：スコア+1（許容範囲内）
- **ERROR**：スコア+0（判定失敗）

### 3-ゲーム完了

楽曲の最後まで到達した場合、またはHARDゲージが0になった場合にゲーム完了となり、scene=SCENE_RESULTへ遷移する（play_key_input.hsp行131）。遷移時にBASSストリーム解放・キー音ライブラリクリアが行われる。

### 4-ESCキー中断

ESCキー押下でゲームを中断し、scene=SCENE_RESULTへ遷移する（途中終了扱い）。コースモード中は自動デモのフラグもリセットされる。

### 5-一時停止・再開

Ctrl+EnterまたはMediaStopキーでゲームを一時停止/再開する（processPlaybackControlInput, play_key_input.hsp行1-89）。mstop変数で一時停止状態を管理。

### 6-プレイ中HiSpeed変更

FXボタン長押し+BTボタンによりプレイ中にHiSpeedを変更可能。

### 7-タイミング手動調整

Ctrl+Alt+矢印キーでタイミング補正値（sync変数）を手動調整可能（processSyncValueManualChangeInput, play_key_input.hsp行91-109）。Shift追加で1ms刻み、なしで5ms刻み。

## データベース更新仕様

### 操作別データベース影響一覧

| 操作（イベント） | 対象ファイル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| ゲーム開始 | songs/曲ディレクトリ/*.ksh | SELECT | 譜面ファイルの読み込み |
| ゲーム開始 | songs/曲ディレクトリ/*.ogg等 | SELECT | 楽曲音声ファイルの読み込み |

### テーブル別更新項目詳細

該当なし（ゲームプレイ中はファイル書き込みを行わない。スコア保存はリザルト画面で実行）。

## メッセージ仕様

| メッセージID | 種別 | 表示条件 | メッセージ内容 |
|-------------|------|----------|--------------|
| lang.2.13 | エラー | 譜面ファイルが見つからない場合 | 「指定された譜面ファイルが見つかりません。」 |
| FAST/SLOW | 情報 | NEAR判定時 | FAST（早押し）またはSLOW（遅押し）のタイミング表示 |

## 例外処理

| 例外条件 | 処理内容 |
|---------|---------|
| 譜面ファイル不存在 | エラーダイアログ表示後、SCENE_SELECTへ遷移（play_init.hsp行57-63） |
| 楽曲ディレクトリ不存在 | エラーダイアログ表示後、SCENE_SELECTへ遷移（play_init.hsp行9-13） |
| 楽曲ファイル読み込み失敗 | SCENE_SELECTへ遷移 |

## 備考

- 14個のサブモジュール構成：play_init/play_update/play_key_input/play_button_note/play_laser_note/play_draw_frame/play_chart_load/play_game_logic/play_graphics/play_audio/play_audio_effects/play_video/play_utils/play_splash_screen
- スコア計算式：totalscore = 10,000,000 * 獲得スコアポイント / (全ノート数 * 2)
- ゲージタイプ：通常（effratetype<=0、ポジティブゲージ）、HARD（effratetype=1、ネガティブゲージ）
- VSTエフェクトDLL群（bitc/flan/phas/pitc/regawo/sich/tstp）によるリアルタイムオーディオエフェクト適用
- D3D9 Vsync同期制御（mod_d3d9vsync.hsp）により滑らかなフレーム描画を実現
- ノートスキンは2種類（DEFAULT/NOTE）をcoloring変数で切替
- 描画品質は3段階（高画質/中画質/低画質）をlowquality変数で制御

---

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

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

### 推奨読解順序

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

譜面データとゲーム状態の管理構造を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | kshootmania.hsp | `kshootmania.hsp` | 行14: SCENE_PLAY=4。行21-24: mode_on/off/auto/hide定数。行33-48: レーン幅・カウント値等の定数 |
| 1-2 | play_init.hsp | `src/scene/play/play_init.hsp` | 行38: initGamePlayVariables、行41: initChartVariables。ゲームプレイ変数と譜面データ変数の初期化 |

**読解のコツ**: note配列はnote.ノート番号.属性の2次元配列。note.n.0=レーン番号(0-3:BT, 4-5:FX)、note.n.2=ノートタイプ。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | play.hsp | `src/scene/play.hsp` | 14個のサブモジュールを#includeで統合するハブファイル |
| 2-2 | play_init.hsp | `src/scene/play/play_init.hsp` | 行1: start_play関数。初期化処理のエントリーポイント |

**主要処理フロー**:
1. **行1-18**: ジョイスティック初期化、ディレクトリ確認
2. **行20-32**: タイミング補正値計算
3. **行38-47**: 変数初期化、TURN/MODEオプション適用
4. **行56-63**: 譜面ファイル存在確認
5. **行67-70**: 譜面ファイル読み込み・パラメータ解析

#### Step 3: 入力処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | play_key_input.hsp | `src/scene/play/play_key_input.hsp` | 行1-89: processPlaybackControlInput（一時停止・再開）、行91-109: processSyncValueManualChangeInput（タイミング調整）、行111-140: processEscKeyInput（ESC/終了判定） |

#### Step 4: 判定処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | play_button_note.hsp | `src/scene/play/play_button_note.hsp` | BTノートの判定処理。specifyJudgmentTargetOfButtonNotes |
| 4-2 | play_laser_note.hsp | `src/scene/play/play_laser_note.hsp` | レーザーノートの判定処理。specifyJudgmentTargetOfLaserNotes |

#### Step 5: 描画処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 5-1 | play_draw_frame.hsp | `src/scene/play/play_draw_frame.hsp` | ノート・カメラ・背景・判定エフェクト・UIの統合描画処理 |
| 5-2 | play_graphics.hsp | `src/scene/play/play_graphics.hsp` | ノートスキン・描画品質の制御 |

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

```
kshootmania.hsp (メインループ)
    |
    +-- start_play (play_init.hsp:1)
            |
            +-- initGamePlayVariables ... ゲーム変数初期化
            +-- initChartVariables ... 譜面変数初期化
            +-- prepareTurnOptions ... MIRROR/RANDOM
            +-- prepareModeOptions ... ノートモード
            +-- loadKSHChartFile (play_chart_load.hsp) ... 譜面読み込み
            +-- parseKSHChartParamLines ... パラメータ解析
            |
            +-- play_update (play_update.hsp)
            |       +-- processPlaybackControlInput (play_key_input.hsp)
            |       +-- processSyncValueManualChangeInput
            |       +-- processEscKeyInput
            |       +-- specifyJudgmentTargetOfButtonNotes (play_button_note.hsp)
            |       +-- specifyJudgmentTargetOfLaserNotes (play_laser_note.hsp)
            |       +-- processPlayTiming (play_audio.hsp)
            |       +-- play_game_logic (play_game_logic.hsp) ... スコア・ゲージ計算
            |
            +-- play_draw_frame (play_draw_frame.hsp)
            |       +-- 背景描画
            |       +-- レーン描画
            |       +-- ノート描画 (BT/FX/Laser)
            |       +-- 判定エフェクト描画
            |       +-- UI描画 (コンボ/スコア/ゲージ)
            |       +-- カメラ制御 (Zoom/Tilt/Spin)
            |
            +-- play_audio (play_audio.hsp) ... 楽曲再生
            +-- play_audio_effects (play_audio_effects.hsp) ... エフェクト適用
            +-- play_video (play_video.hsp) ... 動画再生
            +-- play_splash_screen (play_splash_screen.hsp) ... スプラッシュ表示
```

### データフロー図

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

*.ksh (譜面) -----------> loadKSHChartFile -------> note/notefx/analog配列
*.ogg (楽曲) -----------> BASS_StreamCreateFile --> mid配列 (再生チャンネル)

BT/FXキー入力 --------> play_key_input ---------> キー状態
アナログ入力 ----------> play_key_input ---------> アナログ位置

note配列 + キー状態 --> specifyJudgmentTarget ---> noteresult配列
                               |                      |
                               v                      v
                        スコア/ゲージ計算      判定エフェクト表示
                               |
                               v
                        play_draw_frame --------> 画面描画
                               |
                               v
                        processEscKeyInput
                               |
                    +-----------+-----------+
                    |                       |
                    v                       v
              scene=SCENE_RESULT      scene=SCENE_SELECT
              (完了/ESC)              (エラー)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| play.hsp | `src/scene/play.hsp` | ソース | 14サブモジュールを統合するハブファイル |
| play_init.hsp | `src/scene/play/play_init.hsp` | ソース | start_play関数。初期化処理 |
| 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ノート判定処理 |
| play_laser_note.hsp | `src/scene/play/play_laser_note.hsp` | ソース | レーザーノート判定処理 |
| play_draw_frame.hsp | `src/scene/play/play_draw_frame.hsp` | ソース | フレーム描画処理 |
| play_chart_load.hsp | `src/scene/play/play_chart_load.hsp` | ソース | 譜面ファイル読み込み処理 |
| play_game_logic.hsp | `src/scene/play/play_game_logic.hsp` | ソース | ゲームロジック（スコア・ゲージ計算） |
| play_graphics.hsp | `src/scene/play/play_graphics.hsp` | ソース | グラフィック設定（スキン・品質） |
| play_audio.hsp | `src/scene/play/play_audio.hsp` | ソース | オーディオ再生・同期制御 |
| play_audio_effects.hsp | `src/scene/play/play_audio_effects.hsp` | ソース | オーディオエフェクト適用 |
| play_video.hsp | `src/scene/play/play_video.hsp` | ソース | MCI動画再生 |
| play_utils.hsp | `src/scene/play/play_utils.hsp` | ソース | ユーティリティ関数群 |
| play_splash_screen.hsp | `src/scene/play/play_splash_screen.hsp` | ソース | プレイ前スプラッシュ画面 |
| kshootmania.hsp | `kshootmania.hsp` | ソース | メインループ、シーン管理 |
| bass.dll | `bass.dll` | ライブラリ | BASSオーディオエンジン |
| bass_fx.dll | `bass_fx.dll` | ライブラリ | BASSエフェクト拡張 |
| ksmcore.dll | `ksmcore.dll` | ライブラリ | ゲームシステム管理・カメラ値計算 |
| kshlib.dll | `kshlib.dll` | ライブラリ | Switch Audio・チャートファイル操作・MD5ハッシュ |
| bitc.dll等 | `bitc.dll`, `flan.dll`, `phas.dll`, `pitc.dll`, `regawo.dll`, `sich.dll`, `tstp.dll` | ライブラリ | VSTエフェクトDLL群 |
