# 機能設計書 34-FAST/SLOW表示

## 概要

本ドキュメントは、K-Shoot MANIAのゲームプレイにおけるFAST/SLOW表示機能の設計を記述する。NEAR判定時にプレイヤーの入力タイミングが早い（FAST）か遅い（SLOW）かを画面に表示する機能である。

### 本機能の処理概要

**業務上の目的・背景**：プレイヤーが自身のタイミング傾向を把握し、判定精度を向上させるためのフィードバック機能である。NEAR判定時のFAST/SLOWの偏りを可視化することで、プレイヤーはオフセット設定の調整指針を得られる。

**機能の利用シーン**：ゲームプレイ中、オプション設定でFAST/SLOW表示を有効（vtiming=1）にしている場合に、NEAR判定の発生時にタイミング方向を表示する。fast変数・slow変数にそれぞれの回数が累積され、結果画面で参照可能。

**主要な処理内容**：
1. オプション設定でvtiming=1が有効な場合にのみFAST/SLOW表示を行う
2. NEAR判定時にarstat.cnt.0（判定誤差時間）の正負でFAST/SLOWを判別
3. arstat.cnt.0 < 0（実際のタイミングが早い）→ SLOW（slow++）
4. arstat.cnt.0 > 0（実際のタイミングが遅い）→ FAST（fast++）
5. judge.cnt.1の値を4（SLOW）/5（FAST）に設定して表示種別を管理

**関連システム・外部連携**：特になし。

**権限による制御**：vtiming変数（オプション設定）で表示ON/OFFが切り替わる。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 5 | ゲームプレイ画面 | 主画面 | NEAR判定時のタイミングFAST/SLOW表示(vtiming変数による表示制御) |

## 機能種別

計算処理 / 表示制御

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| vtiming | int | Yes | FAST/SLOW表示有効フラグ（0=無効, 1=有効） | 0または1 |
| arstat.cnt.0 | int | Yes | 判定誤差時間（ノート時刻 - 入力時刻 + 補正値） | 整数（ms単位） |

### 入力データソース

ノート判定処理（processButtonNoteJudgment）内でのarstat配列の判定誤差値。vtimingはオプション設定（config.ini）から読み込まれる。

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| fast | int | FAST判定の累計回数 |
| slow | int | SLOW判定の累計回数 |
| judge.cnt.1 | int | 判定種別（2=NEAR, 4=SLOW, 5=FAST, 6=ERROR+vtiming） |

### 出力先

- 画面表示: ゲームプレイ画面の判定エフェクト表示（play_draw_frame.hsp）

## 処理フロー

### 処理シーケンス

```
1. NEAR判定が発生
2. vtiming=1の場合
   ├─ arstat.cnt.0 < 0 → slow++, judge.cnt.1=4
   └─ arstat.cnt.0 >= 0 → fast++, judge.cnt.1=5
3. vtiming=0の場合
   └─ judge.cnt.1=2（通常NEAR表示）
```

### フローチャート

```mermaid
flowchart TD
    A[NEAR判定発生] --> B{vtiming=1?}
    B -->|No| C["judge.cnt.1=2 (通常NEAR)"]
    B -->|Yes| D{"arstat.cnt.0 < 0?"}
    D -->|Yes| E["slow++, judge.cnt.1=4 (SLOW)"]
    D -->|No| F["fast++, judge.cnt.1=5 (FAST)"]
    C --> G[完了]
    E --> G
    F --> G
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-34-01 | FAST判定 | arstat.cnt.0 > 0（遅い入力）の場合にFAST判定 | vtiming=1かつNEAR判定時 |
| BR-34-02 | SLOW判定 | arstat.cnt.0 < 0（早い入力）の場合にSLOW判定 | vtiming=1かつNEAR判定時 |
| BR-34-03 | 表示制御 | vtiming=0の場合はFAST/SLOW表示を行わない | vtiming=0 |
| BR-34-04 | judge値マッピング | 4=SLOW, 5=FAST, 6=ERROR+vtiming | vtiming=1 |

### 計算ロジック

```
// arstat.cnt.0 = ノート時刻 - (入力時刻 - judgedelay) + de
// arstat.cnt.0 < 0 → 入力が早い(SLOW表示)
// arstat.cnt.0 > 0 → 入力が遅い(FAST表示)

if vtiming == 1:
    if arstat.cnt.0 < 0:
        slow++
        judge.cnt.1 = 4  // SLOW
    else:
        fast++
        judge.cnt.1 = 5  // FAST
```

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

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

## エラー処理

### エラーケース一覧

特にエラーケースなし。vtiming=0の場合は単にスキップされる。

### リトライ仕様

リトライは不要。

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

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

## パフォーマンス要件

NEAR判定ごとに実行される単純な条件分岐。パフォーマンス上の懸念なし。

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

特になし。

## 備考

- arstat.cnt.0の符号は「ノート時刻 - 入力時刻」で計算される。負の値は入力が早い（SLOW）、正の値は入力が遅い（FAST）を意味する
- judge.cnt.1の値はplay_draw_frame.hspで描画時に参照される
- BT/FXどちらのNEAR判定時にも同じロジックが適用される

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | play_button_note.hsp | `src/scene/play/play_button_note.hsp` | judge配列のデータ構造: judge.cnt.0=時刻、judge.cnt.1=判定種別 |

**読解のコツ**: judge.cnt.1の値は 1=ERROR, 2=NEAR, 3=CRITICAL, 4=SLOW, 5=FAST, 6=ERROR(vtiming表示)。vtimingが有効な場合、NEAR(2)がSLOW(4)/FAST(5)に置き換わる。

#### Step 2: BT NEAR判定でのFAST/SLOW分岐を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | play_button_note.hsp | `src/scene/play/play_button_note.hsp` | BTチップNEAR判定時のFAST/SLOW分岐（47-67行目）を確認 |

**主要処理フロー**:
- **47-48行目**: `if(arstat.cnt.0<0) → slow++`
- **49-50行目**: `else → fast++`
- **61-66行目**: `if(vtiming=1) → judge.cnt.1=4(SLOW)/5(FAST)`

#### Step 3: FX NEAR判定でのFAST/SLOW分岐を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | play_button_note.hsp | `src/scene/play/play_button_note.hsp` | FXチップNEAR判定時の同様の分岐（187-214行目）を確認 |

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

```
on_update_play (play_update.hsp)
    |
    +-- processButtonNoteJudgment (play_button_note.hsp)
            |
            +-- BT NEAR判定 (47-67行目)
            |       +-- arstat.cnt.0 < 0 → slow++, judge.cnt.1=4
            |       +-- arstat.cnt.0 >= 0 → fast++, judge.cnt.1=5
            |
            +-- FX NEAR判定 (187-214行目)
                    +-- 同上のロジック
```

### データフロー図

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

arstat.cnt.0  ─────> FAST/SLOW判定          fast/slow ──> 累計カウント
(判定誤差)                                  judge.cnt.1 -> play_draw_frame.hsp
vtiming       ─────> 表示ON/OFF制御                      (FAST/SLOW表示)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| play_button_note.hsp | `src/scene/play/play_button_note.hsp` | ソース | FAST/SLOW判定ロジックの実装（BT/FXノート） |
| play_draw_frame.hsp | `src/scene/play/play_draw_frame.hsp` | ソース | judge.cnt.1に基づくFAST/SLOW表示の描画 |
| play_game_logic.hsp | `src/scene/play/play_game_logic.hsp` | ソース | vtiming変数の参照 |
| option.hsp | `src/scene/option.hsp` | ソース | vtiming設定のUI |
