# 機能設計書 89-判定遅延設定

## 概要

本ドキュメントは、K-ShootManiaにおける入力遅延(inputdelay)・レーザー遅延(laserdelay)の調整機能の設計を記述する。オプション設定画面のページ1(ゲームプレイ設定)のselnow=6(入力遅延)およびselnow=7(レーザー遅延)として提供される。

### 本機能の処理概要

**業務上の目的・背景**：音楽ゲームにおいて、オーディオ出力デバイスの遅延やモニタの表示遅延により、プレイヤーの入力タイミングと実際の判定タイミングにズレが生じることがある。判定遅延設定により、プレイヤーはこのズレをms(ミリ秒)単位で手動補正し、正確な判定を得ることができる。入力遅延はBT/FXノートの判定タイミング、レーザー遅延はレーザーノートの判定タイミングをそれぞれ個別に調整する。

**機能の利用シーン**：オプション設定画面のページ1でselnow=6(入力遅延)またはselnow=7(レーザー遅延)を選択し、左右キーで1msec刻みの遅延値を調整する。正の値は判定位置を遅らせ(入力が早い場合)、負の値は判定位置を早める(入力が遅い場合)。

**主要な処理内容**：
1. judgedelay_config変数(入力遅延)の1ms刻み増減（範囲制限なし）
2. analogdelay_config変数(レーザー遅延)の1ms刻み増減（範囲制限なし）
3. config.iniへのinputdelay/laserdelay値の保存
4. プレイ時の判定タイミング補正への反映

**関連システム・外部連携**：プレイ画面の判定処理(play_game_logic.hsp, play_button_note.hsp, play_laser_note.hsp)

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

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 8 | オプション設定画面 | 主画面 | judgedelay_config/analogdelay_config変数による入力遅延・レーザー遅延のms単位調整 |

## 機能種別

設定変更 / 判定補正

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| judgedelay_config | int | Yes | 入力遅延補正値(msec) | 整数値（上限下限なし） |
| analogdelay_config | int | Yes | レーザー遅延補正値(msec) | 整数値（上限下限なし） |

### 入力データソース

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

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| judgedelay_config | int | 入力遅延補正値(msec) |
| analogdelay_config | int | レーザー遅延補正値(msec) |

### 出力先

- config.ini（inputdelay, laserdelay設定値）
- プレイ画面の判定タイミング補正

## 処理フロー

### 処理シーケンス

```
1. 左キー押下時
   ├─ selnow=6: judgedelay_config--
   └─ selnow=7: analogdelay_config--
2. 右キー押下時
   ├─ selnow=6: judgedelay_config++
   └─ selnow=7: analogdelay_config++
3. 表示
   ├─ 値=0: "0msec (補正なし)"
   ├─ 値>0: "+{値}msec (判定位置を遅らせます)"
   └─ 値<0: "{値}msec (判定位置を早くします)"
4. Esc押下時
   └─ *saveconfigでconfig.iniに保存
```

### フローチャート

