# 機能設計書 75-スコア・グレード表示

## 概要

結果画面において合計スコア(0〜10,000,000点)とグレード(D/C/B/A/AA/AAA/S)を表示する機能の設計書である。

### 本機能の処理概要

プレイ終了後の結果画面で、プレイヤーのスコアとそれに対応するグレードをImage画像として描画・表示する。スコアは8桁のゼロパディングで表示され、グレードはスコアの閾値に基づいて7段階で判定される。

**業務上の目的・背景**：プレイ結果をプレイヤーに分かりやすく伝えるため、スコアとグレードを視覚的に表示する機能が必要である。グレードはスコアの達成度を直感的に理解できる指標として機能する。

**機能の利用シーン**：プレイ画面からの遷移後、結果画面(SCENE_RESULT)で表示される。通常プレイ・コースモードの両方で使用される。オートプレイ(auto=1)やアジャストモード(adjmode=1)の場合は結果画面自体がスキップされる。

**主要な処理内容**：
1. totalscore2(ゲージボーナス込みスコア)を基にグレードを判定する
2. スコアを8桁ゼロパディング文字列に変換する
3. 画像バッファ(Image34)のスコア数字画像を使って各桁を描画する
4. グレード画像(Image33)から該当グレードの画像を選択して描画する
5. 途中終了(tochu=1)の場合はグレードを強制的にD(最低)に設定する

**関連システム・外部連携**：artlet2d(alXxx系関数)による画像描画、BASS Audio Libraryによる結果BGM再生。

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

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 6 | リザルト画面 | 主画面 | 合計スコアとD/C/B/A/AA/AAAグレードをImage画像で表示 |
| 7 | コースリザルト画面 | 主画面 | 合計スコアとグレードの表示 |

## 機能種別

計算処理・画面表示処理

## 入力仕様

### 入力パラメータ

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

### 入力データソース

プレイ画面(play_game_logic.hsp)で計算されたスコア・ゲージ情報。

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| stat1_ | int | グレードインデックス(0:D, 1:C, 2:B, 3:A, 4:AA, 5:AAA) |
| スコア表示 | 画面 | 8桁のスコア数値画像 |
| グレード表示 | 画面 | グレード画像(Image33から選択) |

### 出力先

結果画面(Image32 = 結果画面の作業バッファ)に描画される。

## 処理フロー

### 処理シーケンス

```
1. totalscore2の計算
   ├─ 通常ゲージ: totalscore2 = totalscore * 9/10 + (gauge*100/gaugemax) * 10000
   └─ HARDゲージ: totalscore2 = totalscore * 9/10 + (ngauge*100/gaugemax) * 10000

2. グレード判定(stat1_)
   ├─ totalscore2 >= 9,800,000 → 5 (AAA)
   ├─ totalscore2 >= 9,400,000 → 4 (AA)
   ├─ totalscore2 >= 8,900,000 → 3 (A)
   ├─ totalscore2 >= 8,000,000 → 2 (B)
   ├─ totalscore2 >= 7,000,000 → 1 (C)
   └─ totalscore2 < 7,000,000  → 0 (D)
   ※ tochu=1(途中終了)の場合は強制的に0(D)

3. スコア表示
   ├─ totalscoreを8桁ゼロパディング文字列に変換
   └─ Image34(スコア数字画像)から各桁を描画

4. グレード表示
   └─ Image33(グレード画像)からstat1_に対応するグレードを描画
```

### フローチャート

