# 機能設計書 14-コースモード

## 概要

本ドキュメントは、K-Shoot MANIA の選曲画面における「コースモード」機能の設計を記述する。複数曲を連続してプレイするコースモードの選択・コース内楽曲情報の表示機能である。

### 本機能の処理概要

本機能は、`.kco`(K-Shoot Course)ファイルで定義されたコースを選曲画面上で選択・表示し、SCENE_BEFORE_PLAYに遷移してコースモードでのプレイを開始する機能を提供する。コースは`courses`ディレクトリまたは各楽曲パッケージ内に配置され、複数の楽曲を順番にプレイする。

**業務上の目的・背景**：単曲プレイだけでなく、複数曲を連続してプレイするコースモードにより、段位認定・チャレンジ・テーマ別セットリストなど多様なプレイスタイルを提供する。

**機能の利用シーン**：
- ルートメニューの「Courses」フォルダを選択: `courses/`ディレクトリ内の.kcoファイル一覧を表示
- コースエントリを選択してEnter: SCENE_BEFORE_PLAYに遷移し、iscourse=1でコースモード開始
- 選曲画面でコースの詳細情報(各曲タイトル・アーティスト・難易度・レベル)を表示

**主要な処理内容**：
1. `courses/`ディレクトリおよび楽曲パッケージ内の`.kco`ファイルの検出・一覧化
2. `.kco`ファイルのメタデータ解析(title, information, icon)
3. コース内各曲の譜面ファイル読み込みと情報表示(IMG_MSEL_COURSETEMP)
4. コース選択時のSCENE_BEFORE_PLAYへの遷移(iscourse=1設定)
5. コーススコアの読み込みと表示(`courses/score/`ディレクトリ)

**関連システム・外部連携**：ファイルシステム(courses/ディレクトリ)。

**権限による制御**：なし。全プレイヤーが利用可能。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 3 | 曲選択画面 | 主画面 | コースファイル(.kco)選択時のSCENE_BEFORE_PLAYへの遷移によるコースモード開始 |
| 4 | プレイ前処理画面 | 遷移先 | コースファイル解析後にSCENE_PLAYまたはSCENE_SELECTへ遷移制御 |

## 機能種別

データ読み込み / ナビゲーション処理

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| minfo.selnow.0.0 | int | Yes | 選択項目の種別(4=コース) | 4の場合にコース処理 |
| minfostr.selnow.0.5 | string | Yes | コースファイル名(.kco) | .kco拡張子 |
| dir | string | Yes | 現在のディレクトリ("..\\courses"=Coursesフォルダ) | - |

### 入力データソース

- ファイルシステム: `courses/*.kco`ファイル、各楽曲パッケージ内の`*.kco`ファイル
- `.kco`ファイル内: title, information, icon, 各曲のKSHファイルパス

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| iscourse | int | コースモードフラグ(1=コースモード) |
| scene | int | 遷移先シーン(SCENE_BEFORE_PLAY) |
| IMG_MSEL_COURSETEMP | image | コース内各曲情報の描画用テンポラリ画像 |

### 出力先

- 画面表示: コース内各曲のタイトル・アーティスト・難易度・レベル・ジャケット
- シーン遷移: SCENE_BEFORE_PLAY

## 処理フロー

### 処理シーケンス

```
1. *refreshfilelist内でコースファイルを検出
   ├─ courses/ディレクトリの.kcoファイルをfilelistkco_coursesに追加
   └─ 各楽曲パッケージ内の.kcoファイルをfilelistkcoに追加
2. .kcoファイルのメタデータ解析
   ├─ title: コースタイトル
   ├─ title_img: タイトル画像
   ├─ information: コース説明文
   └─ icon: コースアイコン画像パス
3. minfo配列にminfo.*.0.0=4(コース種別)で登録
4. *refreshsonginfo内でコース詳細表示(minfo.*.0.0=4の場合)
   ├─ .kcoファイルの各セクション([パス])を解析
   ├─ 各曲の譜面ファイルを読み込み(title/artist/difficulty/level/jacket)
   └─ IMG_MSEL_COURSETEMPに各曲情報を描画
5. コース選択・Enter押下時
   ├─ iscourse=1を設定
   └─ scene=SCENE_BEFORE_PLAYに遷移
```

### フローチャート

