# 機能設計書 67-判定エフェクト表示

## 概要

本ドキュメントは、K-Shoot MANIA のプレイ画面における判定エフェクト（CRITICAL/NEAR/ERROR）およびチェーンエフェクトの表示機能の設計を記述する。ノートの判定結果に応じた視覚的フィードバックをリアルタイムに描画する。

### 本機能の処理概要

**業務上の目的・背景**：リズムゲームでは、プレイヤーの入力に対する即時的な視覚フィードバックが不可欠である。判定エフェクトにより、プレイヤーは自身のタイミング精度（CRITICAL/NEAR/ERROR）を直感的に把握でき、プレイの質を向上させることができる。

**機能の利用シーン**：ゲームプレイ画面（SCENE_PLAY）の毎フレーム描画処理として実行される。ノート判定が発生するたびに対応するエフェクトが表示され、一定時間後にフェードアウトする。

**主要な処理内容**：
1. BTノート（4レーン）のチップ判定エフェクト表示（judge 配列に基づく）
2. FXノート（2レーン）のチップ判定エフェクト表示
3. BTロングノートの押下/離し判定エフェクト表示（shljudge 配列）
4. FXロングノートの押下/離し判定エフェクト表示（ljudge 配列）
5. レーザーカーソルの表示（アナログ入力追従）
6. レーザー方向転換エフェクトの表示
7. COMBO数表示（chainvt / chainnow）
8. チェーンマイルストーンエフェクト表示（chainefft）
9. アナログデバイス予告表示（anapret）

**関連システム・外部連携**：HGIMG4 による2D/3Dハイブリッド描画。テクスチャはキャッシュから読み込み。

**権限による制御**：ノートモード（shortmode/longmode/analogmode）が AUTO の場合、CRITICAL 判定のエフェクトのみ表示される。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 5 | ゲームプレイ画面 | 主画面 | play_draw_frame.hsp による CRITICAL/NEAR/ERROR の判定結果・チェーンエフェクト表示 |

## 機能種別

描画処理 / アニメーション表示

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| judge | int配列 | Yes | 判定結果配列 [6レーン][タイミング, 種別] | 種別: 0=なし, 1=ERROR, 2=NEAR, 3=CRITICAL, 4=NEAR(FAST) |
| judgel | int配列 | Yes | 判定ライン上エフェクト配列 [6レーン][リングバッファ][タイミング, 種別] | - |
| shljudge | int配列 | Yes | BTロングノート判定配列 [4] | 0=離し, 1=押下中 |
| ljudge | int配列 | Yes | FXロングノート判定配列 [2] | 0=離し, 1=押下中 |
| chainnow | int | Yes | 現在のチェーン数 | 0以上 |
| chainvt | int | Yes | COMBO表示開始タイミング | -1=非表示 |
| chainefft | int | Yes | チェーンマイルストーンエフェクトのタイミング | -1=非表示 |
| t | int | Yes | 現在のプレイ時間（ms） | - |

### 入力データソース

play_game_logic.hsp / play_button_note.hsp / play_laser_note.hsp で更新される判定結果配列。

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| 判定エフェクト画像 | ビットマップ | バッファ155（判定ライン用バッファ）への描画 |
| COMBO数表示 | テクスチャ | 画面上のCOMBO数値表示 |
| チェーンエフェクト | テクスチャ | チェーンマイルストーン到達時のエフェクト |

### 出力先

バッファ155（判定エフェクト専用バッファ）およびHGIMG4テクスチャへの描画。3Dオブジェクト（obj_judgel）経由で画面表示。

## 処理フロー

### 処理シーケンス

```
1. 判定エフェクト専用バッファのクリア (gsel 155, boxf)
2. チップノートの判定アニメーション (repeat 6)
   2-1. 判定種別で分岐: CRITICAL→gcopy 16, NEAR→gcopy 17, NEAR(FAST)→gcopy 17(別座標), ERROR→gcopy 18
   2-2. アニメーション: 12フレーム × (t-判定時刻)/500 で進行
   2-3. 500ms でフェードアウト後、judgel.cnt.1=0 にリセット
3. BTロングノートの判定アニメーション (repeat 4)
   3-1. 押下中(shljudge=1): 開始アニメーション → ループアニメーション
   3-2. 離し時: 終了アニメーション (500ms)
4. FXロングノートの判定アニメーション (repeat 2)
   4-1. 押下中(ljudge=1): 開始アニメーション → ループアニメーション
   4-2. 離し時: 終了アニメーション (500ms)
5. レーザーカーソル表示 (repeat 2)
   5-1. アナログ位置に基づくカーソル座標計算
   5-2. 追従精度に応じたカーソルの透過度変更
   5-3. 1200ms 周期のアニメーション
6. レーザー方向転換エフェクト (repeat 2)
   6-1. 方向転換検出時にエフェクト配列に追加
   6-2. 90ms→170ms の2段階アニメーション
7. COMBO数表示
   7-1. chainnow を4桁で表示（先頭0埋め）
   7-2. noerror フラグでフォント色切替
   7-3. 500ms でフェードアウト
8. チェーンマイルストーンエフェクト
   8-1. 300ms のフェードイン→持続→フェードアウト
   8-2. 4段階のアニメーション切替
9. レーザー予告表示
   9-1. レーザー開始1400ms以上前から予告表示
   9-2. 300ms フェードイン → 2000ms 表示 → 300ms フェードアウト
```

### フローチャート

