# 機能設計書 4-結果画面

## 概要

K-Shoot MANIAのプレイ後に表示されるリザルト画面の機能設計書である。スコア・グレード・ゲージ・判定結果・クリアメダル等を表示し、スコアをファイルに保存する。

### 本機能の処理概要

結果画面は、プレイ画面で計算されたスコア・判定結果を視覚的に表示し、プレイヤー別にスコアデータをファイルに永続化する画面である。

**業務上の目的・背景**：プレイヤーの演奏結果をフィードバックし、成績記録の永続化とハイスコア更新の通知を行う。インターネットランキング(IR)へのスコア送信も本画面から行われる。

**機能の利用シーン**：プレイ画面で楽曲が終了した後に自動遷移する。Enter/Escキーで選曲画面に戻る。コースモード時は次の曲またはコース結果画面に遷移する。

**主要な処理内容**：
1. スコア（0-10,000,000点）とグレード（D/C/B/A/AA/AAA/S）の表示
2. ゲージパーセンテージとクリア/フルコンボ/パーフェクト判定の表示
3. CRITICAL/NEAR/ERROR個数・最大チェーン数の表示
4. ハイスコア更新時のNEW RECORD演出
5. プレイヤー別スコアファイル（.ksc）への保存
6. 楽曲アンロック演出（条件達成時）
7. IRポップアップによるスコア送信結果表示

**関連システム・外部連携**：BASS Audio Library（リザルトBGM再生）、IR（スコア送信）、ファイルシステム（スコア保存）

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

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 6 | リザルト画面 | 主画面 | スコア・グレード・判定結果・ゲージ・メダルを総合表示するリザルト画面の主処理 |
| 3 | 曲選択画面 | 遷移先 | Enter/Esc押下で曲選択画面(SCENE_SELECT)へ遷移 |
| 5 | ゲームプレイ画面 | 遷移元/遷移先 | コースモード途中曲の場合にSCENE_PLAYへ遷移 |
| 7 | コースリザルト画面 | 遷移先 | コースモード最終曲完了後にSCENE_COURSE_RESULTへ遷移 |

## 機能種別

結果表示・データ保存・シーン遷移制御

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| totalscore | int | Yes | 合計スコア | 0-10,000,000 |
| critical | int | Yes | CRITICAL判定数 | 0以上 |
| near | int | Yes | NEAR判定数 | 0以上 |
| errorn | int | Yes | ERROR判定数 | 0以上 |
| chainmax | int | Yes | 最大チェーン数 | 0以上 |
| gaugenow | double | Yes | 最終ゲージ値 | 0.0-100.0 |
| auto | int | No | オートプレイフラグ | 0 or 1 |
| iscourse | int | No | コースモードフラグ | 0 or 1 |

### 入力データソース

- プレイ画面からのグローバル変数（totalscore, critical, near, errorn等）
- score/{player}/ディレクトリの既存スコアファイル

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| scene | int | 遷移先シーンID |
| スコアファイル | file | .ksc形式のスコアデータ |

### 出力先

- 画面表示（スコア、グレード、メダル、判定詳細、NEW RECORD）
- score/{player}/ディレクトリ（スコアファイル保存）
- IRサーバー（スコア送信）

## 処理フロー

### 処理シーケンス

```
1. リザルト画面初期化（on_update_result）
   ├─ IRポップアップ初期化
   ├─ オートプレイ/調整モード判定
   │   └─ auto=1: コースモード次曲またはSCENE_SELECT直行
   ├─ 画像リソース読み込み（result.png, result_grade.png等）
   └─ 判定集計（critical/near/errorn/shortnum計算）
2. リザルト表示ループ
   ├─ スコア・グレード描画
   ├─ ゲージ・クリア判定描画
   ├─ 判定詳細（CRITICAL/NEAR/ERROR個数）描画
   ├─ NEW RECORD表示（ハイスコア更新時）
   ├─ IRポップアップ表示
   └─ 入力待ち（Enter/Esc）
3. スコア保存
   └─ プレイヤー別.kscファイルへの書き込み
4. シーン遷移
   ├─ 通常: SCENE_SELECT
   ├─ コース途中: SCENE_PLAY
   └─ コース最終: SCENE_COURSE_RESULT
```

### フローチャート

