# 機能設計書 22-自動デモ再生

## 概要

本ドキュメントは、選曲画面における自動デモ再生機能の設計を記述する。一定時間のShiftキー長押し操作によりオートプレイモードで連続デモ再生を開始する機能である。

### 本機能の処理概要

**業務上の目的・背景**：ゲームセンターの展示機やイベント会場での無人デモンストレーションを想定した機能である。操作不要で楽曲が連続的にオートプレイされることで、ゲームの魅力を来場者にアピールできる。個人利用では楽曲のプレビュー視聴を自動化する用途にも使える。

**機能の利用シーン**：選曲画面でShiftキーを長押しし続けると自動デモ再生モードが有効になり、楽曲リストを順にオートプレイで再生し続ける。次の楽曲への遷移も自動で行われる。

**主要な処理内容**：
1. Shiftキー（キーコード16）の押下状態をautodemo変数に取得
2. autodemo状態に応じてauto=1を設定し、オートプレイモードで楽曲を再生
3. 楽曲終了後、自動的にselnowをインクリメントして次の楽曲に遷移
4. 不正なアイテム（フォルダ等、minfo.selnow.0.0 < 0）に到達した場合は自動デモを停止

**関連システム・外部連携**：プレイ画面（play系モジュール）のオートプレイ機能と連携する。auto=1が設定されることで全ノートがAUTOモードで処理される。

**権限による制御**：特になし。全ユーザーが利用可能。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 3 | 曲選択画面 | 主画面 | Shiftキー長押しによる自動デモ再生の開始制御 |
| 5 | ゲームプレイ画面 | 結果表示画面 | auto=1でのオートプレイ実行 |

## 機能種別

自動実行制御 / デモンストレーション機能

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| autodemo | int | Yes | Shiftキー長押し状態（0:無効、1:デモ中、2:遷移中） | 0, 1, 2のいずれか |
| auto | int | Yes | F11キーまたはジョイスティックボタン13によるオートプレイ有効フラグ | 0または1 |
| selnow | int | Yes | 現在の選曲インデックス | 0以上mnum未満 |
| mnum | int | Yes | 楽曲リストの総数 | 1以上 |
| minfo.selnow.0.0 | int | Yes | 選択中アイテムの種別 | 0=通常楽曲, 負値=フォルダ等 |

### 入力データソース

キーボード入力（Shiftキー: キーコード16）、ゲーム内部状態

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| auto | int | オートプレイフラグ（1=有効） |
| autodemo | int | 自動デモ状態（0=停止、1=デモ中、2=次曲遷移中） |
| selnow | int | 次の楽曲インデックス |

### 出力先

ゲーム内部状態変数（プレイ画面のオートプレイ制御に使用）

## 処理フロー

### 処理シーケンス

```
1. 選曲画面初期化時にautodemoとautoの状態をチェック
   └─ auto=1かつautodemo=1なら、自動デモ再生を継続
2. autodemo=2（遷移中）の場合
   ├─ selnowをインクリメント
   ├─ selnow >= mnumなら0にリセット
   ├─ 負のアイテム種別(-3:セパレータ)をスキップ
   └─ 負のアイテム種別(-1等)に到達したらautodemo=0で停止
3. 選曲画面メインループ内
   ├─ F11キーとジョイスティックボタン13でauto変数を設定
   ├─ autodemo!=2のときShiftキー状態をautodemo変数に取得
   └─ autodemo=2の場合、auto=1を強制設定しオートプレイで遷移
4. 楽曲決定処理
   └─ autodemo=2ならautodemo=1に変更し、通常のプレイ開始処理へ
```

### フローチャート

