# 画面設計書 7-コースリザルト画面

## 概要

本ドキュメントは、K-Shoot MANIA のコースリザルト画面の設計仕様を記述する。コースモード完了後の累積成績表示画面であり、コース全体のスコア、曲ごとの成績リスト、難易度別スコア、合計判定数をスクロール可能なリストで表示する。

### 本画面の処理概要

コースリザルト画面はコースモード（複数楽曲の連続プレイ）完了後に表示される総合成績画面であり、個別楽曲の成績と累積成績を一覧表示する。

**業務上の目的・背景**：コースモードでは複数曲を通してプレイするため、個別曲ごとの成績と全体の累積成績を一覧で確認できる画面が必要である。各曲のスコア・グレード・メダルの一覧と、コース全体の合計スコア・合計判定数を提供する。

**画面へのアクセス方法**：リザルト画面からコースモード最終曲完了後に自動遷移する。

**主要な操作・処理内容**：
1. コース内各曲の成績リスト表示（曲名・アーティスト名・ジャケット・難易度・レベル・スコア・グレード・メダル）
2. コース全体の合計スコア・グレード表示
3. コース全体のゲージ・クリア判定表示
4. CRITICAL/NEAR/ERROR合計判定数表示
5. NEW RECORD表示（コースハイスコア更新時）
6. スクロール可能なリスト表示（4曲以上の場合）
7. コーススコアの保存

**画面遷移**：
- 遷移先：曲選択画面（SCENE_SELECT、Enter/ESCキー、行494）
- 遷移元：リザルト画面（SCENE_RESULT、コースモード最終曲完了）

**権限による表示制御**：auto=1またはadjmode=1の場合、詳細を表示せず即座にSCENE_SELECTへ遷移する（行5-21）。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 5 | コース結果画面 | 主機能 | コース全体のスコア・各曲スコアリスト・グレード・メダルを表示する主処理 |
| 81 | コース結果表示 | 主機能 | コース内各曲のスコア一覧(IMG_CRESULT_LISTBUF)・合計スコア・ゲージ・グレードのスクロール可能リスト表示 |
| 75 | スコア・グレード表示 | 主機能 | 合計スコアとD/C/B/A/AA/AAAグレードをImage画像で表示 |
| 76 | クリア判定表示 | 主機能 | ゲージパーセンテージ・クリア判定・メダルの表示(IMG_CRESULT_GAUGE) |
| 77 | 判定詳細表示 | 主機能 | coursecritical/coursenear/courseerrorによるコース全体の判定詳細数値表示 |
| 78 | NEW RECORD表示 | 補助機能 | コースハイスコア更新時のNEW RECORD表示(IMG_CRESULT_NEWRECORD) |
| 79 | スコア保存 | 主機能 | コーススコアファイルへのコース全体スコア・各曲成績の保存 |
| 58 | キーボード入力 | 補助機能 | Enter/Escキーによるコースリザルト画面からの遷移操作 |
| 59 | ジョイスティック入力 | 補助機能 | getjoykeystatによるジョイスティック入力 |
| 42 | 音量制御 | 補助機能 | コースリザルトBGMのマスターボリューム適用 |
| 24 | 文字エンコード自動判定 | 補助機能 | 各曲の譜面ファイル読み込み時のUTF-8/Shift-JIS自動判定 |
| 101 | 多言語テキスト管理 | 補助機能 | lang変数によるUIラベルの多言語表示 |
| 130 | BASS Audio Library | 補助機能 | courseresultbgmidによるコースリザルトBGMの再生制御 |
| 7 | シーン遷移管理 | 遷移先機能 | Enter/Esc押下によるSCENE_SELECT遷移 |

## 画面種別

詳細表示画面（コース累積成績表示・スクロール対応リスト）

## URL/ルーティング

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

## 入出力項目

| 項目名 | 入出力 | データ型 | 説明 |
|--------|--------|----------|------|
| coursetotalscore | 入力 | int | コース累計スコア |
| coursecritical | 入力 | int | コース累計CRITICAL数 |
| coursenear | 入力 | int | コース累計NEAR数 |
| courseerrorn | 入力 | int | コース累計ERROR数 |
| courselistnum | 入力 | int | コース内の曲数 |
| courselist | 入力 | string | コース内曲リスト（改行区切り） |
| course_sc | 入力 | int配列 | 各曲のスコア |
| course_md | 入力 | int配列 | 各曲のメダル |
| course_gr | 入力 | int配列 | 各曲のグレード |
| ccoursetitle | 入力 | string | コースタイトル |
| courseresultbgmid | 内部状態 | int | コースリザルトBGMのBASSチャンネルID |

## 表示項目

| 項目名 | 表示位置 | 説明 |
|--------|----------|------|
| 背景画像 | 画面全体 | bg2.jpg（buffer 29） |
| リザルトフレーム | 画面中央 | result.png（Image 31/32）によるリザルト表示枠 |
| コース情報 | フレーム上部 | courseresult_info.png（IMG_CRESULT_INFO）によるコースタイトル・合計スコア表示 |
| 曲リスト | フレーム中央 | IMG_CRESULT_LISTBUFに描画された各曲の成績一覧（スクロール対応） |
| 各曲項目 | リスト内 | courseresult_item.png（IMG_CRESULT_ITEM）にジャケット・曲名・アーティスト・難易度・レベル・スコア・グレード・メダルを表示 |
| スクロール矢印 | リスト上下 | courseresult_arrow.png（IMG_CRESULT_ARROW）によるスクロール可能表示 |
| 合計スコア | フレーム上部 | coursetotalscore値のスコア数値表示 |
| グレード | スコア横 | result_grade.png（Image 33）によるコース全体グレード |
| ゲージ | フレーム | courseresult_gauge.png（IMG_CRESULT_GAUGE）によるゲージ表示 |
| NEW RECORD | フレーム上 | courseresult_newrecord.png（IMG_CRESULT_NEWRECORD） |
| 判定詳細 | フレーム下部 | coursecritical/coursenear/courseerrornの合計値 |

