# 機能設計書 1-タイトル画面

## 概要

K-Shoot MANIAの起動時に最初に表示されるタイトル画面の機能設計書である。タイトルBGMの再生、ジョイスティックの検索・初期化、テクスチャ・画像の初期ロード、メニュー項目の表示と選択を担当する。

### 本機能の処理概要

タイトル画面は、K-Shoot MANIAの起動後に最初にユーザーが触れる画面であり、ゲーム全体のエントリーポイントとして機能する。ユーザーはここからゲーム本編（選曲画面）、オプション設定、ゲート画面、終了のいずれかを選択できる。

**業務上の目的・背景**：音楽ゲームにおけるタイトル画面は、ゲーム起動後にユーザーが最初に見る画面であり、ゲーム内の各機能へのナビゲーションハブとして機能する。また、初回起動時やオプション変更後のテクスチャ再読み込み処理を担い、描画品質設定に応じた画像リソースの最適化を行う重要な初期化処理を含む。

**機能の利用シーン**：ゲーム起動直後、オプション設定画面からの復帰時、選曲画面からの戻り時に表示される。ユーザーはメニューから「Play」「Option」「Gate」「Exit」を選択してゲームの各機能にアクセスする。

**主要な処理内容**：
1. ジョイスティックデバイスの検索と初期化（JStickSearchID）
2. IME状態の無効化
3. テクスチャ・画像リソースの読み込みとキャッシュ生成（オプション変更後）
4. タイトルBGM（title_bgm.ogg）のストリーミング再生
5. メニュー項目（Play/Option/Gate/Exit）の描画と選択カーソル表示
6. キーボード・ジョイスティック入力によるメニュー項目選択
7. 選択決定時のシーン遷移（IR Sign-In / Option / Gate / Exit）
8. フェードイン・フェードアウトのトランジション演出

**関連システム・外部連携**：BASS Audio Library（タイトルBGM・SE再生）、Direct3D（画面描画）、Win32 API（ジョイスティック入力）

**権限による制御**：特になし。全ユーザーが同一の操作が可能。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 1 | タイトル画面 | 主画面 | タイトルBGM再生、ジョイスティック初期化、テクスチャ・画像キャッシュ読み込み、メニュー項目表示を行うタイトル画面の主処理 |
| 2 | IRサインイン画面 | 遷移先画面 | IRサインイン画面経由で曲選択画面(SCENE_SELECT)へ遷移 |
| 8 | オプション設定画面 | 遷移先画面 | メニュー項目「Option」選択時にオプション設定画面(SCENE_OPTION)へ遷移 |

## 機能種別

画面表示・初期化処理・シーン遷移制御

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| prev_scene | int | Yes | 前のシーンのID | SCENE_OPTION / SCENE_IR_SIGN_IN / SCENE_GATE 等 |
| is_scene_initial_frame | int | Yes | シーン初期化フラグ（1=初期化要） | 0 or 1 |
| imgrefresh | int | No | テクスチャ再読み込みフラグ | 0 or 1 |
| lowquality | int | No | 描画品質設定 | 0(高) / 1(中) / 2(低) |
| mastervol | int | No | マスターボリューム | 0-100 |

### 入力データソース

- config.ini：キーバインド設定、HiSpeed設定、画面設定、言語設定等
- standby.jpg：タイトル背景画像のキャッシュ
- imgs/ディレクトリ配下の各種テクスチャファイル

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| scene | int | 遷移先シーンID（SCENE_IR_SIGN_IN / SCENE_OPTION / SCENE_GATE） |
| is_scene_initial_frame | int | 次シーンの初期化フラグ |
| standbyselp | int | タイトル画面での選択位置 |

### 出力先

- 画面表示（タイトル背景、メニュー項目、カーソル）
- グローバル変数（scene, is_scene_initial_frame, standbyselp）

## 処理フロー

### 処理シーケンス

```
1. シーン初期化（is_scene_initial_frame=1の場合）
   ├─ ジョイスティック検索・初期化（JStickSearchID）
   ├─ IME無効化
   └─ テクスチャ再読み込み（imgrefresh=1の場合）
       ├─ LOADING表示
       ├─ standby.jpgキャッシュ読み込み
       ├─ 各種画像リソース読み込み（ノート、判定、背景、選曲画面用等）
       ├─ 描画品質に応じた画像縮小処理（ra=max(powf(2,lowquality),1)）
       └─ コマンドライン引数による直接起動処理
2. タイトル画面表示ループ
   ├─ 背景画像描画（standby.jpg）
   ├─ メニュー項目描画（Play/Option/Gate/Exit）
   ├─ 選択カーソル描画（半透明アニメーション付き）
   ├─ フェードイン演出（最初の500ms）
   └─ 入力処理
       ├─ 上下キー / ジョイスティックによるメニュー選択
       ├─ Enterキー / ジョイスティックボタンによる決定
       └─ Escキーによる「Exit」選択
3. シーン遷移
   ├─ selnow=0: SCENE_IR_SIGN_IN（Play選択）
   ├─ selnow=1: SCENE_OPTION（Option選択）
   ├─ selnow=2: SCENE_GATE（Gate選択）
   └─ selnow=3: ゲーム終了（*exit）
```

