# 機能設計書 20-インラインオプション変更

## 概要

本ドキュメントは、K-Shoot MANIA の選曲画面における「インラインオプション変更」機能の設計を記述する。HiSpeed・ノートモード・エフェクトレート・TURN・ゲージタイプ等を選曲画面上で直接変更する機能である。

### 本機能の処理概要

本機能は、選曲画面でBTキー(BT-A/BT-B/BT-C)を単独押ししながら方向キーを操作することで、オプション設定画面に遷移せずに各種プレイオプションを直接変更できる機能を提供する。3つのBTキーにそれぞれ異なるオプショングループが割り当てられ、変更内容はリアルタイムで画面右下にオーバーレイ表示される。また、3つ以上のBTキー同時押しで判定詳細情報も表示される。

**業務上の目的・背景**：頻繁に変更するプレイオプション(ノートモード・ゲージタイプ・TURN設定等)をオプション画面に遷移せずに素早く変更できるようにし、選曲の流れを中断しないようにする。

**機能の利用シーン**：
- BT-A単独押し+方向キー: BT/FX/LASERのノートモード(ON/OFF/HIDE/AUTO)変更
- BT-B単独押し+方向キー: ゲージタイプ(EASY/NORMAL/HARD)・TURN(NORMAL/MIRROR/RANDOM)変更
- BT-C単独押し+方向キー: アシストティック・AUTO SYNC・FAST/SLOW表示・ノートスキン・動画再生変更
- BT-D単独押し+方向キー: HiSpeed変更
- BT3個以上同時押し: 判定詳細情報(CRITICAL/NEAR/ERROR/最大チェーン)表示

**主要な処理内容**：
1. BTキー単独押し状態の検出(`btkey.N=1` かつ `btkey合計=1`)
2. 方向キー入力による各オプション値の増減
3. 上下キーによるオプショングループ内項目の切替
4. オプション変更内容のオーバーレイ画像生成(画像ID 87)
5. 設定変更時のスコア再読み込み(effratetype/turn等はスコアキーに影響)
6. optionfl変数によるオーバーレイ表示制御

**関連システム・外部連携**：なし。

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

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 3 | 曲選択画面 | 主画面 | 曲選択画面上でのHiSpeed・effratetype(ゲージタイプ)・turn(MIRROR/RANDOM等)の直接変更 |

## 機能種別

設定変更 / UI操作

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| btkey.0-3 | int | Yes | BT-A〜BT-Dボタン状態(0/1) | 0 or 1 |
| 方向キー(左右) | int | Yes | オプション値の増減 | - |
| 方向キー(上下) | int | Yes | オプション項目の切替 | - |
| shortmode | int | Yes | BTノートモード(0:ON, 1:OFF, 2:AUTO, 3:HIDE) | 0-3 |
| longmode | int | Yes | FXノートモード(0:ON, 1:OFF, 2:AUTO, 3:HIDE) | 0-3 |
| analogmode | int | Yes | LASERノートモード(0:ON, 1:OFF, 2:AUTO, 3:HIDE) | 0-3 |
| effratetype2 | int | Yes | ゲージタイプ(-1:EASY, 0:NORMAL, 1:HARD) | -1, 0, 1 |
| turn | int | Yes | TURN設定(0:NORMAL, 1:MIRROR, 2:RANDOM) | 0-2 |
| assisttick | int | Yes | アシストティック(0:OFF, 1:ON) | 0-1 |
| autosync | int | Yes | AUTO SYNC(0:OFF, 1-3:レベル) | 0-3 |
| vtiming | int | Yes | FAST/SLOW表示(0:OFF, 1:ON) | 0-1 |
| coloring | int | Yes | ノートスキン(0:DEFAULT, 1:NOTE) | 0-1 |
| vmov | int | Yes | 動画再生(0:OFF, 1:ON) | 0-1 |

### 入力データソース

- キーボード/ジョイスティック入力

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| 各オプション変数 | int | 変更後の各設定値 |
| 画像ID 87 | image | オプション表示オーバーレイ画像 |
| optionfl | int | オーバーレイ表示フラグ(0:非表示, 1:表示) |

### 出力先

- 画面表示: 選曲画面右下のオプションオーバーレイ
- メモリ: 各オプション変数の更新

## 処理フロー

### 処理シーケンス