## イベント仕様

### 1-曲リスト構築

コースリザルト画面表示時に各曲の情報を構築する（行71-200付近）：
1. courselist配列から各曲のパスを取得
2. 各曲の譜面ファイルを読み込み、曲名・アーティスト名・難易度・レベル・ジャケット画像を取得
3. UTF-8/Shift-JIS自動判定によるテキストエンコード処理
4. IMG_CRESULT_LISTBUFにリスト項目を描画

### 2-スクロール操作

4曲以上のコースでは上下キーによるスクロール操作が可能。IMG_CRESULT_ARROWでスクロール可能方向を表示。

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

Enter/ESCキー押下でSCENE_SELECTへ遷移する（行484-502）：
1. コースリザルトBGMを100msでフェードアウト（行488）
2. refreshsonglistoff=1を設定
3. scene=SCENE_SELECTに設定（行494）
4. LOADING画像を表示

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

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

| 操作（イベント） | 対象ファイル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| コーススコア保存 | score/プレイヤー名/ | INSERT/UPDATE | コーススコアの保存 |

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

該当なし（ファイルベースアーキテクチャ）。

## メッセージ仕様

| メッセージID | 種別 | 表示条件 | メッセージ内容 |
|-------------|------|----------|--------------|
| NEW RECORD | 通知 | コースハイスコア更新時 | IMG_CRESULT_NEWRECORD画像表示 |

## 例外処理

| 例外条件 | 処理内容 |
|---------|---------|
| auto=1またはadjmode=1 | 詳細を表示せず即座にSCENE_SELECTへ遷移 |
| 譜面ファイル読み込み失敗 | 曲名等が表示されないが処理は続行 |

## 備考

- コースリザルト画面はリザルト画面（result.hsp）と類似の構造を持つが、コース固有の累積表示機能を持つ。
- 曲リストの高さ（stat_h）はcourselistnumに応じて動的に計算される（行4）。4曲以上の場合とそれ未満で計算式が異なる。
- 各曲の情報は譜面ファイルを直接読み込んで取得するため、表示時に多少の遅延が発生する可能性がある。
- ツイート機能はリザルト画面と同様にF11キーまたはマウスクリックで利用可能。

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | kshootmania.hsp | `kshootmania.hsp` | 行16: SCENE_COURSE_RESULT=6、行95-100: IMG_CRESULT_*定数群 |

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

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

**主要処理フロー**:
1. **行1-4**: 初期化（time_scene_start, stat_h計算）
2. **行5-21**: auto/adjmode時の即遷移処理
3. **行22-70**: 画像リソース読み込み・リストバッファ作成
4. **行71-200**: 各曲情報の読み込みとリスト描画
5. **行456-**: メインループ（描画・スクロール・遷移判定）

#### Step 3: 曲リスト描画を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | course_result.hsp | `src/scene/course_result.hsp` | 行71-200: 各曲の譜面読み込み、UTF-8/Shift-JIS判定、曲名・アーティスト・難易度・ジャケット描画 |

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

```
kshootmania.hsp (メインループ)
    |
    +-- on_update_course_result (src/scene/course_result.hsp:1)
            |
            +-- [auto/adjmode] 即遷移 (行5-21)
            +-- 画像リソース読み込み (行22-70)
            |       +-- result.png, result_grade.png, courseresult_*.png
            +-- 各曲情報読み込みループ (行71-200)
            |       +-- notesel/noteload ... 各曲の譜面読み込み
            |       +-- UTF-8 BOM判定 (行88-91)
            |       +-- 曲名/アーティスト描画 (行130-155)
            |       +-- ジャケット画像読み込み (行169-172)
            |       +-- 難易度/レベル/スコア/グレード/メダル描画
            |
            +-- メインループ (行456-)
                    +-- 描画処理
                    +-- スクロール操作（上下キー）
                    +-- Enter/ESC遷移判定 (行484-502)
                            +-- scene=SCENE_SELECT
```

### データフロー図

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

courselist (曲リスト) -----> 各曲パス取得
                                |
各曲 *.ksh ファイル -------> notesel/noteload ------> 曲情報取得
                                |
                                v
                         IMG_CRESULT_LISTBUFに描画

coursetotalscore ---------> 合計スコア表示
coursecritical/near/error -> 合計判定数表示
course_sc/md/gr ----------> 各曲スコア/メダル/グレード表示

Enter/ESCキー ------------> scene=SCENE_SELECT
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| course_result.hsp | `src/scene/course_result.hsp` | ソース | コースリザルト画面の全処理。on_update_course_result関数 |
| kshootmania.hsp | `kshootmania.hsp` | ソース | メインループ、定数定義 |
| result.png | `imgs/result.png` | リソース | リザルトフレーム画像 |
| result_grade.png | `imgs/result_grade.png` | リソース | グレード画像 |
| courseresult_info.png | `imgs/courseresult_info.png` | リソース | コース情報表示枠 |
| courseresult_item.png | `imgs/courseresult_item.png` | リソース | 各曲リスト項目枠 |
| courseresult_arrow.png | `imgs/courseresult_arrow.png` | リソース | スクロール矢印 |
| courseresult_gauge.png | `imgs/courseresult_gauge.png` | リソース | ゲージ画像 |
| courseresult_newrecord.png | `imgs/courseresult_newrecord.png` | リソース | NEW RECORD画像 |