### フローチャート

```mermaid
flowchart TD
    A[タイトル画面開始] --> B{初期化フレーム?}
    B -->|Yes| C[ジョイスティック初期化]
    C --> D{テクスチャ再読み込み?}
    D -->|Yes| E[全テクスチャ読み込み・キャッシュ生成]
    D -->|No| F[メニュー画像読み込み]
    E --> F
    B -->|No| F
    F --> G[タイトルBGM再生]
    G --> H[メインループ開始]
    H --> I[背景・メニュー描画]
    I --> J[入力処理]
    J --> K{Enter押下?}
    K -->|Yes| L{選択項目}
    K -->|No| M{上下キー?}
    M -->|Yes| N[カーソル移動]
    M -->|No| O{Esc押下?}
    O -->|Yes| P[Exit選択]
    O -->|No| H
    N --> H
    L -->|Play| Q[SCENE_IR_SIGN_IN]
    L -->|Option| R[SCENE_OPTION]
    L -->|Gate| S[SCENE_GATE]
    L -->|Exit| T[ゲーム終了]
    P --> U[Exit項目選択表示]
    U --> H
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-01 | メニュー項目範囲制限 | selnowは0-3の範囲に制限される | 常時 |
| BR-02 | BGM再生条件 | IRサインイン画面からの復帰時はBGMを再生しない | prev_scene=SCENE_IR_SIGN_IN |
| BR-03 | テクスチャ再読み込み | オプション画面で設定変更後にimgrefresh=1の場合のみ全テクスチャを再読み込み | prev_scene=SCENE_OPTION かつ imgrefresh=1 |
| BR-04 | カーソルアニメーション | 選択カーソルはsin波によるパルス半透明エフェクト付き | 常時 |
| BR-05 | コマンドライン起動 | .ksh/.kcoファイル指定での直接起動時はタイトル画面をスキップ | iscmdline=1 |

### 計算ロジック

- 描画品質係数: `ra = max(powf(2, lowquality), 1)` (lowquality=0:1, 1:2, 2:4)
- カーソル透過率: `166 + int(sin(double(d3timer()) / 150 + 1.0) / 2 * 90)` (166-256の範囲でパルス)
- カーソルY座標: `(260 + curpos * 25) * scrsize_h / 480` (curposはスムーズ補間)

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

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

本機能ではデータベース操作は行わない。ファイルベースの設定管理（config.ini）のみ参照する。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | ファイル不在 | standby.jpgキャッシュが存在しない | キャッシュなしで続行 |
| - | コマンドライン不正 | 指定ファイルが.ksh/.kco以外 | エラーダイアログ表示後に終了 |
| - | 画像読み込み失敗 | picload対象ファイルが存在しない | ファイル名を含むエラーダイアログを表示 |

### リトライ仕様

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

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

トランザクション処理は適用されない（ファイルベースの読み込みのみ）。

## パフォーマンス要件

- メインループは7ms間隔のawaitで動作（約143fps上限）
- テクスチャ再読み込み時はLOADING表示で体感待機を軽減
- 描画品質設定（lowquality）により画像サイズを1/2~1/4に縮小し描画負荷を低減

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

特になし。ローカルリソースの読み込みのみ。

## 備考

- HSP（Hot Soup Processor）言語で実装されたWindowsネイティブアプリケーション
- HGIMG3プラグインによる3D描画エンジンを使用
- バージョン: v1.75b

---

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

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

### 推奨読解順序

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

まず、シーン管理に使用される列挙定数と主要なグローバル変数を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | kshootmania.hsp | `kshootmania.hsp` | シーン列挙定数の定義（SCENE_TITLE=0等）と画像バッファ定数 |

**読解のコツ**: HSPの`#enum`は0から始まる列挙定数を定義する。`#define`はC言語のマクロに相当する。

- **11-19行目**: シーン列挙定数（SCENE_TITLE=0, SCENE_IR_SIGN_IN=1, ..., SCENE_GATE=8）
- **75行目**: バージョン文字列定義 `aversion "1.75b"`
- **82-111行目**: 画像バッファ番号の定数定義

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

メインループからタイトル画面が呼び出される仕組みを理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | kshootmania.hsp | `kshootmania.hsp` | メインループ（947-1235行目）とシーン分岐 |

