# 機能設計書 39-ノートモード管理

## 概要

本ドキュメントは、K-Shoot MANIAのゲームプレイにおけるノートモード管理機能の設計を記述する。ON/OFF/HIDE/AUTOの各ノートモード設定をプレイに適用する機能である。

### 本機能の処理概要

**業務上の目的・背景**：プレイヤーが特定のノート種別（BTチップ、FXロング、レーザー）を個別に有効/無効/非表示/オートプレイに設定できるようにすることで、練習やアクセシビリティの向上を実現する。

**機能の利用シーン**：オプション設定画面または選曲画面でノートモードを設定し、ゲームプレイ開始時にprepareModeOptions関数が呼び出されて適用される。AUTO PLAYモード（auto=1）やADJUSTモード（adjmode=1）では自動的にモードが変更される。

**主要な処理内容**：
1. shortmode（BTチップノートモード）: mode_on/mode_off/mode_hide/mode_auto
2. longmode（FXロングノートモード）: mode_on/mode_off/mode_hide/mode_auto
3. analogmode（レーザーモード）: mode_on/mode_off/mode_hide/mode_auto
4. auto=1（AUTO PLAY）時: ON設定のモードを自動的にAUTOに変更
5. adjmode=1（ADJUST MODE）時: BTをON、FXとレーザーをHIDEに強制設定

**関連システム・外部連携**：オプション設定（option.hsp）、選曲画面（select.hsp）でのモード設定。

**権限による制御**：auto変数、adjmode変数でモードの強制変更が行われる。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 5 | ゲームプレイ画面 | 主画面 | prepareModeOptionsによるON/OFF/HIDE/AUTOの各ノートモード設定適用 |
| 8 | オプション設定画面 | 設定画面 | shortmodedef/longmodedef/analogmodedefによるBT/FX/LASERの各モード設定 |

## 機能種別

設定管理

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| auto | int | Yes | AUTO PLAYフラグ（0=通常, 1=AUTO） | 0または1 |
| adjmode | int | Yes | ADJUSTモードフラグ（0=通常, 1=ADJUST） | 0または1 |
| shortmode | int | Yes | BTチップノートモード | mode_on/mode_off/mode_hide/mode_auto |
| longmode | int | Yes | FXロングノートモード | mode_on/mode_off/mode_hide/mode_auto |
| analogmode | int | Yes | レーザーモード | mode_on/mode_off/mode_hide/mode_auto |

### 入力データソース

オプション設定画面（option.hsp）で設定されたshortmodedef/longmodedef/analogmodedef変数。config.iniからの読み込み。

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| shortmode | int | 適用後のBTチップノートモード |
| longmode | int | 適用後のFXロングノートモード |
| analogmode | int | 適用後のレーザーモード |
| kmode | int[3] | AUTO/ADJUST時の元のモード値バックアップ（復元用） |

### 出力先

- メモリ: 判定処理（processButtonNoteJudgment、processLaserNoteJudgment）でのモード参照

## 処理フロー

### 処理シーケンス

```
1. auto=1（AUTO PLAY）の場合
   ├─ kmode配列に元のモード値をバックアップ
   ├─ shortmode=mode_on → shortmode=mode_auto に変更
   ├─ longmode=mode_on → longmode=mode_auto に変更
   └─ analogmode=mode_on → analogmode=mode_auto に変更

2. adjmode=1（ADJUST MODE）の場合
   ├─ kmode配列に元のモード値をバックアップ
   ├─ shortmode=mode_on（BT有効）
   ├─ longmode=mode_hide（FX非表示）
   └─ analogmode=mode_hide（レーザー非表示）

3. プレイ終了時
   └─ kmode配列からモード値を復元
```

### フローチャート

```mermaid
flowchart TD
    A[prepareModeOptions] --> B{auto=1?}
    B -->|Yes| C[kmode = shortmode,longmode,analogmode]
    C --> D{shortmode=mode_on?}
    D -->|Yes| E[shortmode=mode_auto]
    D -->|No| F{longmode=mode_on?}
    E --> F
    F -->|Yes| G[longmode=mode_auto]
    F -->|No| H{analogmode=mode_on?}
    G --> H
    H -->|Yes| I[analogmode=mode_auto]
    H -->|No| J[完了]
    I --> J
    B -->|No| K{adjmode=1?}
    K -->|Yes| L[kmode = shortmode,longmode,analogmode]
    L --> M[shortmode=mode_on]
    M --> N[longmode=mode_hide]
    N --> O[analogmode=mode_hide]
    O --> J
    K -->|No| J
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-39-01 | AUTO変換 | auto=1時、ONモードのノートをAUTOモードに変更 | auto=1 |
| BR-39-02 | OFF/HIDE保持 | auto=1時、OFFまたはHIDEに設定されたモードはそのまま保持 | auto=1 |
| BR-39-03 | ADJUST強制 | adjmode=1時、BT=ON、FX=HIDE、LASER=HIDEに強制設定 | adjmode=1 |
| BR-39-04 | モード復元 | プレイ終了時にkmode配列から元のモード値を復元 | auto=1 or adjmode=1 |
| BR-39-05 | 判定制御 | mode_off: 判定無効、mode_hide: 非表示+判定無効、mode_auto: 自動判定 | 各モード時 |

### 計算ロジック

```
// AUTO PLAY時の変換
if auto == 1:
    kmode = [shortmode, longmode, analogmode]  // バックアップ
    if shortmode == mode_on: shortmode = mode_auto
    if longmode == mode_on: longmode = mode_auto
    if analogmode == mode_on: analogmode = mode_auto

