# 画面設計書 6-リザルト画面

## 概要

本ドキュメントは、K-Shoot MANIA のリザルト画面の設計仕様を記述する。単曲プレイ後の成績表示画面であり、スコア、グレード、判定内訳、新記録、メダルを表示する。

### 本画面の処理概要

リザルト画面はゲームプレイ完了後に表示される成績発表画面であり、プレイ結果の可視化とスコア保存を行う。

**業務上の目的・背景**：プレイ結果をプレイヤーに明確にフィードバックし、達成感や改善ポイントを提供する。また、ハイスコア更新の通知、IRへのスコア送信、スコアファイルへの保存を行い、プレイ記録を管理する。

**画面へのアクセス方法**：ゲームプレイ画面でゲーム完了（楽曲終了またはESC中断）後に自動遷移する。

**主要な操作・処理内容**：
1. スコア表示（0-10,000,000点）とグレード表示（D/C/B/A/AA/AAA）
2. クリア判定・メダル表示（クリア/フルコンボ/パーフェクト）
3. 判定詳細表示（CRITICAL/NEAR/ERROR個数、最大チェーン数）
4. NEW RECORD表示（ハイスコア更新時）
5. スコア保存（プレイヤー別スコアファイル.kscへの書き込み）
6. 楽曲アンロック演出（条件達成時）
7. IRスコア送信（オンラインモード時）
8. IRポップアップUI表示
9. ツイートボタン（F11キーまたはマウスクリック）

**画面遷移**：
- 遷移先：曲選択画面（SCENE_SELECT、通常終了、行668）、コースリザルト画面（SCENE_COURSE_RESULT、コースモード完了、行658）、ゲームプレイ画面（SCENE_PLAY、コースモード次曲、行660）
- 遷移元：ゲームプレイ画面（SCENE_PLAY、ゲーム完了）

**権限による表示制御**：auto=1またはadjmode=1の場合、リザルト詳細を表示せず即座に次の画面へ遷移する（行6-24）。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 4 | 結果画面 | 主機能 | スコア・グレード・判定結果・ゲージ・メダルを総合表示するリザルト画面の主処理 |
| 75 | スコア・グレード表示 | 主機能 | 合計スコアとD/C/B/A/AA/AAAグレードをImage画像で表示 |
| 76 | クリア判定表示 | 主機能 | ゲージパーセンテージ・クリア/フルコンボ/パーフェクト判定・メダルの表示 |
| 77 | 判定詳細表示 | 主機能 | CRITICAL/NEAR/ERROR個数・最大チェーン数の数値表示 |
| 78 | NEW RECORD表示 | 主機能 | ハイスコア更新時(diff>0)のNEW RECORDフラグ・差分スコア表示 |
| 79 | スコア保存 | 主機能 | プレイヤー別スコアファイル(.ksc)へのスコア・メダル・判定情報の保存 |
| 80 | 楽曲アンロック演出 | 補助機能 | completedlist変数に基づく条件達成楽曲のアンロック通知表示 |
| 96 | IRポップアップUI | 補助機能 | ir_popup_init/ir_popup_set_textによるIRスコア送信結果のポップアップ表示 |
| 58 | キーボード入力 | 補助機能 | Enter/Escキーによるリザルト画面からの遷移操作 |
| 59 | ジョイスティック入力 | 補助機能 | getjoykeystatによるジョイスティック入力 |
| 42 | 音量制御 | 補助機能 | リザルトBGMのマスターボリューム適用 |
| 99 | プレイヤー別スコア管理 | 主機能 | score/プレイヤー名/ディレクトリへのスコアデータ保存・読み込み |
| 101 | 多言語テキスト管理 | 補助機能 | lang変数によるリザルト画面UIラベルの多言語表示 |
| 130 | BASS Audio Library | 補助機能 | リザルトBGMの再生制御 |
| 7 | シーン遷移管理 | 遷移先機能 | Enter/Esc押下による各シーンへの遷移 |
| 95 | IRハッシュ計算 | API連携 | ir_send_scoreによるIRサーバーへのスコア送信 |

## 画面種別

詳細表示画面（成績結果表示）

## URL/ルーティング

デスクトップアプリケーション（HSP3）のため、URLルーティングは存在しない。シーン管理はscene変数（SCENE_RESULT = 5）により制御される。

## 入出力項目