```mermaid
flowchart TD
    A[選曲画面開始] --> B{auto=1 かつ autodemo=1?}
    B -->|Yes| C[autodemo=2に設定]
    C --> D[selnow++]
    D --> E{selnow >= mnum?}
    E -->|Yes| F[selnow=0]
    E -->|No| G{minfo<0?}
    F --> G
    G -->|Yes -3| H[selnow++でスキップ]
    G -->|Yes 他| I[autodemo=0で停止]
    G -->|No| J[次の楽曲を選択]
    B -->|No| K[autodemo=0]
    K --> L[メインループ]
    L --> M{Shiftキー押下?}
    M -->|Yes| N[autodemo=Shiftキー状態]
    M -->|No| O[autodemo維持]
    N --> P{autodemo=2?}
    P -->|Yes| Q[auto=1, 楽曲決定処理へ]
    P -->|No| L
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-22-01 | 自動遷移 | autodemo=2時にselnowを自動インクリメントし次曲へ遷移 | autodemoかつauto有効時 |
| BR-22-02 | フォルダスキップ | minfo.selnow.0.0=-3（セパレータ）はスキップする | 自動遷移時 |
| BR-22-03 | 停止条件 | minfo.selnow.0.0<0（フォルダ等）に到達したら停止 | 自動遷移時 |
| BR-22-04 | ラップアラウンド | selnow >= mnumの場合は0にリセット | 自動遷移時 |
| BR-22-05 | 強制オート | autodemo=2の場合、auto=1を強制設定 | デモ再生中 |

### 計算ロジック

特になし。

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

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

本機能ではデータベース操作は発生しない。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | 無効アイテム到達 | フォルダや特殊アイテムに到達 | autodemo=0で自動停止 |

### リトライ仕様

リトライは行わない。無効アイテム到達時は自動デモモードを終了する。

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

トランザクション管理は不要。

## パフォーマンス要件

自動デモ再生中の楽曲切替は、通常の選曲と同じ速度で処理される。追加のパフォーマンス要件はない。

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

特になし。

## 備考

- autodemo変数の状態遷移: 0(停止) -> Shiftキー押下で1(デモ開始) -> 楽曲決定で2(遷移中) -> 次曲選択後1に戻る
- adjmode（調整モード）はShiftキーとF12キーの同時押下で有効になるが、autodemo=2の場合はadjmode=0が強制される（1450行目）

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | select.hsp | `src/scene/select.hsp` | autodemo/auto/selnow/mnum変数の役割を理解する |

**読解のコツ**: autodemoは3状態（0/1/2）を持つ状態機械として読む。auto変数はF11キーでも設定可能なオートプレイフラグ。

#### Step 2: エントリーポイント（初期化時の自動遷移）

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | select.hsp | `src/scene/select.hsp` | 選曲画面初期化部分でのautodemo処理 |

**主要処理フロー**:
1. **72行目**: auto=1かつautodemo=1の場合にautodemo=2を設定
2. **73行目**: autodemo=2でselnowをインクリメント
3. **74-77行目**: selnow >= mnumでリスト先頭に戻る
4. **78-83行目**: minfo=-3（セパレータ）のスキップ処理
5. **84-86行目**: minfo<0で到達時にselnow=0, autodemo=0で停止
6. **88行目**: else分岐でautodemo=0にリセット

#### Step 3: メインループ内のShiftキー検出

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | select.hsp | `src/scene/select.hsp` | メインループ内でのShiftキー状態取得と楽曲決定処理 |

**主要処理フロー**:
- **1443-1444行目**: F11キーとジョイスティックボタン13でauto変数を設定
- **1445行目**: autodemo!=2のときgetkey autodemo,16でShiftキー状態を取得
- **1447-1448行目**: Shiftキー+F12キーでadjmode（調整モード）を設定
- **1450行目**: autodemo=2の場合、auto=1を強制設定、adjmode=0
- **1452行目**: 楽曲決定条件の複合判定（autodemo=2を含む）
- **1453行目**: autodemo=2ならautodemo=1に変更

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

```
select.hsp (選曲画面)
    |
    +-- 初期化処理 (72-88行目)
    |     +-- auto & autodemo判定
    |     +-- selnow自動インクリメント
    |     +-- minfo種別チェック
    |
    +-- メインループ (1443-1453行目)
          +-- getkey auto, 122 (F11)
          +-- getkey autodemo, 16 (Shift)
          +-- autodemo=2時のauto=1強制設定
          +-- 楽曲決定処理への遷移
```

### データフロー図

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

Shiftキー(16) -----> autodemo状態取得 ----+
                                          |
F11キー(122) -------> auto状態取得 -------+
                                          |
                      autodemo状態機械:
                      0(停止)
                       ↓ Shift長押し
                      1(デモ中)
                       ↓ 楽曲決定
                      2(遷移中)     -----> auto=1 -----> オートプレイ
                       ↓ 次曲選択
                      1(デモ中)に戻る
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| select.hsp | `src/scene/select.hsp` | ソース | 自動デモ再生の全実装（72-88行目、1443-1453行目） |
