# 機能設計書 7-シーン遷移管理

## 概要

K-Shoot MANIAのTITLE/SELECT/PLAY/RESULT/COURSE_RESULT/OPTION等のシーン間遷移をメインループで制御する機能の設計書である。

### 本機能の処理概要

シーン遷移管理は、kshootmania.hspのメインループ内でscene変数に基づくswitch-case分岐によりゲーム全体のシーンフローを制御する。各シーンのサブルーチンを呼び出し、シーン間のトランジション演出（フェードイン/フェードアウト/ホワイトアウト）も管理する。

**業務上の目的・背景**：ゲーム全体のフロー制御を一元管理することで、シーン間の遷移ロジックを明確に定義し、各シーンの独立性を保ちつつ統合的な動作を実現する。

**機能の利用シーン**：ゲーム起動から終了まで常に動作し、各シーンの切替をリアルタイムに制御する。シーン変数（scene）の変更が検出されると、対応するシーンのサブルーチンが呼び出される。

**主要な処理内容**：
1. 9つのシーン列挙定数の定義（SCENE_TITLE=0 ~ SCENE_GATE=8）
2. メインループのrepeat-loop内でのswitch-case分岐
3. 各シーンの初期化フラグ管理（is_scene_initial_frame）
4. 前シーン記録（prev_scene）
5. フェードイン/フェードアウト/ホワイトアウト/ブラックアウトのトランジション制御
6. フレームスキップ制御と再描画管理
7. ボリュームアクティブ制御（*volactive）
8. PowerMate入力制御

**関連システム・外部連携**：全てのシーン画面モジュール

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

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 全画面 | 全画面 | 主機能 | 全シーンの遷移制御を担当 |

## 機能種別

フロー制御・状態管理

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| scene | int | Yes | 現在のシーンID | 0-8（SCENE_TITLE ~ SCENE_GATE） |
| is_scene_initial_frame | int | Yes | シーン初期化フラグ | 0 or 1 |
| prev_scene | int | No | 前のシーンID | 0-8 |
| frameskip | int | No | フレームスキップ設定 | 0以上 |

### 入力データソース

- 各シーンのサブルーチンが設定するscene変数

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| scene | int | 次に実行するシーンID |
| is_scene_initial_frame | int | 次シーンの初期化フラグ |

### 出力先

- 各シーンのサブルーチン呼び出し

## 処理フロー

### 処理シーケンス

```
1. メインループ（repeat）
   ├─ switch scene
   │   ├─ SCENE_TITLE (0): start_title
   │   ├─ SCENE_IR_SIGN_IN (1): IRサインイン処理（インライン）
   │   ├─ SCENE_SELECT (2): start_select
   │   ├─ SCENE_BEFORE_PLAY (3): コースモード前処理（インライン）
   │   ├─ SCENE_PLAY (4): start_play
   │   ├─ SCENE_RESULT (5): on_update_result
   │   ├─ SCENE_COURSE_RESULT (6): on_update_course_result
   │   ├─ SCENE_OPTION (7): on_update_option
   │   └─ SCENE_GATE (8): on_update_gate
   ├─ フレームスキップ制御
   │   └─ cnt % (frameskip+1) = 0 のとき再描画
   ├─ ボリューム制御（*volactive）
   ├─ ウィンドウフォーカス待機
   └─ PowerMate入力制御
```

### フローチャート

```mermaid
flowchart TD
    A[ゲーム開始] --> B[初期化処理]
    B --> C[scene=SCENE_TITLE]
    C --> D[メインループ]
    D --> E{scene値}
    E -->|0| F[start_title]
    E -->|1| G[IRサインイン]
    E -->|2| H[start_select]
    E -->|3| I[コースモード前処理]
    E -->|4| J[start_play]
    E -->|5| K[on_update_result]
    E -->|6| L[on_update_course_result]
    E -->|7| M[on_update_option]
    E -->|8| N[on_update_gate]
    F --> O[フレーム制御]
    G --> O
    H --> O
    I --> O
    J --> O
    K --> O
    L --> O
    M --> O
    N --> O
    O --> D
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-01 | シーン初期化 | is_scene_initial_frame=1のとき各シーンは初期化処理を実行 | シーン切替時 |
| BR-02 | フレームスキップ | frameskip+1フレームに1回描画（0=毎フレーム描画） | メインループ末尾 |
| BR-03 | フォーカス待機 | ゲート画面以外かつ非コース/非デモ時、ウィンドウ非フォーカスで待機 | ginfo2()!=0 |
| BR-04 | SCENE_BEFORE_PLAY | フレーム描画なしの前処理シーン（コースモード専用） | iscourse=1 |
| BR-05 | トランジション | blackout/whiteout関数でフェードイン/アウト演出 | シーン切替時 |

### 計算ロジック

特になし。

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

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

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | 終了処理 | onexit gosub *exit | 終了ハンドラで安全に終了 |

### リトライ仕様

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

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

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

## パフォーマンス要件

- メインループは7msのawait（SCENE_GATE以外）
- フレームスキップにより描画負荷を軽減可能

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

特になし。

## 備考

- SCENE_BEFORE_PLAYはフレーム描画を持たない処理専用シーン
- SCENE_IR_SIGN_INはメインループ内にインライン実装されている

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | kshootmania.hsp | `kshootmania.hsp` | シーン列挙定数の定義 |

**読解のコツ**: HSPの`#enum`はC言語のenumと同様に連続した整数値を割り当てる。`#enum SCENE_TITLE = 0`から始まり、`#enum SCENE_IR_SIGN_IN`は1、以降インクリメントされる。

