# 機能設計書 29-FXノート判定

## 概要

本ドキュメントは、FXボタンのチップノート（ショート）およびロングノートに対するCRITICAL / NEAR / ERROR の3段階判定処理機能の設計を記述する。

### 本機能の処理概要

**業務上の目的・背景**：K-Shoot MANIAにはBTノート（4レーン）に加えてFXノート（2レーン: FX-L/FX-R）が存在する。FXノートはオーディオエフェクトの適用と連動しており、ボタン押下時にリアルタイムでエフェクトが適用される特徴がある。判定ロジック自体はBTノートと類似しているが、ロングノートの構造とエフェクト連動が異なる。

**機能の利用シーン**：processButtonNoteJudgment関数内で、BTノート判定と同一の関数内でFXノート判定（cnt>3, cnt<=5）も処理される。play_update.hspから毎フレーム呼び出される。

**主要な処理内容**：
1. FXショートノート（cnt>3, cnt<=5, note.2=0）のCRITICAL/NEAR/ERROR判定
2. FXロングノート（cnt>3, cnt<=5, note.2>0）の押下開始判定と継続判定
3. 判定結果に基づくスコア加算（lscore: CRITICAL+2, NEAR+1）
4. チェーンカウント更新
5. ゲージ増減処理
6. オートプレイモード（longmode=mode_auto）での自動判定
7. ロングノート離し時のERROR処理

**関連システム・外部連携**：FXノートのロングは音楽エフェクトの適用区間と対応している。play_audio_effects.hspでFXボタンの押下状態に連動してエフェクトが適用される。

**権限による制御**：ノートモード（longmode: ON/OFF/HIDE/AUTO）により判定処理が変化する。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 5 | ゲームプレイ画面 | 主画面 | FXノートのリアルタイム判定処理 |

## 機能種別

計算処理 / リアルタイム判定

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| keystat[7][11] | int配列 | Yes | キー入力状態（現在フレーム） | 0または1 |
| keystatp[7][11] | int配列 | Yes | キー入力状態（前フレーム） | 0または1 |
| arstat[8][3] | int配列 | Yes | 判定対象ノート情報 | specifyJudgmentTargetで設定済み |
| note[131072][8] | int配列 | Yes | ノートデータ | 展開済み |
| longmode | int | Yes | FXノートモード | ON/OFF/HIDE/AUTO |
| t | int | Yes | 現在の再生時間(ms) | - |
| judgedelay | int | Yes | 判定遅延値(ms) | - |

### 入力データソース

キーボード/ジョイスティック入力、譜面データ配列

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| noteresult[] | int配列 | 判定結果 |
| judge[6][2] | int配列 | レーン別判定情報 |
| chainnow | int | 現在のチェーン数 |
| lscore | int | FXノートスコア加算値 |
| longstat[2] | int配列 | FXロングノート押下状態 |
| gauge | int | ゲージ値 |

### 出力先

ゲーム内部変数

## 処理フロー

### 処理シーケンス

```
1. FXショートノート判定（cnt>3, cnt<=5, note.2=0）
   ├─ キー押下エッジ検出（keystat=1, keystatp=0）
   ├─ 差分値(dis)を計算
   ├─ dis<43: CRITICAL判定 → lscore+=2
   ├─ dis<113: NEAR判定 → lscore+=1
   ├─ dis<250: ERROR判定（HARDゲージ時は±150ms）
   └─ それ以外: 待機
2. FXロングノート判定（cnt>3, cnt<=5, note.2>0）
   ├─ 押下開始検出 → longstat設定
   ├─ 継続判定（longj配列で区間チェック）
   │   └─ 区間到達時: CRITICAL加算
   └─ 離し判定
       └─ 残区間: ERROR処理
3. オートプレイ処理
   └─ longmode=mode_auto: ノート到達時に自動CRITICAL
4. 自動ERROR処理
   └─ 110ms超過で未判定ノートをERROR
```

### フローチャート

