# 機能設計書 87-ノートモード設定

## 概要

本ドキュメントは、K-ShootManiaにおけるBT/FX/LASERの各ノートモード(ON/OFF/HIDE/AUTO)を設定する機能の設計を記述する。オプション設定画面のページ1(ゲームプレイ設定)のselnow=0〜2として提供される。

### 本機能の処理概要

**業務上の目的・背景**：音楽ゲームの練習において、特定のノートタイプに集中して練習したい場合や、特定レーンを非表示にして難易度を調整したい場合がある。ノートモード設定により、BT(ショートノート)、FX(ロングノート)、LASER(アナログレーザー)の各ノートタイプについて表示・判定の有無を個別に制御できる。AUTO設定はオートプレイとして機能し、HIDE設定はノート非表示での手動プレイを可能にする。

**機能の利用シーン**：オプション設定画面のページ1でselnow=0(BT)、selnow=1(FX)、selnow=2(LASER)を選択し、左右キーでON/OFF/HIDE/AUTOの4モードを切り替える。これらの設定はプレイ開始時に適用される。

**主要な処理内容**：
1. shortmodedef(BT)、longmodedef(FX)、analogmodedef(LASER)の3変数を0-3の4段階で管理
2. 各変数の即時コピー（shortmode=shortmodedef等）によるプレイ用変数への反映
3. config.iniへのbt_mode/fx_mode/laser_mode値の保存
4. プレイ画面でのprepareModeOptionsによるノートモード適用

**関連システム・外部連携**：プレイ画面ゲームロジック(play_game_logic.hsp)

**権限による制御**：OFF/HIDE/AUTOモードを使用した場合、スコア結果にアシスト表記が付与される。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 8 | オプション設定画面 | 主画面 | shortmodedef/longmodedef/analogmodedefによるBT/FX/LASERの各ON/OFF/HIDE/AUTO設定 |

## 機能種別

設定変更

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| shortmodedef | int | Yes | BTノートモード(0:ON/1:OFF/2:AUTO/3:HIDE) | 0-3 |
| longmodedef | int | Yes | FXノートモード(0:ON/1:OFF/2:AUTO/3:HIDE) | 0-3 |
| analogmodedef | int | Yes | LASERノートモード(0:ON/1:OFF/2:AUTO/3:HIDE) | 0-3 |

### 入力データソース

- オプション設定画面上の左右キー操作
- config.iniのbt_mode/fx_mode/laser_mode設定値

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| shortmodedef | int | BTノートモード |
| longmodedef | int | FXノートモード |
| analogmodedef | int | LASERノートモード |
| shortmode | int | プレイ用BTモード（=shortmodedef） |
| longmode | int | プレイ用FXモード（=longmodedef） |
| analogmode | int | プレイ用LASERモード（=analogmodedef） |

### 出力先

- config.ini（bt_mode, fx_mode, laser_mode設定値）
- プレイ画面のノートモード制御変数

## 処理フロー

### 処理シーケンス

```
1. 左キー押下時（pagenow=1, selnow=0/1/2）
   ├─ selnow=0: shortmodedef-- (最小0でクランプ)、shortmode=shortmodedef
   ├─ selnow=1: longmodedef-- (最小0でクランプ)、longmode=longmodedef
   └─ selnow=2: analogmodedef-- (最小0でクランプ)、analogmode=analogmodedef
2. 右キー押下時
   ├─ selnow=0: shortmodedef++ (最大3でクランプ)、shortmode=shortmodedef
   ├─ selnow=1: longmodedef++ (最大3でクランプ)、longmode=longmodedef
   └─ selnow=2: analogmodedef++ (最大3でクランプ)、analogmode=analogmodedef
3. 表示
   ├─ 0: lang.3.16 (ON - 表示あり・判定あり)
   ├─ 1: lang.3.17 (OFF - 表示あり・判定なし)
   ├─ 2: lang.3.18 (AUTO - 表示あり・オートプレイ)
   └─ 3: lang.3.19 (HIDE - 表示なし・判定なし)
4. Esc押下時
   └─ *saveconfigでconfig.iniに保存
```

### フローチャート