- **11-19行目**: 9つのシーン列挙定数定義
  - SCENE_TITLE=0, SCENE_IR_SIGN_IN=1, SCENE_SELECT=2, SCENE_BEFORE_PLAY=3
  - SCENE_PLAY=4, SCENE_RESULT=5, SCENE_COURSE_RESULT=6, SCENE_OPTION=7, SCENE_GATE=8
- **206-207行目**: scene=0, is_scene_initial_frame=1 の初期化

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | kshootmania.hsp | `kshootmania.hsp` | メインループ（947-1235行目） |

**主要処理フロー**:
1. **947行目**: `repeat` でメインループ開始
2. **948行目**: `switch scene` でシーン分岐開始
3. **949-951行目**: `case SCENE_TITLE` → `start_title` 呼び出し
4. **952-953行目**: `case SCENE_SELECT` → `start_select` 呼び出し
5. **955-1027行目**: `case SCENE_BEFORE_PLAY` → コースモード前処理（インライン）
6. **1028-1077行目**: `case SCENE_PLAY` → `start_play` 呼び出し
7. **1079-1081行目**: `case SCENE_RESULT` → `on_update_result` 呼び出し
8. **1082-1084行目**: `case SCENE_COURSE_RESULT` → `on_update_course_result` 呼び出し
9. **1085-1087行目**: `case SCENE_OPTION` → `on_update_option` 呼び出し
10. **1088-1090行目**: `case SCENE_GATE` → `on_update_gate` 呼び出し
11. **1091-1216行目**: `case SCENE_IR_SIGN_IN` → インライン実装
12. **1218-1234行目**: フレームスキップ制御・再描画・ボリューム制御
13. **1235行目**: `loop` でメインループ終了

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

```
kshootmania.hsp (メインループ: 947行目)
    │
    ├─ case SCENE_TITLE → start_title (src/scene/title.hsp)
    ├─ case SCENE_SELECT → start_select (src/scene/select.hsp)
    ├─ case SCENE_BEFORE_PLAY → インライン処理 (955-1027行目)
    ├─ case SCENE_PLAY → start_play (src/scene/play/play_init.hsp)
    ├─ case SCENE_RESULT → on_update_result (src/scene/result.hsp)
    ├─ case SCENE_COURSE_RESULT → on_update_course_result (src/scene/course_result.hsp)
    ├─ case SCENE_OPTION → on_update_option (src/scene/option.hsp)
    ├─ case SCENE_GATE → on_update_gate (src/scene/gate.hsp)
    ├─ case SCENE_IR_SIGN_IN → インライン処理 (1091-1216行目)
    ├─ *volactive (ボリューム制御)
    └─ *exit (終了処理)
```

### データフロー図

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

scene変数 ──────────────────▶ switch-case分岐 ──────────────▶ シーンサブルーチン呼び出し
                                    │
is_scene_initial_frame ─────▶ 初期化判定 ───────────────────▶ シーン初期化実行
                                    │
prev_scene ─────────────────▶ 前シーン参照 ─────────────────▶ 遷移元に応じた処理分岐
                                    │
frameskip ──────────────────▶ フレーム制御 ─────────────────▶ 再描画タイミング
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| kshootmania.hsp | `kshootmania.hsp` | ソース | メインループ・シーン分岐・全体制御 |
| title.hsp | `src/scene/title.hsp` | ソース | タイトル画面シーン |
| select.hsp | `src/scene/select.hsp` | ソース | 選曲画面シーン |
| play.hsp | `src/scene/play.hsp` | ソース | プレイ画面シーン（サブモジュール集約） |
| result.hsp | `src/scene/result.hsp` | ソース | リザルト画面シーン |
| course_result.hsp | `src/scene/course_result.hsp` | ソース | コースリザルト画面シーン |
| option.hsp | `src/scene/option.hsp` | ソース | オプション設定画面シーン |
| gate.hsp | `src/scene/gate.hsp` | ソース | ゲート画面シーン |