| 項目名 | 入出力 | データ型 | 説明 |
|--------|--------|----------|------|
| totalscore | 入力 | int | プレイ結果の合計スコア（0-10,000,000） |
| critical | 入力/出力 | int | CRITICAL判定数（リザルト画面で再計算） |
| near | 入力/出力 | int | NEAR判定数（リザルト画面で再計算） |
| errorn | 入力/出力 | int | ERROR判定数（リザルト画面で再計算） |
| chainmax | 入力 | int | 最大チェーン数 |
| gauge | 入力 | int | 最終ゲージ値 |
| iscourse | 入力 | int | コースモードフラグ |
| coursenow | 入力/出力 | int | 現在のコース内曲番号 |
| courselistnum | 入力 | int | コース内の総曲数 |
| courseend | 入力 | int | コース終了フラグ |
| diff | 内部状態 | int | ハイスコアとの差分（正の場合NEW RECORD） |
| resultbgmid | 内部状態 | int | リザルトBGMのBASSチャンネルID |

## 表示項目

| 項目名 | 表示位置 | 説明 |
|--------|----------|------|
| 背景画像 | 画面全体 | bg2.jpg（buffer 29） |
| リザルトフレーム | 画面中央 | result.png（Image 31/32）によるリザルト表示枠 |
| 曲名・アーティスト名 | フレーム上部 | 選択楽曲の曲名・アーティスト名テキスト。画像指定がある場合はtitle_img/artist_imgを使用 |
| ジャケット画像 | フレーム左上 | 楽曲のジャケット画像 |
| 難易度 | 曲名下 | result_difficulty.png（IMG_RESULT_DIFFICULTY）による難易度ラベル |
| スコア数値 | フレーム中央 | result_scorenum.png（Image 34）によるスコア表示 |
| グレード | スコア横 | result_grade.png（Image 33）によるD/C/B/A/AA/AAAグレード |
| 判定詳細 | フレーム下部 | CRITICAL/NEAR/ERROR/最大チェーン数の数値表示 |
| メダル | グレード横 | クリア/フルコンボ/パーフェクトメダル画像 |
| NEW RECORD | フレーム上 | ハイスコア更新時のNEW RECORD画像（Image 36）とスコア差分 |
| アンロック通知 | 画面下部 | completedlist変数に基づく楽曲アンロック表示（Image 95） |
| ツイートボタン | 画面右上 | result_tweetbtn.png（IMG_RESULT_TWEETBTN） |
| IRポップアップ | 画面右 | IRスコア送信結果のポップアップ |

## イベント仕様

### 1-判定結果集計

リザルト画面表示時に判定結果を再集計する（行78-158）：
- noteresult配列からCRITICAL/NEAR/ERRORを再カウント
- ショートノート/ロングノート/アナログノートそれぞれの判定を集計
- critical_short/critical_long/near_short/errorn_short/errorn_longに分類

### 2-スコア保存

プレイヤー別スコアファイル(.ksc)にスコア・メダル・判定情報を保存する。

### 3-NEW RECORD判定

保存済みハイスコアと今回のスコアを比較し、diff>0の場合にNEW RECORDアニメーションを表示する。

### 4-画面遷移（Enter/ESCキー）

Enter/ESCキー押下時の遷移処理（行637-679）：
- **コースモードかつ全曲未完了**：SCENE_COURSE_RESULTまたはSCENE_PLAYへ遷移
- **コースモードかつ最終曲完了**：SCENE_COURSE_RESULTへ遷移（行658）
- **コースモードかつ途中曲**：SCENE_PLAYへ遷移（次曲、行660）
- **通常モード**：SCENE_SELECTへ遷移（行668）

### 5-ツイートボタン

F11キーまたはマウスクリック（画面右上エリア）でスクリーンショット付きツイートを実行する（行621-633）。

## データベース更新仕様

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