**主要処理フロー**:
1. **947行目**: `repeat` でメインループ開始
2. **948行目**: `switch scene` でシーン分岐
3. **949-951行目**: `case SCENE_TITLE` で `start_title` を呼び出し
4. **1217-1234行目**: ループ末尾でフレームスキップ制御と再描画

#### Step 3: タイトル画面の初期化処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | title.hsp | `src/scene/title.hsp` | start_titleサブルーチンの初期化部分（1-561行目） |

**主要処理フロー**:
- **1行目**: `#deffunc start_title` でサブルーチン定義
- **7-9行目**: ジョイスティック検索・初期化
- **10行目**: IME無効化
- **14-561行目**: `imgrefresh=1`時のテクスチャ全体再読み込み処理
- **16行目**: 描画品質係数 `ra=max(powf(2,lowquality),1)` の算出
- **32-44行目**: standby.jpgキャッシュの読み込みとサイズ検証
- **530-559行目**: コマンドライン引数による.ksh/.kcoファイル直接起動

#### Step 4: タイトル画面のメインループを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | title.hsp | `src/scene/title.hsp` | メニュー表示・入力ループ（562-747行目） |

**主要処理フロー**:
- **576-580行目**: タイトルBGM再生（IRサインインからの復帰時は再生しない）
- **594行目**: `repeat` でメインループ開始
- **596行目**: ジョイスティック状態取得 `gosub *getjoystat`
- **604-611行目**: Escキー処理（Exit選択）
- **612-658行目**: Enterキー処理（シーン遷移分岐）
  - **631行目**: selnow=0 → SCENE_IR_SIGN_IN
  - **641行目**: selnow=1 → SCENE_OPTION
  - **650行目**: selnow=2 → SCENE_GATE
  - **657行目**: selnow=3 → *exit（ゲーム終了）
- **664-697行目**: 上下キー入力処理（メニューカーソル移動）
- **709-711行目**: カーソル描画（sin波アニメーション付き半透明表示）

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

```
kshootmania.hsp (メインループ: 947行目)
    │
    ├─ start_title (src/scene/title.hsp: 1行目)
    │      ├─ JStickSearchID (ジョイスティック検索)
    │      ├─ *joyinit (ジョイスティック初期化)
    │      ├─ テクスチャ読み込み群 (picload, alCreateImageByFile等)
    │      ├─ picload_zoom_cache (キャッシュ付き画像読み込み: 768行目)
    │      ├─ generate_cache_imgs (キャッシュ画像生成: 519行目)
    │      ├─ BASS_StreamCreateFile (BGM読み込み: 576行目)
    │      ├─ BASS_ChannelPlay (BGM再生: 579行目)
    │      ├─ *getjoystat (ジョイスティック状態取得)
    │      ├─ *keshu (キー入力処理)
    │      ├─ *volactive (ボリューム制御)
    │      └─ blackout/whiteout (トランジション演出)
    │
    └─ *exit (終了処理)
```

### データフロー図

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

config.ini ──────────────────▶ start_title初期化 ──────────────▶ 画面描画
                                    │                               │
imgs/*.gif/png ──────────────▶ テクスチャ読み込み                   ├─ 背景表示
                                    │                               ├─ メニュー項目表示
se/title_bgm.ogg ───────────▶ BASS Audio再生                      └─ カーソル表示
                                    │
キーボード/ジョイスティック ──▶ 入力処理 ─────────────────────▶ scene変数
                                    │                          (遷移先シーンID)
                                    └── selnow(選択位置) ──▶ standbyselp
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| kshootmania.hsp | `kshootmania.hsp` | ソース | メインループ・シーン分岐・グローバル変数定義 |
| title.hsp | `src/scene/title.hsp` | ソース | タイトル画面の初期化・表示・入力処理 |
| config.ini | `config.ini` | 設定 | キーバインド・画面設定・HiSpeed等の設定ファイル |
| standby.jpg | `cache/standby.jpg` | キャッシュ | タイトル背景画像キャッシュ |
| title_bgm.ogg | `se/title_bgm.ogg` | 音声 | タイトルBGM |
| title_sel.wav | `se/title_sel.wav` | 音声 | メニュー選択SE |
| title_enter.wav | `se/title_enter.wav` | 音声 | メニュー決定SE |
| standby.jpg | `imgs/standby.jpg` | 画像 | タイトル背景原画像 |
| standby_cur.gif | `imgs/standby_cur.gif` | 画像 | 選択カーソル画像 |
| standby_item.gif | `imgs/standby_item.gif` | 画像 | メニュー項目画像 |
| loading.png | `imgs/loading.png` | 画像 | ローディング表示画像 |
| bass.as | `src/bass.as` | ソース | BASS Audio Libraryバインディング |
| winapi.as | `src/winapi.as` | ソース | Win32 APIバインディング |
| mod_joystick.as | `mod_joystick.as` | ソース | ジョイスティック入力モジュール |