```
1. BTキー単独押し判定
   ├─ BT-A単独(btkey.0=1, 合計=1): ノートモード変更パネル
   ├─ BT-B単独(btkey.1=1, 合計=1): ゲージ/TURN変更パネル
   ├─ BT-C単独(btkey.2=1, 合計=1): アシスト/表示設定パネル
   ├─ BT-D単独(btkey.3=1, 合計=1): HiSpeed変更パネル
   └─ BT3個以上(合計>=3): 判定詳細表示パネル
2. 左右キーでオプション値を増減
   └─ 各オプションの有効範囲でクランプ
3. 上下キーで項目選択を切替
   └─ jselnow(BT-A用), dselnow(BT-B用), sselnow(BT-C用)
4. オーバーレイ画像(画像ID 87)を生成
   ├─ 背景テンプレート(画像ID 86)をコピー
   ├─ 多言語テキストでオプション名・値を描画
   └─ 選択中項目に"<"/">"矢印を表示
5. optionfl=1を設定して画面右下に表示
6. 設定変更がスコアキーに影響する場合(effratetype/turn/mode)
   └─ *reloadscore / *refreshscore / *refreshsonginfo を実行
```

### フローチャート

```mermaid
flowchart TD
    A{BTキー状態?}
    A -->|BT-A単独| B[ノートモードパネル]
    A -->|BT-B単独| C[ゲージ/TURNパネル]
    A -->|BT-C単独| D[アシスト/表示パネル]
    A -->|BT-D単独| E[HiSpeedパネル]
    A -->|3個以上| F[判定詳細パネル]
    A -->|なし| G[optionfl=0]
    B --> H[左右キーで値変更]
    C --> H
    D --> H
    E --> H
    H --> I[オーバーレイ画像生成]
    I --> J[optionfl=1]
    J --> K{スコアキー影響?}
    K -->|Yes| L[*reloadscore等実行]
    K -->|No| M[表示のみ]
    F --> J
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-20-1 | 単独押し条件 | btkey合計=1(1つのBTキーのみ押下)の場合にオプション変更可能 | 常時 |
| BR-20-2 | 入力間隔 | ts>80(80ms以上経過)の場合にのみ値変更を受け付け | 常時 |
| BR-20-3 | ノートモード範囲 | shortmode/longmode/analogmode: 0(ON)〜3(HIDE) | BT-A操作時 |
| BR-20-4 | ゲージタイプ範囲 | effratetype2: -1(EASY)〜1(HARD) | BT-B操作時 |
| BR-20-5 | TURN範囲 | turn: 0(NORMAL)〜2(RANDOM) ※コメントで4まで対応の記述あり | BT-B操作時 |
| BR-20-6 | AUTO SYNC範囲 | autosync: 0(OFF)〜3(レベル3) | BT-C操作時 |
| BR-20-7 | スコアキー連動 | ノートモード/ゲージタイプ/TURN変更時はスコア再読み込み | 設定変更時(stat3=1) |
| BR-20-8 | ダイアログ非表示 | dialognow=0時のみオプション変更可能 | 常時 |

### 計算ロジック

なし。

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

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

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | 範囲外 | オプション値が有効範囲外になりそうな場合 | min/maxでクランプ |

### リトライ仕様

なし。

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

なし。

## パフォーマンス要件

- オーバーレイ画像の動的生成が毎フレーム発生するが、小サイズ(320x180px相当)のため影響は軽微

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

特になし。

## 備考

- BT-Aパネル: jselnow変数で選択項目管理(0:BT, 1:FX, 2:LASER)
- BT-Bパネル: dselnow変数で選択項目管理(0:ゲージタイプ, 1:TURN)
- BT-Cパネル: sselnow変数で選択項目管理(0:アシストティック, 1:AUTO SYNC, 2:FAST/SLOW, 3:ノートスキン, 4:動画再生)
- BT3個以上同時押し: 現在のスコア詳細(CRITICAL/NEAR/ERROR/最大チェーン)を表示するのみで変更はしない
- 多言語テキスト(lang.1.*)により各オプション名・値が表示される

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | select.hsp | `src/scene/select.hsp` | btkey配列(BT0-3の状態)、optionfl(オーバーレイ表示フラグ)、jselnow/dselnow/sselnow(各パネルの項目選択)の変数を理解 |
| 1-2 | select.hsp | `src/scene/select.hsp` | shortmode/longmode/analogmode(ノートモード)、effratetype2(ゲージ)、turn(TURN)等の設定変数を理解 |

**読解のコツ**: 各BTキーのオプションパネルは`else:if`で連鎖している。optionfl=1が設定されると画面右下にオーバーレイが表示される。

#### Step 2: BT-Aパネル(ノートモード)を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | select.hsp | `src/scene/select.hsp` | 1782-1873行目のBT-A単独押し処理 |

**主要処理フロー**:
1. **1782行目**: BT-A単独押し判定(`btkey.0=1` かつ `合計=1`)
2. **1790-1801行目**: 左右キーでshortmode/longmode/analogmodeの値を変更
3. **1808-1815行目**: 上下キーでjselnow(0-2)を切替
4. **1818-1873行目**: オーバーレイ画像生成(lang.1.1-1.8の多言語テキスト)

#### Step 3: BT-Bパネル(ゲージ/TURN)を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | select.hsp | `src/scene/select.hsp` | 1874-1934行目のBT-B単独押し処理 |

**主要処理フロー**:
- **1888-1893行目**: dselnow=0でeffratetype2変更、dselnow=1でturn変更
- **1912-1928行目**: ゲージタイプ/TURN値の多言語テキスト表示

#### Step 4: BT-Cパネル(アシスト/表示)を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | select.hsp | `src/scene/select.hsp` | 1935-2052行目のBT-C単独押し処理 |

**主要処理フロー**:
- **1950-1963行目**: sselnow別のオプション値変更(assisttick/autosync/vtiming/coloring/vmov)
- **1983-2046行目**: 各設定の多言語テキスト表示

#### Step 5: 判定詳細表示を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 5-1 | select.hsp | `src/scene/select.hsp` | 2276-2284行目のBT3個以上同時押し処理 |

**主要処理フロー**:
- **2276行目**: btkey合計>=3の判定
- **2277行目**: mscore配列からスコア詳細(CRITICAL/NEAR/ERROR/最大チェーン)を取得して表示

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

```
選曲画面メインループ
    |
    +-- btkey入力取得 (1776-1780行目)
    +-- optionfl=0 初期化 (1781行目)
    |
    +-- [BT-A単独: ノートモード] (1782-1873行目)
    |       +-- jselnow切替 (上下キー)
    |       +-- shortmode/longmode/analogmode変更 (左右キー)
    |       +-- オーバーレイ画像生成 -> optionfl=1
    |
    +-- [BT-B単独: ゲージ/TURN] (1874-1934行目)
    |       +-- dselnow切替 (上下キー)
    |       +-- effratetype2/turn変更 (左右キー)
    |       +-- *reloadscore/*refreshscore/*refreshsonginfo (stat3=1時)
    |       +-- オーバーレイ画像生成 -> optionfl=1
    |
    +-- [BT-C単独: アシスト/表示] (1935-2052行目)
    |       +-- sselnow切替 (上下キー)
    |       +-- assisttick/autosync/vtiming/coloring/vmov変更 (左右キー)
    |       +-- オーバーレイ画像生成 -> optionfl=1
    |
    +-- [BT3個以上: 判定詳細] (2276-2284行目)
    |       +-- mscore配列から詳細取得
    |       +-- オーバーレイ画像生成 -> optionfl=1
    |
    +-- [オーバーレイ描画] (2285行目)
            +-- optionfl=1の場合: alCopyImageToScreen(87, 画面右下)
```

### データフロー図

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

BT-Aキー + 方向キー ----------> shortmode/longmode/analogmode -> ノートモード値
BT-Bキー + 方向キー ----------> effratetype2/turn ------------> ゲージ/TURN値
BT-Cキー + 方向キー ----------> assisttick/autosync等 --------> 各設定値
                                     |
                               オーバーレイ画像生成(ID 87) ---> 画面右下表示
                                     |
                               stat3=1の場合:
                               *reloadscore -----------------> mscore更新
                               *refreshscore ----------------> sc/gr/md/pc更新
                               *refreshsonginfo -------------> 画面再描画
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| select.hsp | `src/scene/select.hsp` | ソース | インラインオプション変更の全ロジック(1782-2284行目) |
| kshootmania.hsp | `kshootmania.hsp` | ソース | shortmode/longmode/analogmode/effratetype/turn等の変数定義・config.ini保存 |