```mermaid
flowchart TD
    A[drawFrame] --> B[バッファ155クリア]
    B --> C[チップノート判定アニメ 6レーン]
    C --> D[BTロング判定アニメ 4レーン]
    D --> E[FXロング判定アニメ 2レーン]
    E --> F[レーザーカーソル表示 2レーン]
    F --> G[レーザー方向転換エフェクト]
    G --> H[テクスチャ変換 settex]
    H --> I[3Dオブジェクト更新]
    I --> J[COMBO数表示 hgzoom]
    J --> K[チェーンエフェクト hgzoom]
    K --> L[レーザー予告表示 hgcopy]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-67-1 | AUTO時の表示制限 | AUTOモード時は CRITICAL 判定（judge.cnt.1=3）のエフェクトのみ表示 | shortmode/longmode=mode_auto |
| BR-67-2 | 判定エフェクト持続時間 | チップ判定エフェクトは最大155ms表示（75msでフェードイン完了、残り80msでフェードアウト） | チップノート判定時 |
| BR-67-3 | ロング開始アニメーション | ロングノート押下開始から500msで開始アニメーション、以降はループアニメーション | ロングノート押下開始時 |
| BR-67-4 | ロングループ周期 | ロングノートのループアニメーションは1625ms周期で26フレーム | ロングノート押下中 |
| BR-67-5 | COMBO表示条件 | chainnow が 0000 の場合は非表示 | 常時 |
| BR-67-6 | レーザー予告条件 | レーザー開始まで1400ms以上ある場合に予告表示 | レーザー登場前 |

### 計算ロジック

**チップ判定エフェクトのフェードイン/アウト**:
- 0-75ms: フェードイン `alpha = 220`、幅 `0→40/ra`
- 75-155ms: フェードアウト `alpha = 220 + (judge.cnt.0 - t + 75) * 220 / 80`

**レーザーカーソル位置計算**:
```
stat1 = (canalognow.cnt * anarannow(cnt) - 500 * (anarannow(cnt)=2)) * scrsize_h * 59 / 200 / 480
```

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

該当なし。

## エラー処理

### エラーケース一覧

該当なし。描画処理のみで例外は発生しない。

### リトライ仕様

該当なし。

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

該当なし。

## パフォーマンス要件

毎フレーム実行される描画処理。judgel 配列はリングバッファ（judgelmax）で管理され、判定エフェクトの最大同時表示数が制限されている。

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

該当なし。

## 備考

- judgel 配列はリングバッファ構造（judgelnext でインデックス管理）により、古いエフェクトが自動的に上書きされる
- Center Split 対応: center_split_now に応じてエフェクト表示位置が左右にずれる
- noerror フラグ: 1=全てCRITICAL/NEAR（エラーなし）の場合にCOMBO表示色が変化
- 判定種別の番号: 1=ERROR, 2=NEAR, 3=CRITICAL, 4=NEAR(FAST)

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | play_draw_frame.hsp | `src/scene/play/play_draw_frame.hsp` | judge[6][2]: レーン別判定結果（タイミング、種別） |
| 1-2 | play_draw_frame.hsp | `src/scene/play/play_draw_frame.hsp` | judgel[6][judgelmax][2]: リングバッファ構造の判定エフェクト配列 |
| 1-3 | play_draw_frame.hsp | `src/scene/play/play_draw_frame.hsp` | shljudge[4], ljudge[2]: ロングノート押下状態 |

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | play_draw_frame.hsp | `src/scene/play/play_draw_frame.hsp` | drawFrame 関数の **487-626行目** が判定エフェクト処理部分 |

**主要処理フロー**:
1. **497-500行目**: バッファ155の選択とクリア
2. **501-529行目**: チップノート判定アニメーション（6レーン）
3. **530-549行目**: BTロングノート判定アニメーション（4レーン）
4. **550-569行目**: FXロングノート判定アニメーション（2レーン）
5. **576-593行目**: レーザーカーソル表示
6. **595-623行目**: レーザー方向転換エフェクト
7. **860-890行目**: COMBO数表示
8. **880-890行目**: チェーンマイルストーンエフェクト
9. **893-917行目**: レーザー予告表示

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

```
drawFrame
    |
    +-- [バッファ155] 判定エフェクト描画
    |       +-- gcopy 16 (CRITICAL スプライト)
    |       +-- gcopy 17 (NEAR スプライト)
    |       +-- gcopy 18 (ERROR スプライト)
    |       +-- gcopy 45 (BT ロングエフェクト)
    |       +-- gcopy 30 (FX ロングエフェクト)
    |       +-- gcopy 50 (レーザーカーソル)
    |       +-- gcopy 41 (方向転換エフェクト)
    |
    +-- settex (バッファ→テクスチャ変換)
    +-- hgzoom (COMBO数表示)
    +-- hgcopy (チェーン/予告エフェクト)
```

### データフロー図

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

judge 配列           ───>   ┌──────────────────────┐
judgel 配列           ───>   |  チップ判定アニメ     |       バッファ155
shljudge / ljudge    ───>   |  ロング判定アニメ     |  ──>  (判定エフェクト)
analogpos            ───>   |  レーザーカーソル     |
chainnow             ───>   |  COMBO数表示          |  ──>  画面直接描画
chainefft            ───>   |  チェーンエフェクト   |       (hgzoom/hgcopy)
                             └──────────────────────┘
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| play_draw_frame.hsp | `src/scene/play/play_draw_frame.hsp` | ソース | 判定エフェクト描画（487-917行目） |
| play_button_note.hsp | `src/scene/play/play_button_note.hsp` | ソース | judge/shljudge/ljudge の更新 |
| play_laser_note.hsp | `src/scene/play/play_laser_note.hsp` | ソース | analogpos/analognow の更新 |
| play_game_logic.hsp | `src/scene/play/play_game_logic.hsp` | ソース | chainnow/chainefft の更新 |
| play_graphics.hsp | `src/scene/play/play_graphics.hsp` | ソース | 判定エフェクトのテクスチャロード |