```mermaid
flowchart TD
    A[FXノート判定開始] --> B{FXショート? cnt>3, note.2=0}
    B -->|Yes| C[差分計算]
    C --> D{dis < 43?}
    D -->|Yes| E[CRITICAL: lscore+=2]
    D -->|No| F{dis < 113?}
    F -->|Yes| G[NEAR: lscore+=1]
    F -->|No| H{dis < 250?}
    H -->|Yes| I[ERROR]
    H -->|No| J[待機]
    B -->|No| K{FXロング? cnt>3, note.2>0}
    K -->|Yes| L[ロング判定処理]
    K -->|No| M[処理終了]
    L --> N{押下中?}
    N -->|Yes| O[区間判定: longj配列]
    N -->|No| P[離しERROR処理]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-29-01 | CRITICAL判定窓 | 入力差分±43ms以内でCRITICAL | FXショートノート |
| BR-29-02 | NEAR判定窓 | 入力差分±113ms以内でNEAR | FXショートノート |
| BR-29-03 | ERROR判定窓 | 入力差分±250ms以内でERROR（HARDゲージ時は±150ms） | FXショートノート |
| BR-29-04 | スコア変数 | FXノートのスコアはlscore変数に加算（BTはnscore） | スコア計算時 |
| BR-29-05 | ロング区間判定 | longj配列の区間到達でCRITICAL、区間内に離すとERROR | FXロングノート |
| BR-29-06 | ゲージ増加 | BTノートと同じくaddgaugeで管理 | ゲージ管理 |
| BR-29-07 | 自動ERROR | 110ms超過で未判定ノートは自動ERROR | 全FXノート |

### 計算ロジック

FXショートノートのERROR判定窓: `dis < 250 - 100 * (effratetype = -1)`
- 通常ゲージ: ±250ms
- HARDゲージ(effratetype=-1): ±150ms

BTノートとの差異:
- BTショートノート: ERROR判定窓=260ms（HARDゲージ160ms）
- FXショートノート: ERROR判定窓=250ms（HARDゲージ150ms）

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

本機能ではデータベース操作は発生しない。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | ゲージ枯渇 | HARDゲージ使用時にgauge<=0 | endfl=1でゲーム終了フラグを設定 |

### リトライ仕様

リトライは行わない。

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

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

## パフォーマンス要件

BTノート判定と同一関数内で処理されるため、追加のパフォーマンス要件は発生しない。

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

特になし。

## 備考

- FXノートのショート判定とBTノートのショート判定はprocessButtonNoteJudgment内の同一ループで処理される。cntの値（0-3=BT, 4-5=FX）で分岐する。
- FXロングノートはlongstat/longj配列で管理され、BTロングノート（shlstat/shlj配列）とは別のデータ構造を使用する。
- FXノートのスコアはlscore変数に加算される（BTノートはnscore）。最終スコア計算時に合算される。

---

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

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

### 推奨読解順序

#### Step 1: FXショートノート判定

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | play_button_note.hsp | `src/scene/play/play_button_note.hsp` | FXショートノート判定部分 |

**主要処理フロー**:
1. **148行目**: FXショートノート判定開始（cnt>3, cnt<=5, note.2=0）
2. **155行目**: CRITICAL判定（dis<43）
3. **177行目**: NEAR判定（dis<113）
4. **216行目**: ERROR判定（dis<250）

#### Step 2: FXロングノート判定

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | play_button_note.hsp | `src/scene/play/play_button_note.hsp` | FXロングノート判定部分 |

**主要処理フロー**:
- **240-291行目**: FXロングノートの押下開始・継続・離し判定
- **249行目**: longstat設定
- **268-284行目**: longj区間判定とCRITICAL加算

#### Step 3: オートプレイ・自動ERROR

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | play_button_note.hsp | `src/scene/play/play_button_note.hsp` | FXチップの自動処理 |

**主要処理フロー**:
- **364-400行目**: FXチップノートのオートプレイ・自動ERROR処理

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

```
processButtonNoteJudgment (play_button_note.hsp)
    |
    +-- FXショート判定 (148-238行目)
    |     +-- CRITICAL: lscore+=2, addgauge (155-176行目)
    |     +-- NEAR: lscore+=1, addgauge, FAST/SLOW (177-215行目)
    |     +-- ERROR (216-229行目)
    |
    +-- FXロング判定 (240-291行目)
    |     +-- longstat/longcritical設定 (249-263行目)
    |     +-- longj区間判定 (268-284行目)
    |
    +-- FX自動ERROR (364-400行目)
          +-- chainnow=0, subgauge (396-399行目)
```

### データフロー図

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

FXキー入力 -----> processButtonNoteJudgment
                       |
arstat[4-5] ----> FXショート判定
                  +-- dis<43 ---------> CRITICAL
                  +-- dis<113 --------> NEAR
                  +-- dis<250 --------> ERROR
                       |
                  FXロング判定
                  +-- longj区間 ------> CRITICAL継続
                  +-- 離し -----------> ERROR
                       |
                  スコア・ゲージ更新 --> lscore, gauge, chainnow
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| play_button_note.hsp | `src/scene/play/play_button_note.hsp` | ソース | FXノート判定（148-400行目） |
| play_game_logic.hsp | `src/scene/play/play_game_logic.hsp` | ソース | 判定対象ノート特定（128-164行目） |
| play_utils.hsp | `src/scene/play/play_utils.hsp` | ソース | addgauge/subgauge関数 |
| play_audio_effects.hsp | `src/scene/play/play_audio_effects.hsp` | ソース | FXボタン連動のエフェクト適用 |