```mermaid
flowchart TD
    A[リザルト画面開始] --> B{auto/adjmode?}
    B -->|Yes| C{コースモード?}
    C -->|Yes, 途中| D[次の曲 SCENE_PLAY]
    C -->|Yes, 最終| E[SCENE_COURSE_RESULT]
    C -->|No| F[SCENE_SELECT]
    B -->|No| G[画像リソース読み込み]
    G --> H[判定集計]
    H --> I[リザルト表示ループ]
    I --> J{Enter/Esc?}
    J -->|No| I
    J -->|Yes| K[スコア保存]
    K --> F
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-01 | グレード判定 | S:10M, AAA:9.8M以上, AA:9.5M以上, A:9M以上, B:8.7M以上, C:7M以上, D:7M未満 | スコア確定時 |
| BR-02 | オートプレイ時スキップ | auto=1の場合はリザルト表示をスキップ | auto=1 |
| BR-03 | コースモード継続 | コースモード途中曲はスコアを累積して次曲へ | iscourse=1 かつ coursenow < courselistnum |
| BR-04 | NEW RECORD判定 | 既存ハイスコアより高い場合にNEW RECORDフラグ表示 | diff > 0 |

### 計算ロジック

- コーススコア累積: `coursetotalscore += totalscore`, `coursecritical += critical` 等（result.hsp 9-12行目）
- 判定集計はnoteresult配列をループして集計（result.hsp 94-100行目）

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

### 操作別データベース影響一覧

| 操作 | 対象ファイル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| スコア保存 | score/{player}/*.ksc | INSERT/UPDATE相当 | スコア・メダル・判定情報を保存 |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | スコア保存失敗 | ディスク容量不足等 | エラー処理なし（HSPの標準動作に依存） |

### リトライ仕様

リトライ処理は実装されていない。

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

トランザクション処理は適用されない（ファイル保存は上書き方式）。

## パフォーマンス要件

特に厳密な要件なし（結果表示のみ）。

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

- IRスコア送信時のセッション認証（session_id使用）

## 備考

- オートプレイ時・調整モード時はリザルト表示をスキップする設計

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | kshootmania.hsp | `kshootmania.hsp` | IMG_RESULT_* 定数定義（画像バッファ番号） |

- **92-93行目**: IMG_RESULT_DIFFICULTY=57, IMG_RESULT_TWEETBTN=166
- **107行目**: BUF_RESULT_TEMP=184

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | result.hsp | `src/scene/result.hsp` | on_update_resultサブルーチン |

**主要処理フロー**:
1. **1行目**: `#deffunc on_update_result`
2. **4行目**: `ir_popup_init` - IRポップアップ初期化
3. **6-24行目**: auto/adjmode時のスキップ処理（コースモード累積含む）
4. **64-76行目**: 200ms待機後のリザルト表示開始
5. **78-100行目**: 判定集計処理（noteresult配列ループ）

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

```
kshootmania.hsp (メインループ: 1079行目 case SCENE_RESULT)
    │
    └─ on_update_result (src/scene/result.hsp: 1行目)
           ├─ ir_popup_init (src/ir.hsp)
           ├─ 判定集計処理（noteresult配列ループ）
           ├─ スコア保存処理（.kscファイル書き込み）
           ├─ ir_send_score (src/ir.hsp) [IR送信]
           └─ ir_popup_set_text (src/ir.hsp) [ポップアップ表示]
```

### データフロー図

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

noteresult配列 ─────────────▶ 判定集計 ────────────────────▶ critical/near/errorn
totalscore ──────────────────▶ グレード判定 ────────────────▶ グレード画像表示
gaugenow ────────────────────▶ クリア判定 ─────────────────▶ メダル・クリア表示
既存スコア ──────────────────▶ ハイスコア比較 ─────────────▶ NEW RECORD表示
全結果データ ────────────────▶ スコア保存 ─────────────────▶ .kscファイル
全結果データ ────────────────▶ ir_send_score ─────────────▶ IRサーバー
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| result.hsp | `src/scene/result.hsp` | ソース | リザルト画面の全処理 |
| kshootmania.hsp | `kshootmania.hsp` | ソース | メインループ・定数定義 |
| ir.hsp | `src/ir.hsp` | ソース | IR連携（スコア送信・ポップアップ） |
| result.png | `imgs/result.png` | 画像 | リザルト画面背景 |
| result_grade.png | `imgs/result_grade.png` | 画像 | グレード表示画像 |
| result_newrecord.png | `imgs/result_newrecord.png` | 画像 | NEW RECORD表示画像 |
| result_scorenum.png | `imgs/result_scorenum.png` | 画像 | スコア数値画像 |
| result_bgm.ogg | `se/result_bgm.ogg` | 音声 | リザルトBGM |
