# 機能設計書 90-HiSpeed設定

## 概要

本ドキュメントは、K-ShootManiaにおけるx倍速/C値/m値/a値/オフセット値の5種類のHiSpeed方式設定機能の設計を記述する。オプション設定画面のページ2(HiSpeed設定)のselnow=0〜4として提供される。

### 本機能の処理概要

**業務上の目的・背景**：音楽ゲームにおいてHiSpeed(ハイスピード)はノートのスクロール速度を調整する重要な設定である。BPMが異なる楽曲でも一定の視認性を確保するため、K-ShootManiaは5種類のHiSpeed方式を提供する。プレイヤーは自分のプレイスタイルに合った方式を選択・有効化し、プレイ中にリアルタイムで速度調整を行える。

**機能の利用シーン**：オプション設定画面のページ2で各HiSpeed方式(selnow=0:x倍速, selnow=1:C値, selnow=2:m値, selnow=3:a値, selnow=4:オフセット値)の表示/非表示を切り替える。有効化した方式はプレイ中のHiSpeed変更操作で選択可能になる。

**主要な処理内容**：
1. vhstype配列[5]による各HiSpeed方式の表示(1)/非表示(0)の切替
2. 5種類のHiSpeed方式の有効/無効管理
3. config.iniへのhispeedtype値の保存（有効な方式をカンマ区切りで列挙）
4. 全方式非表示の場合のフォールバック処理（x倍速とオフセット値を自動有効化）

**関連システム・外部連携**：プレイ画面のHiSpeed制御(play_key_input.hsp)

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

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 8 | オプション設定画面 | 主画面 | vhstype配列によるx倍速/C値/m値/a値/オフセット値の5種類HiSpeed方式の有効/無効設定 |

## 機能種別

設定変更

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| vhstype | int配列[5] | Yes | 各HiSpeed方式の有効(1)/無効(0) | 各要素0 or 1 |
| vhstype.0 | int | Yes | x倍速方式(0:非表示/1:表示) | 0 or 1 |
| vhstype.1 | int | Yes | C値方式(0:非表示/1:表示) | 0 or 1 |
| vhstype.2 | int | Yes | m値方式(0:非表示/1:表示) | 0 or 1 |
| vhstype.3 | int | Yes | a値方式(0:非表示/1:表示) | 0 or 1 |
| vhstype.4 | int | Yes | オフセット値方式(0:非表示/1:表示) | 0 or 1 |

### 入力データソース

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

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| vhstype | int配列[5] | 各HiSpeed方式の有効/無効状態 |

### 出力先

- config.ini（hispeedtype設定値、有効方式をカンマ区切りで保存）

## 処理フロー

### 処理シーケンス

```
1. 左キー押下時（pagenow=2, selnow=0〜4）
   └─ vhstype.(selnow)-- (最小0でクランプ)
2. 右キー押下時
   └─ vhstype.(selnow)++ (最大1でクランプ)
3. 表示
   ├─ 0: lang.3.53 (非表示)
   └─ 1: lang.3.54 (表示)
4. Esc押下時（pagenow=-1から外部へ）
   ├─ 全方式非表示チェック: sum(vhstype)=0の場合
   │   └─ vhstype=1,1,0,0,0にリセット（x倍速とC値を自動有効化）
   └─ *saveconfigでconfig.iniに保存
```

### フローチャート