```mermaid
flowchart TD
    A[プレイ終了] --> B{通常ゲージ OR HARDゲージ?}
    B -->|通常| C[totalscore2 = totalscore*9/10 + ゲージボーナス]
    B -->|HARD| D[totalscore2 = totalscore*9/10 + ngaugeボーナス]
    C --> E[グレード判定]
    D --> E
    E --> F{tochu==1?}
    F -->|Yes| G[stat1_ = 0 D強制]
    F -->|No| H[stat1_ = 閾値判定]
    G --> I[スコア8桁表示]
    H --> I
    I --> J[グレード画像表示]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-75-01 | グレード閾値 | D(<700万)/C(>=700万)/B(>=800万)/A(>=890万)/AA(>=940万)/AAA(>=980万) | グレード判定時 |
| BR-75-02 | 途中終了ペナルティ | tochu=1の場合はグレードを強制的にDに設定 | 途中終了時 |
| BR-75-03 | ゲージボーナス | スコアの90%+ゲージの貢献(最大100万点)でtotalscore2を算出 | グレード計算時 |
| BR-75-04 | HARDゲージ補正 | HARDゲージ時はngauge(通常ゲージ相当値)でボーナスを計算 | HARDゲージ時 |

### 計算ロジック

- totalscore2(通常): `totalscore * 9 / 10 + (gauge * 100 / gaugemax) * 10000`
- totalscore2(HARD): `totalscore * 9 / 10 + (ngauge * 100 / gaugemax) * 10000`
- グレード判定: `stat1_ = (totalscore2>=7000000) + (totalscore2>=8000000) + (totalscore2>=8900000) + (totalscore2>=9400000) + (totalscore2>=9800000)`

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

該当なし。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | - | 特になし | - |

### リトライ仕様

リトライ処理は不要。

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

該当なし。

## パフォーマンス要件

特になし。

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

特になし。

## 備考

- グレードSはtotalscore=10,000,000(PERFECT)の場合に該当するが、設計書上のグレード判定ロジックではAAAまでの判定のみ行っている。Sグレードの判別はクリア判定(stat6)側で扱われる
- 結果画面の画像リソースは`imgs/result.png`、`imgs/result_grade.png`等から読み込まれる

---

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

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

### 推奨読解順序

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

スコア・グレード表示に使用される変数と画像リソースを理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | result.hsp | `src/scene/result.hsp` | totalscore, totalscore2, gauge, gaugemax, effratetype等の変数を確認する |

**読解のコツ**: HSP3のalStretchImageToImage関数は、画像バッファ間でリサイズコピーを行う。Image番号はバッファIDとして使用される。

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

結果画面の更新処理を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | result.hsp | `src/scene/result.hsp` | on_update_result関数内のグレード判定(212-219行目)を理解する |

**主要処理フロー**:
1. **212-216行目**: totalscore2の計算(通常/HARDゲージで分岐)
2. **217行目**: `stat1_=(totalscore2>=7000000)+...+(totalscore2>=9800000)` - グレード判定(比較結果の加算で閾値判定)
3. **218行目**: `if(tochu=1):stat1_=0` - 途中終了時のグレード強制D
4. **219行目**: `alCopyImageToImage 33,32,...` - Image33からグレード画像を描画
5. **237-247行目**: スコアの8桁ゼロパディング表示(Image34のスコア数字画像使用)

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

```
on_update_result (結果画面更新)
    │
    ├─ totalscore2計算 (212-216行目)
    ├─ グレード判定 (217行目)
    ├─ 途中終了チェック (218行目)
    ├─ グレード画像描画 (219行目)
    │      └─ alCopyImageToImage (Image33 → Image32)
    └─ スコア8桁表示 (237-247行目)
           └─ alCopyImageToImage (Image34 → Image32)
```

### データフロー図

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

totalscore           ──▶ totalscore2計算           ──▶ totalscore2
gauge/ngauge              (90%+ゲージボーナス)

totalscore2          ──▶ グレード判定              ──▶ stat1_ (0-5)
                          (閾値比較加算)

stat1_               ──▶ Image33選択描画           ──▶ グレード画像表示
totalscore           ──▶ Image34選択描画           ──▶ スコア数値表示
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| result.hsp | `src/scene/result.hsp` | ソース | 結果画面の主要処理(スコア・グレード描画) |
| kshootmania.hsp | `kshootmania.hsp` | ソース | 定数・変数の定義 |
| result.png | `imgs/result.png` | リソース | 結果画面の背景・枠画像 |
| result_grade.png | `imgs/result_grade.png` | リソース | グレード画像(D/C/B/A/AA/AAA) |
