# 機能設計書 76-クリア判定表示

## 概要

結果画面においてゲージパーセンテージ・クリア/フルコンボ/パーフェクト判定・メダルを表示する機能の設計書である。

### 本機能の処理概要

プレイ終了後の結果画面で、ゲージの達成パーセンテージとクリア結果(FAILED/CLEARED/FULL COMBO/PERFECT)を判定・表示する。さらにメダル情報としてstat6変数に結果を格納し、IR(インターネットランキング)送信やスコア保存に使用する。

**業務上の目的・背景**：プレイヤーにクリア状態を明確に伝えるため、ゲージのパーセンテージ表示とクリア判定結果を可視化する。EASY/通常/HARDの各ゲージタイプに応じたクリア判定基準の適用が必要である。

**機能の利用シーン**：結果画面(SCENE_RESULT)でスコア・グレード表示と同時に表示される。ゲージタイプ(effratetype)に応じてクリア条件が異なり、通常ゲージは70%以上、HARDゲージは30%超でクリアとなる。

**主要な処理内容**：
1. ゲージパーセンテージの計算と表示(通常: gauge*100/gaugemax、HARD: gauge/1000)
2. クリア判定(stat6): 0=FAILED, 1=CLEARED, 2=FULL COMBO, 3=PERFECT
3. ゲージタイプ別のクリア条件判定(通常70%以上、HARD30%超)
4. メダル文字列の生成(IR送信用: failed/cleared/hard_cleared/fullcombo/perfect等)
5. ゲージ描画(Image23: ゲージ本体、Image10: 数値フォント)
6. コースモード時のメダル保存(course_md配列)

**関連システム・外部連携**：IR(インターネットランキング)へのスコア送信時にメダル情報が付与される。

**権限による制御**：特になし。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 6 | リザルト画面 | 主画面 | ゲージパーセンテージ・クリア/フルコンボ/パーフェクト判定・メダルの表示 |
| 7 | コースリザルト画面 | 主画面 | ゲージパーセンテージ・クリア判定・メダルの表示 |

## 機能種別

計算処理・画面表示処理

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| gauge | int | Yes | ゲージ値 | 整数値 |
| gaugemax | int | Yes | ゲージ最大値 | 正の整数 |
| effratetype | int | Yes | ゲージタイプ(-1:EASY, 0:通常, 1:HARD) | -1,0,1 |
| iscourse | int | Yes | コースモードフラグ | 0または1 |
| tochu | int | Yes | 途中終了フラグ | 0または1 |
| errorn | int | Yes | ERROR判定回数 | 0以上 |
| totalscore | int | Yes | 合計スコア | 0〜10,000,000 |

### 入力データソース

プレイ画面で計算されたゲージ・判定結果データ。

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| stat6 | int | クリア判定結果(0:FAILED, 1:CLEARED, 2:FULL COMBO, 3:PERFECT) |
| medal | string | IR送信用メダル文字列(failed/cleared/hard_cleared/fullcombo/perfect等) |
| gpercent | int | ゲージパーセンテージ(スコア保存用) |

### 出力先

結果画面(Image32)への描画およびスコアファイル(.ksc)への保存データ。

## 処理フロー

### 処理シーケンス

```
1. ゲージパーセンテージ計算
   ├─ 通常/EASYゲージ: stat2 = 100 * gauge / gaugemax
   └─ HARDゲージ: stat2 = gauge / 1000 (gauge < 0 の場合は 0)

2. クリア判定(stat6)
   ├─ 通常/EASYゲージ:
   │   ├─ gauge*100/gaugemax >= 70 → stat6 = 1 (CLEARED)
   │   ├─ errorn = 0 → stat6 = 2 (FULL COMBO)
   │   └─ totalscore = 10,000,000 → stat6 = 3 (PERFECT)
   └─ HARDゲージ:
       ├─ gauge/1000 > 0 → stat6 = 1 (CLEARED)
       ├─ errorn = 0 → stat6 = 2 (FULL COMBO)
       └─ totalscore = 10,000,000 → stat6 = 3 (PERFECT)

3. 途中終了チェック
   └─ tochu = 1 → stat6 = 0 (FAILED)

4. メダル文字列生成
   ├─ stat6=0: "failed"
   ├─ stat6=1: effratetype別("easy_cleared"/"cleared"/"hard_cleared")
   ├─ stat6=2: effratetype別("easy_fullcombo"/"fullcombo")
   └─ stat6=3: effratetype別("easy_perfect"/"perfect")

5. ゲージパーセンテージ描画
   └─ Image10の数値フォントで3桁表示
```

### フローチャート