// ADJUST MODE時の強制設定
if adjmode == 1:
    kmode = [shortmode, longmode, analogmode]  // バックアップ
    shortmode = mode_on
    longmode = mode_hide
    analogmode = mode_hide
```

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

本機能はデータベースを使用しない。

## エラー処理

### エラーケース一覧

特にエラーケースなし。

### リトライ仕様

リトライは不要。

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

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

## パフォーマンス要件

プレイ開始時に1回のみ実行。パフォーマンス上の懸念なし。

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

特になし。

## 備考

- mode_onは定数値2、mode_offは0、mode_hideは3、mode_autoは2（mode_auto=mode_onと同値の場合がある）
- kmode配列はprocessEscKeyInput関数内でプレイ終了時にモードを復元する際に使用される
- 判定処理内ではshortmode/longmode/analogmodeの値によって判定の有効/無効が制御される

---

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

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

### 推奨読解順序

#### Step 1: prepareModeOptions関数を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | play_game_logic.hsp | `src/scene/play/play_game_logic.hsp` | prepareModeOptions関数（95-110行目）の全体ロジック |

**主要処理フロー**:
- **96-102行目**: auto=1時のON→AUTO変換
- **103-109行目**: adjmode=1時の強制設定（BT=ON, FX=HIDE, LASER=HIDE）

**読解のコツ**: `mode_on`と`mode_auto`は別の定数値。`if(shortmode=mode_on):shortmode=mode_auto`のように、ONに設定されている場合のみAUTOに変更する。OFF/HIDEはそのまま。

#### Step 2: モード復元処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | play_key_input.hsp | `src/scene/play/play_key_input.hsp` | processEscKeyInput関数（116-120行目）でのkmode復元 |

**主要処理フロー**:
- **116行目**: `if(((auto=1)|(adjmode=1))&(length(kmode)=3))`
- **117-119行目**: shortmode=kmode.0, longmode=kmode.1, analogmode=kmode.2

#### Step 3: 判定処理でのモード参照を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | play_button_note.hsp | `src/scene/play/play_button_note.hsp` | shortmode/longmodeの値による判定制御の分岐 |
| 3-2 | play_laser_note.hsp | `src/scene/play/play_laser_note.hsp` | analogmodeの値による判定制御の分岐 |

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

```
start_play (play_init.hsp)
    |
    +-- prepareModeOptions (play_game_logic.hsp:95-110)
    |       +-- auto=1: ON → AUTO変換
    |       +-- adjmode=1: BT=ON, FX/LASER=HIDE
    |
    +-- on_update_play
    |       +-- processButtonNoteJudgment
    |       |       +-- shortmode/longmode参照で判定制御
    |       +-- processLaserNoteJudgment
    |               +-- analogmode参照で判定制御
    |
    +-- processEscKeyInput
            +-- kmode復元: shortmode/longmode/analogmode
```

### データフロー図

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

auto/adjmode  ────> prepareModeOptions         shortmode ──> 判定処理
shortmodedef  ────>   モード変換               longmode  ──> 判定処理
longmodedef   ────>   kmode保存                analogmode -> 判定処理
analogmodedef ────>                            kmode     ──> 復元用
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| play_game_logic.hsp | `src/scene/play/play_game_logic.hsp` | ソース | prepareModeOptions関数の実装 |
| play_init.hsp | `src/scene/play/play_init.hsp` | ソース | prepareModeOptionsの呼び出し（47行目） |
| play_key_input.hsp | `src/scene/play/play_key_input.hsp` | ソース | processEscKeyInputでのkmode復元 |
| play_button_note.hsp | `src/scene/play/play_button_note.hsp` | ソース | shortmode/longmode参照による判定制御 |
| play_laser_note.hsp | `src/scene/play/play_laser_note.hsp` | ソース | analogmode参照による判定制御 |
| option.hsp | `src/scene/option.hsp` | ソース | ノートモード設定UI |