```mermaid
flowchart TD
    A[selnow=6 or 7選択] --> B{左右キー?}
    B -->|左| C[delay_config--]
    B -->|右| D[delay_config++]
    C --> E[表示更新]
    D --> E
    E --> F{Esc押下?}
    F -->|No| B
    F -->|Yes| G[config.ini保存]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-89-01 | 範囲無制限 | judgedelay_config/analogdelay_configに上限下限なし | 常時 |
| BR-89-02 | 1ms刻み | 1回の操作で1msec増減 | 左右キー操作時 |
| BR-89-03 | 表示テキスト分岐 | 0: 補正なし(lang.3.34)、正: 遅延(lang.3.35)、負: 早送り(lang.3.36) | 表示時 |
| BR-89-04 | デフォルト値 | judgedelay_config=0, analogdelay_config=0 | 初回起動時 |
| BR-89-05 | config保存キー名 | inputdelay(入力遅延), laserdelay(レーザー遅延) | config.ini保存時 |
| BR-89-06 | globaloffset互換 | 旧バージョンのglobaloffset_configがjudgedelay_configに移行される | 起動時 |

### 計算ロジック

**判定タイミング補正**:
```
実効判定時刻 = 基準判定時刻 + judgedelay_config  (BT/FXノート)
実効判定時刻 = 基準判定時刻 + analogdelay_config (レーザーノート)
```

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

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

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

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

## エラー処理

### エラーケース一覧

特になし。値に上限下限はないが、極端な値は判定精度に悪影響を与える。

### リトライ仕様

なし。

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

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

## パフォーマンス要件

判定遅延補正はプレイ中のリアルタイム処理に影響するが、単純な加算演算のためパフォーマンスへの影響は無視できる。

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

特になし。

## 備考

- judgedelay_configは起動時にglobaloffset_configから移行される（旧バージョン互換処理: kshootmania.hsp 743行目）
- レーザー遅延(analogdelay_config)の表示テキストはlang.3.38/3.39で、入力遅延(lang.3.35/3.36)とは異なるラベルが使用される
- プレイ中にもCtrl+Alt+左右矢印キーでタイミング手動調整が可能(機能No.63)
- stat2=2（両方向矢印表示）が常時設定される（上限下限がないため）

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | kshootmania.hsp | `kshootmania.hsp` | **303-304行目**: judgedelay_config=0, analogdelay_config=0のデフォルト値、**302行目**: globaloffset_config=0 |

**読解のコツ**: judgedelay_configとglobaloffset_configは旧バージョン互換のために両方存在する。起動時にglobaloffset_configの値がjudgedelay_configに移行される(743行目)。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | option.hsp | `src/scene/option.hsp` | **287-290行目**: 左キーでjudgedelay_config--/analogdelay_config--、**438-441行目**: 右キーで++ |

**主要処理フロー**:
1. **287行目**: `judgedelay_config--` - 左キーで入力遅延1ms減
2. **289行目**: `analogdelay_config--` - 左キーでレーザー遅延1ms減
3. **438行目**: `judgedelay_config++` - 右キーで入力遅延1ms増
4. **440行目**: `analogdelay_config++` - 右キーでレーザー遅延1ms増
5. **640-671行目**: 表示処理（値の符号に応じたラベル分岐）

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | kshootmania.hsp | `kshootmania.hsp` | **618行目**: inputdelay読み込み、**621行目**: laserdelay読み込み、**1464-1465行目/1477-1478行目**: config保存 |

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

```
on_update_option (option.hsp:1)
    │
    ├─ 左右キー処理 (selnow=6/7)
    │      ├─ judgedelay_config増減 (selnow=6)
    │      └─ analogdelay_config増減 (selnow=7)
    │
    ├─ 表示処理 (pagenow=1)
    │      └─ *drawconfigitem (遅延値+説明ラベル)
    │
    └─ Esc押下時
           └─ *saveconfig → inputdelay/laserdelay保存

プレイ時参照:
play_game_logic.hsp ──> judgedelay_config参照
    └─ 判定タイミング = 基準時刻 + judgedelay_config

play_laser_note.hsp ──> analogdelay_config参照
    └─ t - analogdelay でレーザー判定タイミング補正
```

### データフロー図

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

左右キー操作        ───> delay_config増減           ───> 画面表示更新

config.ini          ───> inputdelay/laserdelay      ───> delay_config設定
(起動時)                  読み込み

globaloffset_config ───> judgedelay_configへ移行     ───> 旧バージョン互換
(互換処理)                (743行目)

delay_config値      ───> 判定タイミング補正          ───> BT/FX/LASER判定
(プレイ時)

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` | ソース | 入力遅延の判定タイミングへの適用 |
| play_laser_note.hsp | `src/scene/play/play_laser_note.hsp` | ソース | レーザー遅延の判定タイミングへの適用 |
| play_key_input.hsp | `src/scene/play/play_key_input.hsp` | ソース | タイミング手動調整(Ctrl+Alt+矢印) |
| config.ini | `config.ini` | 設定 | inputdelay/laserdelay設定値の保存 |