| 操作（イベント） | 対象ファイル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| スコア保存 | score/プレイヤー名/*.ksc | INSERT/UPDATE | スコア・メダル・判定情報の保存 |
| IRスコア送信 | IRサーバー | INSERT | ir_send_scoreによるHTTP通信でスコア送信 |

### テーブル別更新項目詳細

#### スコアファイル (.ksc)

| 操作 | 項目 | 更新値 | 備考 |
|-----|------|--------|------|
| UPDATE | スコア | totalscore | ハイスコア更新時のみ |
| UPDATE | メダル | クリア/FC/パーフェクト | 上位メダル更新時のみ |
| UPDATE | グレード | D-AAA | ハイスコア更新時のみ |

## メッセージ仕様

| メッセージID | 種別 | 表示条件 | メッセージ内容 |
|-------------|------|----------|--------------|
| NEW RECORD | 通知 | diff>0（ハイスコア更新時） | NEW RECORD画像 + スコア差分 |
| アンロック通知 | 通知 | completedlist!="" | 楽曲アンロック演出画像 |

## 例外処理

| 例外条件 | 処理内容 |
|---------|---------|
| auto=1またはadjmode=1 | リザルト詳細を表示せず即座に次画面へ遷移 |
| コマンドライン起動(cmdline_from>0) | アプリケーション終了 |

## 備考

- auto=1（オートプレイ）またはadjmode=1（調整モード）の場合、リザルト詳細画面を表示せずに即座に次の遷移を行う。
- 判定結果はリザルト画面で再集計される。プレイ画面で計算されたtotalscoreはそのまま使用されるが、CRITICAL/NEAR/ERRORはnoteresult配列から再カウントされる。
- スコアファイル(.ksc)はプレイヤー別にscore/プレイヤー名/ディレクトリに保存される。
- ツイート機能はF11キーまたは画面右上のツイートボタンクリックで起動し、スクリーンショット画像を含むツイートを投稿する。

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | kshootmania.hsp | `kshootmania.hsp` | 行15: SCENE_RESULT=5、行92-93: IMG_RESULT_DIFFICULTY/IMG_RESULT_TWEETBTN定数 |

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | result.hsp | `src/scene/result.hsp` | 行1: `#deffunc on_update_result`がエントリーポイント |

**主要処理フロー**:
1. **行1-4**: 初期化（keshuoff=0, time_scene_start, ir_popup_init）
2. **行5**: コマンドライン起動時は即終了
3. **行6-31**: auto/adjmode時の即遷移処理
4. **行32-63**: リザルト画像リソースの読み込み
5. **行78-158**: 判定結果の再集計
6. **行159-**: リザルトフレーム描画・スコア保存・遷移処理

#### Step 3: 遷移処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | result.hsp | `src/scene/result.hsp` | 行637-679: Enter/ESCキーによる遷移判定。コースモード/通常モードでの分岐 |

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

```
kshootmania.hsp (メインループ)
    |
    +-- on_update_result (src/scene/result.hsp:1)
            |
            +-- ir_popup_init (行4) ... IRポップアップ初期化
            +-- [auto/adjmode] 即遷移処理 (行6-31)
            +-- 画像リソース読み込み (行32-63)
            +-- 判定結果再集計 (行78-158)
            +-- スコア保存処理
            +-- メインループ (行606-)
                    +-- 描画処理（フレーム・スコア・グレード・判定）
                    +-- ツイートボタン判定 (行621-633)
                    +-- Enter/ESC遷移判定 (行637-679)
                            +-- コースモード完了 -> SCENE_COURSE_RESULT
                            +-- コースモード途中 -> SCENE_PLAY
                            +-- 通常モード -> SCENE_SELECT
```

### データフロー図

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

noteresult配列 ---------> 判定再集計 (行78-158) ---------> critical/near/errorn
totalscore ------------->                                   |
gauge ------------------>                                   v
                                                     グレード計算 --> 画面表示
                                                     メダル計算 ----> 画面表示
                                                     diff計算 ------> NEW RECORD
                                                            |
                                                            v
                                                     スコアファイル保存 (.ksc)
                                                     IRスコア送信 (ir_send_score)

Enter/ESCキー ---------> 遷移判定
                              |
                  +-----------+-----------+
                  |           |           |
                  v           v           v
            SCENE_        SCENE_      SCENE_
            SELECT        PLAY        COURSE_RESULT
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| result.hsp | `src/scene/result.hsp` | ソース | リザルト画面の全処理。on_update_result関数 |
| kshootmania.hsp | `kshootmania.hsp` | ソース | メインループ、シーン管理、定数定義 |
| result.png | `imgs/result.png` | リソース | リザルトフレーム画像 |
| result_grade.png | `imgs/result_grade.png` | リソース | グレード画像（D/C/B/A/AA/AAA） |
| result_scorenum.png | `imgs/result_scorenum.png` | リソース | スコア数字画像 |
| result_newrecord.png | `imgs/result_newrecord.png` | リソース | NEW RECORD画像 |
| result_top.png | `imgs/result_top.png` | リソース | リザルト上部画像 |
| result_difficulty.png | `imgs/result_difficulty.png` | リソース | 難易度ラベル画像 |
| result_tweetbtn.png | `imgs/result_tweetbtn.png` | リソース | ツイートボタン画像 |
| result_unlocked.png | `imgs/result_unlocked.png` | リソース | アンロック通知画像 |