```mermaid
flowchart TD
    A[pagenow=1, selnow=0-2] --> B{selnow?}
    B -->|0| C[shortmodedef変更]
    B -->|1| D[longmodedef変更]
    B -->|2| E[analogmodedef変更]
    C --> F[shortmode同期]
    D --> G[longmode同期]
    E --> H[analogmode同期]
    F --> I[表示更新]
    G --> I
    H --> I
    I --> J{Esc押下?}
    J -->|No| A
    J -->|Yes| K[config.ini保存]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-87-01 | モード範囲制限 | 0(ON)〜3(HIDE)の4段階に制限 | 左右キー操作時 |
| BR-87-02 | 即時同期 | shortmodedef変更時にshortmode=shortmodedefで即時コピー | 値変更時 |
| BR-87-03 | アシスト判定 | shortmode+longmode+analogmode>0の場合、結果にアシスト表記 | リザルト画面 |
| BR-87-04 | デフォルト値 | shortmodedef=0(ON), longmodedef=0(ON), analogmodedef=0(ON) | 初回起動時 |
| BR-87-05 | config保存キー名 | bt_mode(BT), fx_mode(FX), laser_mode(LASER) | config.ini保存時 |

### 計算ロジック

特になし。

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

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

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

| 操作 | 対象ファイル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| 設定保存 | config.ini | WRITE | bt_mode, fx_mode, laser_mode値の保存 |

## エラー処理

### エラーケース一覧

特になし。

### リトライ仕様

なし。

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

config.iniへの保存は*saveconfigサブルーチンによる一括書き込み。

## パフォーマンス要件

設定変更は即座に反映される。

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

特になし。

## 備考

- analogmodedefのデフォルトは0(ON)だが、kshootmania.hspの初期値ではanalogmode=1(OFF)に設定されている点に注意。analogmodedefが0の場合はanalogmode=0に上書きされる。
- ノートモードがON以外の場合、リザルト画面でクリアステータスに「ASSIST」接頭辞が付与される
- 選曲画面からもインラインオプション変更機能でノートモードを変更可能

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | kshootmania.hsp | `kshootmania.hsp` | **288-293行目**: shortmode/longmode/analogmode/shortmodedef/longmodedef/analogmodedefの初期値 |

**読解のコツ**: xxxmodedefが設定用の永続変数、xxxmodeがプレイ時の実効変数。設定変更時に即座にコピーされるが、選曲画面のインラインオプションではxxxmodeのみ変更される場合がある。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | option.hsp | `src/scene/option.hsp` | **258-269行目**: 左キーでのモード値減少、**409-420行目**: 右キーでのモード値増加 |

**主要処理フロー**:
1. **258-261行目**: shortmodedef-- + クランプ + shortmode同期
2. **262-265行目**: longmodedef-- + クランプ + longmode同期
3. **266-269行目**: analogmodedef-- + クランプ + analogmode同期
4. **590-614行目**: 各ノートモードの表示処理

#### Step 3: config保存を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | kshootmania.hsp | `kshootmania.hsp` | **512-520行目**: config読み込み(bt_mode/fx_mode/laser_mode)、**1384-1389行目**: config保存 |

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

```
on_update_option (option.hsp:1)
    │
    ├─ 左右キー処理 (selnow=0-2)
    │      ├─ shortmodedef増減 → shortmode同期
    │      ├─ longmodedef増減 → longmode同期
    │      └─ analogmodedef増減 → analogmode同期
    │
    ├─ 表示処理 (pagenow=1)
    │      └─ *drawconfigitem (ON/OFF/AUTO/HIDEラベル)
    │
    └─ Esc押下時
           └─ *saveconfig → bt_mode/fx_mode/laser_mode保存

プレイ時参照:
play_game_logic.hsp ──> prepareModeOptions
    ├─ shortmode → BTノート判定制御
    ├─ longmode → FXノート判定制御
    └─ analogmode → LASERノート判定制御
```

### データフロー図

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

左右キー操作        ───> xxxmodedef変更(0-3)         ───> xxxmode同期
                                                           画面表示更新

config.ini          ───> bt_mode/fx_mode/             ───> xxxmodedef設定
(起動時)                  laser_mode読み込み

xxxmode値           ───> prepareModeOptions            ───> ノート判定制御
(プレイ時)                (play_game_logic.hsp)

Escキー押下         ───> *saveconfig                  ───> config.ini更新
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| option.hsp | `src/scene/option.hsp` | ソース | ノートモード設定の操作処理 |
| kshootmania.hsp | `kshootmania.hsp` | ソース | 変数初期化・config読み込み・保存 |
| play_game_logic.hsp | `src/scene/play/play_game_logic.hsp` | ソース | prepareModeOptionsによるモード適用 |
| config.ini | `config.ini` | 設定 | bt_mode/fx_mode/laser_mode設定値の保存 |