```mermaid
flowchart TD
    A[クリア判定開始] --> B{通常/EASY OR HARD?}
    B -->|通常/EASY| C{gauge*100/gaugemax >= 70?}
    B -->|HARD| D{gauge/1000 > 0?}
    C -->|No| E[stat6 = 0 FAILED]
    C -->|Yes| F[stat6 = 1 CLEARED]
    D -->|No| E
    D -->|Yes| F
    F --> G{errorn == 0?}
    G -->|Yes| H[stat6 = 2 FULL COMBO]
    G -->|No| I{途中終了?}
    H --> J{totalscore == 10000000?}
    J -->|Yes| K[stat6 = 3 PERFECT]
    J -->|No| I
    K --> I
    I -->|tochu=1| E
    I -->|tochu=0| L[メダル文字列生成]
    E --> L
    L --> M[ゲージパーセンテージ描画]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-76-01 | 通常クリア条件 | ゲージが70%以上でクリア判定 | effratetype <= 0 かつ iscourse = 0 |
| BR-76-02 | HARDクリア条件 | ゲージが30%超でクリア判定 | effratetype > 0 または iscourse = 1 |
| BR-76-03 | フルコンボ条件 | ERROR判定が0回 | クリア後の追加判定 |
| BR-76-04 | パーフェクト条件 | スコアが10,000,000点(満点) | フルコンボ後の追加判定 |
| BR-76-05 | 途中終了 | tochu=1の場合は強制FAILED | 常時 |
| BR-76-06 | コースモードメダル | コースモード時はmedal="course_play"に固定 | iscourse = 1 |
| BR-76-07 | EASY接頭辞 | EASYゲージの場合メダル名に"easy_"接頭辞が付く | effratetype = -1 |

### 計算ロジック

- 通常ゲージパーセンテージ: `100 * gauge / gaugemax`
- HARDゲージパーセンテージ: `gauge / 1000` (gauge < 0 なら 0)

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

該当なし。

## エラー処理

特になし。

### リトライ仕様

リトライ処理は不要。

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

該当なし。

## パフォーマンス要件

特になし。

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

特になし。

## 備考

- stat6の値はスコア保存時に.kscファイルの第2フィールドとして保存される
- EASYゲージの場合、クリア条件は通常と同じ(70%以上)だが、メダル名に"easy_"接頭辞が付く
- コースモード時は各曲ごとのメダルがcourse_md配列に保存され、コースリザルト画面で参照される

---

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

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

### 推奨読解順序

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

クリア判定で使用される変数を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | kshootmania.hsp | `kshootmania.hsp` | effratetype, mode_on/mode_off等の定義を確認する |

#### Step 2: クリア判定ロジックを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | result.hsp | `src/scene/result.hsp` | 277-302行目のクリア判定ロジック(stat6計算)を理解する |

**主要処理フロー**:
1. **279-282行目**: 通常/EASYゲージのクリア判定(70%条件)
2. **283-288行目**: フルコンボ/パーフェクト判定(errorn=0, totalscore=10000000)
3. **289-298行目**: HARDゲージのクリア判定(30%超条件)
4. **300-302行目**: 途中終了チェック(tochu=1で強制FAILED)

#### Step 3: メダル文字列生成を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | result.hsp | `src/scene/result.hsp` | 309-339行目のswitch文によるメダル文字列生成を理解する |

**主要処理フロー**:
- **309-336行目**: stat6の値とeffratetypeに基づくメダル文字列の分岐
- **337-339行目**: コースモード時の"course_play"固定

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

```
on_update_result (結果画面更新)
    │
    ├─ ゲージパーセンテージ計算 (222-230行目)
    ├─ クリア判定(stat6) (277-302行目)
    ├─ メダル文字列生成 (309-339行目)
    ├─ ゲージパーセンテージ描画 (231-236行目)
    │      └─ alStretchImageToImage (Image10 → Image32)
    └─ コースモード保存 (303-307行目)
           └─ course_md配列への格納
```

### データフロー図

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

gauge/gaugemax       ──▶ ゲージ%計算              ──▶ stat2 (パーセンテージ)
effratetype               (通常/HARD分岐)

gauge/errorn         ──▶ クリア判定               ──▶ stat6 (0-3)
totalscore/tochu          (閾値チェック)

stat6/effratetype    ──▶ メダル文字列生成          ──▶ medal (IR送信用)
                          (switch分岐)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| result.hsp | `src/scene/result.hsp` | ソース | クリア判定・メダル生成・ゲージ描画の主要処理 |
| kshootmania.hsp | `kshootmania.hsp` | ソース | effratetype等の定義 |
| ir.hsp | `src/ir.hsp` | ソース | IR送信時のメダル情報使用 |
