# 機能設計書 88-レーザー入力方式設定

## 概要

本ドキュメントは、K-ShootManiaにおけるキーボード/PowerMate/マウス/スティック/スライダー/Z軸の6種類のレーザー(アナログ)入力方式切替機能の設計を記述する。オプション設定画面のページ1(ゲームプレイ設定)のselnow=3として提供される。

### 本機能の処理概要

**業務上の目的・背景**：K-ShootManiaのレーザーノートは左右のアナログ操作を必要とする独自のゲームプレイ要素である。プレイヤーが使用するコントローラの種類はさまざまであり、キーボード、Griffin PowerMate、マウス、アナログスティック、専用スライダーコントローラ、Z軸入力など多様な入力デバイスに対応する必要がある。本機能によりプレイヤーは自分の環境に最適な入力方式を選択できる。

**機能の利用シーン**：オプション設定画面のページ1でselnow=3を選択し、左右キーで入力方式を切り替える。入力方式の選択はプレイ時のレーザーノート操作に直接影響する。

**主要な処理内容**：
1. analoginput変数の6段階切替（特殊な遷移順序: 0→4→2→1→3→5）
2. 各入力方式に対応する入力処理の選択（play_key_input.hsp）
3. config.iniへのlaserinput値の保存

**関連システム・外部連携**：各種入力デバイスドライバ、PowerMate API、マウスAPI

**権限による制御**：特になし。全プレイヤーが変更可能。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 8 | オプション設定画面 | 主画面 | analoginput変数による6種類入力方式切替 |

## 機能種別

設定変更 / 入力制御

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| analoginput | int | Yes | レーザー入力方式(0:キーボード/1:PowerMate/2:マウス/3:スティック/4:スライダー/5:Z軸) | 0-5 |

### 入力データソース

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

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| analoginput | int | レーザー入力方式(0-5) |

### 出力先

- config.ini（laserinput設定値）
- プレイ画面の入力処理選択

## 処理フロー

### 処理シーケンス

```
1. 左キー押下時（pagenow=1, selnow=3）
   └─ analoginput遷移（右方向への逆順）
      ├─ 4→0, 2→4, 1→2, 3→1, 5→3
      └─ 0は左端（遷移なし）
2. 右キー押下時
   └─ analoginput遷移（右方向）
      ├─ 0→4, 4→2, 2→1, 1→3, 3→5
      └─ 5は右端（遷移なし）
3. 表示
   ├─ 0: lang.3.20 (キーボードプレイ)
   ├─ 4: lang.3.24 (専用コントローラ/デジタルスライダー)
   ├─ 2: lang.3.22 (専用コントローラ/マウスX/Y座標)
   ├─ 1: lang.3.21 (PowerMate)
   ├─ 3: lang.3.23 (アナログスティック)
   └─ 5: lang.3.25 (ジョイスティックX/Y座標)
4. Esc押下時
   └─ *saveconfigでconfig.iniに保存
```

### フローチャート

```mermaid
flowchart TD
    A[selnow=3選択] --> B{左右キー?}
    B -->|左| C{現在の値?}
    C -->|4| C0[analoginput=0]
    C -->|2| C1[analoginput=4]
    C -->|1| C2[analoginput=2]
    C -->|3| C3[analoginput=1]
    C -->|5| C4[analoginput=3]
    B -->|右| D{現在の値?}
    D -->|0| D0[analoginput=4]
    D -->|4| D1[analoginput=2]
    D -->|2| D2[analoginput=1]
    D -->|1| D3[analoginput=3]
    D -->|3| D4[analoginput=5]
    C0 --> E[表示更新]
    C1 --> E
    C2 --> E
    C3 --> E
    C4 --> E
    D0 --> E
    D1 --> E
    D2 --> E
    D3 --> E
    D4 --> E
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-88-01 | 非連続遷移 | 値の増減ではなく、固定の遷移テーブル(0→4→2→1→3→5)に従う | 左右キー操作時 |
| BR-88-02 | 遷移順序 | 表示順: キーボード(0)→スライダー(4)→マウス(2)→PowerMate(1)→スティック(3)→Z軸(5) | UI表示順 |
| BR-88-03 | デフォルト値 | analoginput=0(キーボード) | 初回起動時 |
| BR-88-04 | config保存キー名 | laserinput（旧名analoginput） | config.ini保存時 |

### 計算ロジック

特になし。固定遷移テーブルによる値切替。

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

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

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

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

## エラー処理

### エラーケース一覧

特になし。

### リトライ仕様

なし。

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

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

## パフォーマンス要件

特になし。

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

特になし。

## 備考

- analoginputの値と入力方式の対応: 0=キーボード, 1=PowerMate, 2=マウスXY, 3=アナログスティック, 4=デジタルスライダー, 5=ジョイスティックXY(-127〜127)
- 値の遷移順序が連続的でないのは、追加実装された入力方式の番号が時系列順に割り当てられたためと推定される
- config.iniではlaserinputキーで保存されるが、旧バージョンではanaloginputキーも読み込みに対応(互換性処理)

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | kshootmania.hsp | `kshootmania.hsp` | **287行目**: analoginput=0のデフォルト値 |

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | option.hsp | `src/scene/option.hsp` | **270-281行目**: 左キーでの遷移テーブル、**421-432行目**: 右キーでの遷移テーブル |

**主要処理フロー**:
1. **270-281行目**: 左キーの遷移チェーン(if-else-if構造)
2. **421-432行目**: 右キーの遷移チェーン(if-else-if構造)
3. **615-624行目**: 各方式の表示ラベル

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | kshootmania.hsp | `kshootmania.hsp` | **447-448行目**: config読み込み(laserinput)、**1416-1419行目**: config保存(laserinput/analoginput互換) |

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

```
on_update_option (option.hsp:1)
    │
    ├─ 左右キー処理 (selnow=3)
    │      └─ analoginput遷移テーブル(0⇔4⇔2⇔1⇔3⇔5)
    │
    ├─ 表示処理 (pagenow=1)
    │      └─ *drawconfigitem (入力方式ラベル)
    │
    └─ Esc押下時
           └─ *saveconfig → laserinput保存

プレイ時参照:
play_key_input.hsp ──> analoginput値で入力処理分岐
    ├─ 0: キーボードアナログ処理
    ├─ 1: PowerMate入力処理
    ├─ 2: マウスXY座標入力処理
    ├─ 3: アナログスティック入力処理
    ├─ 4: スライダー入力処理
    └─ 5: Z軸入力処理
```

### データフロー図

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

左右キー操作        ───> analoginput遷移テーブル   ───> 画面表示更新

config.ini          ───> laserinput読み込み         ───> analoginput設定
(起動時)                  (447-448行目)

analoginput値       ───> play_key_input.hsp          ───> レーザー入力処理
(プレイ時)                入力方式分岐

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

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| option.hsp | `src/scene/option.hsp` | ソース | レーザー入力方式設定の操作処理 |
| kshootmania.hsp | `kshootmania.hsp` | ソース | 変数初期化・config読み込み・保存 |
| play_key_input.hsp | `src/scene/play/play_key_input.hsp` | ソース | プレイ時のアナログ入力処理 |
| config.ini | `config.ini` | 設定 | laserinput設定値の保存 |