```mermaid
flowchart TD
    A[*refreshfilelist] --> B[courses/ディレクトリ走査]
    B --> C[.kcoファイル検出]
    C --> D[メタデータ解析 title/information/icon]
    D --> E[minfo配列にコースエントリ登録]
    E --> F[*refreshsonginfo]
    F --> G{minfo.selnow.0.0 = 4?}
    G -->|Yes| H[.kcoファイル内のセクション解析]
    H --> I[各曲の譜面ファイル読み込み]
    I --> J[IMG_MSEL_COURSETEMPに描画]
    J --> K[コース情報表示]
    G -->|No| L[通常楽曲情報表示]
    K --> M{Enter押下?}
    M -->|Yes| N[iscourse=1 / scene=SCENE_BEFORE_PLAY]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-14-1 | コース種別 | minfo.*.0.0=4でコースエントリを識別 | 常時 |
| BR-14-2 | コースフォルダ | `courses/`ディレクトリと各楽曲パッケージ内の.kcoを両方検出 | *refreshfilelist時 |
| BR-14-3 | UTF-8対応 | .kcoファイルのUTF-8 BOMを検出し、タイトル等にBOMプレフィックスを付与 | .kcoファイル読み込み時 |
| BR-14-4 | コーススコアパス | コースのスコアは`courses/score/[プレイヤー名]/`に保存 | dir="..\\courses"の場合 |
| BR-14-5 | 曲存在確認 | コース内の各曲パスが存在しない場合は"---"を表示 | *refreshsonginfo内 |

### 計算ロジック

.kcoファイルのセクション構造:
```
title=コースタイトル
information=説明文
icon=アイコンファイル名
--
[パッケージ/曲フォルダ/ファイル.ksh]
[パッケージ/曲フォルダ/ファイル.ksh]
...
```

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

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

本機能ではデータベース操作は行わない。ファイルシステムの読み取りのみ。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | 曲ファイル不在 | コース内の譜面ファイルが存在しない場合 | "---"テキストを表示(lang.2.10) |
| - | .kcoファイル不在 | coursesディレクトリが空の場合 | Coursesエントリ自体が非表示 |

### リトライ仕様

なし。

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

トランザクション管理は不要。ファイルシステムの読み取り操作のみ。

## パフォーマンス要件

- コース詳細表示時に各曲の譜面ファイルを読み込むため、曲数が多いコースでは表示に時間がかかる可能性がある
- IMG_MSEL_COURSETEMPの画像サイズは曲数に応じて動的に生成される

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

特になし。ローカルファイルシステムの読み取り操作のみ。

## 備考

- コース内曲数が5曲以上の場合、表示領域をスクロールして表示する(2268-2272行目)
- iscourse変数はSCENE_BEFORE_PLAYで参照され、コースファイルの解析と連続プレイの制御に使用される
- コースモード中は選曲画面の`courseendfl`フラグでコース終了を管理する

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | select.hsp | `src/scene/select.hsp` | minfo.*.0.0=4がコースエントリ、-8がCoursesフォルダ、-9がCoursesフォルダ戻るを示す |
| 1-2 | select.hsp | `src/scene/select.hsp` | filelistkco_courses(courses/直下の.kcoリスト)、filelistkco(パッケージ内.kcoリスト)の管理 |

**読解のコツ**: .kcoファイルは「--」行で区切られ、前半がメタデータ、後半が`[パス]`形式の曲リストとなる。

#### Step 2: コースファイル検出を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | select.hsp | `src/scene/select.hsp` | 2586-2592行目のCoursesエントリ生成(ルートメニュー) |
| 2-2 | select.hsp | `src/scene/select.hsp` | 2659-2670行目のCoursesフォルダ処理(dirtype=3) |
| 2-3 | select.hsp | `src/scene/select.hsp` | 2897-2903行目のパッケージ内.kcoファイル検出 |

**主要処理フロー**:
1. **2587-2592行目**: courses/ディレクトリの.kcoファイルをリスト化、Coursesエントリ生成
2. **2971-3027行目**: .kcoファイルのメタデータ解析とminfo配列への登録

#### Step 3: コース詳細表示を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | select.hsp | `src/scene/select.hsp` | 4530-4676行目の*refreshsonginfo内コース詳細処理 |

**主要処理フロー**:
- **4530-4540行目**: .kcoファイル読み込みとUTF-8 BOM検出
- **4541-4548行目**: 「--」以降のセクション数カウント
- **4550-4551行目**: IMG_MSEL_COURSETEMP画像生成(曲数に応じたサイズ)
- **4555-4675行目**: 各セクションの譜面ファイル読み込みと描画
- **4584-4612行目**: 各曲のtitle/artist/difficulty/level/jacket/title_img/artist_img解析
- **4619-4666行目**: 各曲情報のIMG_MSEL_COURSETEMPへの描画

#### Step 4: コース選択・遷移を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | select.hsp | `src/scene/select.hsp` | 1650-1705行目のコース選択・遷移処理 |

**主要処理フロー**:
- **1654行目**: `iscourse=1` - コースモードフラグ設定
- **1704行目**: `scene=SCENE_BEFORE_PLAY` - シーン遷移

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

```
*refreshfilelist
    |
    +-- courses/ディレクトリ走査 (2586-2592行目)
    +-- パッケージ内.kco検出 (2897-2903行目)
    +-- .kcoメタデータ解析 (2971-3027行目)
    |       +-- title/information/icon/title_img解析
    |       +-- minfo配列へのコースエントリ登録(minfo.*.0.0=4)
    |
*refreshsonginfo (minfo.selnow.0.0=4の場合)
    |
    +-- .kcoファイル読み込み (4530-4540行目)
    +-- セクション数カウント (4541-4548行目)
    +-- IMG_MSEL_COURSETEMP生成 (4550行目)
    +-- 各曲情報の解析・描画 (4555-4675行目)
    |       +-- 各曲の譜面読み込み(noteload)
    |       +-- title/artist/difficulty/level/jacket解析
    |       +-- alDrawText/alStretchImageToImageによる描画
    |
メインループ (Enter押下時)
    |
    +-- iscourse=1設定 (1654行目)
    +-- scene=SCENE_BEFORE_PLAY (1704行目)
```

### データフロー図

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

courses/*.kco -----------> .kcoメタデータ解析 -----------> minfo/minfostr配列
                                |
.kco内セクション ---------> 各曲譜面ファイル読み込み ----> course_songtitle等
                                |                              |
各曲の.kshファイル -------> title/artist/level等解析 ----> IMG_MSEL_COURSETEMP
                                |
Enter押下 ----------------> iscourse=1設定 -------------> SCENE_BEFORE_PLAY遷移
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| select.hsp | `src/scene/select.hsp` | ソース | コースファイル検出、メタデータ解析、詳細表示、遷移処理 |
| *.kco | `courses/*.kco` | データ | コース定義ファイル(タイトル・曲リスト) |
| *.kco | `songs/[パッケージ]/*.kco` | データ | パッケージ内コース定義ファイル |
| *.ksc | `courses/score/[プレイヤー]/*.ksc` | データ | コーススコアファイル |