```mermaid
flowchart TD
    A[pagenow=2, selnow=0-4] --> B{左右キー?}
    B -->|左| C[vhstype.selnow-- クランプ0]
    B -->|右| D[vhstype.selnow++ クランプ1]
    C --> E[表示更新]
    D --> E
    E --> F{Esc押下?}
    F -->|No| B
    F -->|Yes| G{sum vhstype = 0?}
    G -->|Yes| H[vhstype = 1,1,0,0,0にリセット]
    G -->|No| I[現在値維持]
    H --> J[config.ini保存]
    I --> J
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-90-01 | 二値制御 | 各方式は0(非表示)または1(表示)の二値 | 左右キー操作時 |
| BR-90-02 | 全非表示フォールバック | 全方式が非表示の場合、x倍速(0)とC値(1)を自動有効化: vhstype=1,1,0,0,0 | Esc押下時(pagenow=-1) |
| BR-90-03 | デフォルト値 | vhstype=1,1,0,0,0（x倍速とC値が有効） | 初回起動時 |
| BR-90-04 | config保存形式 | 有効な方式の識別子をカンマ区切りで保存（例: "x,C"） | config.ini保存時 |
| BR-90-05 | 方式識別子 | x(倍速), C(C値), m(m値), a(a値), O(オフセット) | config読み書き時 |
| BR-90-06 | 空文字列フォールバック | hispeedtype文字列が空の場合 "x,O" にリセット | config保存時 |

### 計算ロジック

**config保存文字列構築**:
```
vhstypestat = ""
if vhstype.0=1: vhstypestat += "x,"
if vhstype.1=1: vhstypestat += "C,"
if vhstype.2=1: vhstypestat += "m,"
if vhstype.3=1: vhstypestat += "a,"
if vhstype.4=1: vhstypestat += "O,"
if vhstypestat="": vhstypestat = "x,O,"
// 末尾のカンマを除去して保存
```

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

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

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

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

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | 全方式非表示 | 全てのvhstypeが0 | vhstype=1,1,0,0,0にリセット |
| - | config空文字列 | hispeedtype保存文字列が空 | "x,O"にリセット |

### リトライ仕様

なし。

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

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

## パフォーマンス要件

特になし。

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

特になし。

## 備考

- 5種類のHiSpeed方式の意味：
  - **x倍速**: BPMに対する固定倍率（例: x10 = BPM*10）
  - **C値(Constant)**: BPMに関わらず一定のスクロール速度
  - **m値**: 最大BPMに基づくスクロール速度
  - **a値**: 平均BPMに基づくスクロール速度
  - **O値(Offset)**: 基準速度からのオフセット値
- ページ2にはselnow=5(マウスカーソル非表示)とselnow=6(テンキー使用)も含まれるが、それらはHiSpeed設定とは別の機能
- プレイ中のHiSpeed変更はFXボタン長押し+BTキーで行う(機能No.62)

---

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

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

### 推奨読解順序

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

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

**読解のコツ**: vhstypeは5要素のint配列で、インデックス0-4がそれぞれx/C/m/a/O方式に対応する。config.iniではカンマ区切り文字列"x,C"のような形式で保存される。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | option.hsp | `src/scene/option.hsp` | **304-314行目**: 左右キーでのvhstype値変更、**718-741行目**: ページ2の表示処理 |

**主要処理フロー**:
1. **308-310行目**: 左キーでvhstype.(selnow)-- + 0クランプ
2. **459-461行目**: 右キーでvhstype.(selnow)++ + 1クランプ
3. **721-727行目**: repeat 5ループでの5方式表示
4. **725行目**: vhstype.cnt=0で非表示(lang.3.53)、=1で表示(lang.3.54)
5. **1062-1067行目**: Esc時の全非表示フォールバック

#### Step 3: config読み書きを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | kshootmania.hsp | `kshootmania.hsp` | **435-445行目**: config読み込み(hispeedtype解析)、**1468-1476行目**: config保存(文字列構築) |

**主要処理フロー**:
- **435-445行目**: hispeedtypeの解析。カンマ区切り文字列をsplitし、各識別子(x/C/m/a/O)に対応するvhstype要素を1に設定
- **1468-1476行目**: 保存文字列の構築。有効な方式の識別子をカンマ区切りで連結し、末尾カンマを除去

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

```
on_update_option (option.hsp:1)
    │
    ├─ 左右キー処理 (selnow=0-4)
    │      └─ vhstype.(selnow)増減 + クランプ(0-1)
    │
    ├─ 表示処理 (pagenow=2)
    │      └─ repeat 5 ─ *drawconfigitem (表示/非表示ラベル)
    │
    └─ Esc押下時 (pagenow=-1)
           ├─ 全非表示フォールバック (1062-1067行目)
           │      └─ sum(vhstype)=0 → vhstype=1,1,0,0,0
           └─ *saveconfig
                  └─ hispeedtype文字列構築 (1468-1476行目)
                         └─ notesave "config.ini"
```

### データフロー図

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

左右キー操作        ───> vhstype.(selnow)変更      ───> 画面表示更新
                         (0/1切替)

config.ini          ───> hispeedtype解析            ───> vhstype配列設定
(起動時)                  "x,C" → vhstype=1,1,0,0,0
                          (435-445行目)

Esc押下             ───> 全非表示チェック           ───> フォールバック
                         vhstype文字列構築                config.ini保存

vhstype配列         ───> プレイ中HiSpeed選択       ───> 利用可能方式の制限
(プレイ時)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| option.hsp | `src/scene/option.hsp` | ソース | HiSpeed方式設定の操作処理 |
| kshootmania.hsp | `kshootmania.hsp` | ソース | 変数初期化・config読み込み(hispeedtype解析)・保存 |
| play_key_input.hsp | `src/scene/play/play_key_input.hsp` | ソース | プレイ中のHiSpeed変更操作処理 |
| config.ini | `config.ini` | 設定 | hispeedtype設定値の保存 |
