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

## 概要

本ドキュメントは、K-Shoot MANIA のタイトル画面（起動画面）の設計仕様を記述する。タイトル画面はアプリケーション起動時に最初に表示されるメイン画面であり、全画面への起点となるハブとして機能する。

### 本画面の処理概要

タイトル画面はゲーム起動時に表示される最初の画面であり、ユーザーに対しメニュー項目を提示し、各機能画面への遷移を提供する。

**業務上の目的・背景**：K-Shoot MANIAはSound Voltex風の音楽ゲームであり、タイトル画面はプレイヤーがゲームを開始する際の最初の接点となる。ジョイスティック初期化・テクスチャキャッシュ読み込み・BGM再生などの初期化処理を行いつつ、メニューによる各画面への遷移を提供することが主な役割である。また、オプション設定画面から戻った際のテクスチャリフレッシュ処理も本画面が担当する。

**画面へのアクセス方法**：アプリケーション起動時に自動的に表示される。また、IRサインイン画面・オプション設定画面・ゲート画面・曲選択画面からESCキーで戻ることで再度表示される。

**主要な操作・処理内容**：
1. メニュー項目の表示と選択（上下キー/ジョイスティックによるカーソル移動）
2. 選択決定（Enterキー/ジョイスティックボタン11）によるIRログイン・オプション設定・ゲート・終了への遷移
3. ESCキーによる終了メニュー項目への移動
4. タイトルBGMの再生制御（フェードアウト含む）
5. ジョイスティック初期化処理
6. コマンドライン引数による直接プレイ（.ksh/.kcoファイル指定時）
7. オプション画面からの復帰時のテクスチャキャッシュリフレッシュ処理

**画面遷移**：
- 遷移先：IRサインイン画面（メニュー0番）、オプション設定画面（メニュー1番）、ゲート画面（メニュー2番）、アプリケーション終了（メニュー3番）
- 遷移元：IRサインイン画面（ESCキー）、オプション設定画面（ESCキー）、ゲート画面（ダイアログ後自動）、曲選択画面（ESCキー）

**権限による表示制御**：特になし。全ユーザーに同一のメニュー項目が表示される。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 1 | タイトル画面 | 主機能 | タイトルBGM再生、ジョイスティック初期化、テクスチャ・画像キャッシュ読み込み、メニュー項目表示を行うタイトル画面の主処理 |
| 7 | シーン遷移管理 | 補助機能 | Enter/Escキー押下によりIRサインイン画面・オプション設定画面・ゲート画面・終了へ遷移する（scene変数によるシーン切替） |
| 58 | キーボード入力 | 補助機能 | 方向キー・Enterキー・Escキーによるメニュー項目選択・決定・キャンセル操作 |
| 59 | ジョイスティック入力 | 補助機能 | JStickSearchIDによるジョイスティック検索・初期化、getjoykeystatによるジョイスティック入力でのメニュー操作 |
| 42 | 音量制御 | 補助機能 | BASS_ChannelSetAttributeによるタイトルBGM・SE再生時のマスターボリューム適用 |
| 98 | config.ini管理 | 補助機能 | 初回起動時のconfig.ini設定値（キーバインド・HiSpeed・画面設定等）の読み込みと反映 |
| 101 | 多言語テキスト管理 | 補助機能 | lang変数による多言語テキスト表示（メニュー項目ラベル等） |
| 130 | BASS Audio Library | 補助機能 | BASS_StreamCreateFile/BASS_SampleLoadによるタイトルBGM・SE音声ファイルの再生制御 |
| 74 | スプラッシュ画面 | 補助機能 | standby.jpgキャッシュ画像によるタイトル画面背景の表示 |
| 2 | 選曲画面 | 遷移先機能 | IRサインイン画面経由で曲選択画面(SCENE_SELECT)へ遷移 |
| 6 | オプション設定画面 | 遷移先機能 | メニュー項目「Option」選択時にオプション設定画面(SCENE_OPTION)へ遷移 |

## 画面種別

メニュー選択画面

## URL/ルーティング

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

## 入出力項目

| 項目名 | 入出力 | データ型 | 説明 |
|--------|--------|----------|------|
| selnow | 内部状態 | int | 現在選択中のメニュー項目インデックス（0:IRログイン, 1:オプション, 2:ゲート, 3:終了） |
| standbyselp | 入力/出力 | int | タイトル画面表示時のデフォルト選択位置。他画面からの復帰時に設定される |
| prev_scene | 入力 | int | 前画面のシーンID。テクスチャリフレッシュ判定やBGM制御に使用 |
| imgrefresh | 入力 | int | テクスチャリフレッシュフラグ（1の場合、全テクスチャを再読み込み） |
| iscmdline | 入力 | int | コマンドライン引数による起動かどうか（1の場合、直接プレイ画面へ遷移） |
| dir_cmdline2 | 入力 | string | コマンドライン引数で指定されたファイルパス |
| titlebgmid | 内部状態 | int | タイトルBGMのBASSチャンネルID |
| mastervol | 入力 | int | マスターボリューム値（0-100） |

## 表示項目

| 項目名 | 表示位置 | 説明 |
|--------|----------|------|
| 背景画像 | 画面全体 | standby.jpg（キャッシュ画像）を背景として描画（buffer 27） |
| メニュー項目 | 画面中央 | standby_item.gifから読み込んだ4つのメニュー項目画像（buffer 20） |
| カーソル | 選択項目上 | standby_cur.gifから読み込んだカーソル画像（buffer 19）。アルファ値をsin波で変動させ点滅表現 |
| フェードイン演算 | 画面全体 | 画面遷移時に500msのフェードインアニメーション |

## イベント仕様

### 1-メニュー項目選択（上下キー）

方向キー上下・ジョイスティック対応キーの入力により、selnow変数をインクリメント/デクリメントする。範囲は0～3にクランプされる。選択変更時にはSE（titleselid）を再生する。カーソル位置はcurpos変数により補間アニメーションで滑らかに移動する。

### 2-メニュー決定（Enterキー）

Enterキーまたはジョイスティックボタン11の押下で、selnow値に応じた画面遷移を実行する。

- **selnow=0（IRログイン）**：500msブラックアウト後、SCENE_IR_SIGN_INへ遷移（行631）。タイトルBGMはフェードアウトせず維持。
- **selnow=1（オプション設定）**：500msブラックアウト後、SCENE_OPTIONへ遷移（行641）。タイトルBGMを即座に解放。
- **selnow=2（ゲート）**：500msブラックアウト後、SCENE_GATEへ遷移（行650）。タイトルBGMを即座に解放。
- **selnow=3（終了）**：800msブラックアウト後、アプリケーション終了（行657）。

決定時にはSE（titleenterid）を再生する。

### 3-ESCキー押下

ESCキー押下時、メニュー選択をselnow=3（終了）に移動する。SE（titleselid）を再生する。

### 4-コマンドライン起動

iscmdline=1の場合、コマンドライン引数のファイル拡張子を判定し、.kcoならコースモード、.kshなら通常モードとして直接SCENE_BEFORE_PLAYへ遷移する（行537, 549）。不正な拡張子の場合はエラーダイアログを表示して終了。

### 5-テクスチャリフレッシュ

prev_scene=SCENE_OPTIONかつimgrefresh=1の場合、全テクスチャを再読み込みする大規模な初期化処理が実行される（行14～561）。画面解像度変更・描画品質変更への対応。

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

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

本画面はデータベースを使用しない（ファイルベースのローカルアプリケーション）。

| 操作（イベント） | 対象ファイル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| 画面初期化 | cache/standby.jpg | SELECT（読み込み） | 背景画像キャッシュの読み込み |
| 画面初期化 | se/title_bgm.ogg | SELECT（読み込み） | タイトルBGMの読み込みと再生 |

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

該当なし（DBレスアーキテクチャ）。

## メッセージ仕様

| メッセージID | 種別 | 表示条件 | メッセージ内容 |
|-------------|------|----------|--------------|
| lang.2.13 | エラー | コマンドライン引数のファイルが不正な拡張子の場合 | 「指定された譜面ファイルが見つかりません。」（多言語対応） |

## 例外処理

| 例外条件 | 処理内容 |
|---------|---------|
| キャッシュ画像不存在 | standby.jpgが存在しない場合、背景なしで描画 |
| コマンドライン引数ファイル不正 | エラーダイアログ表示後、アプリケーション終了 |
| キャッシュ画像サイズ不一致 | 画面解像度とキャッシュサイズが異なる場合、キャッシュを削除して再生成 |

## 備考

- HSP3（Hot Soup Processor 3）で記述されたデスクトップアプリケーション。
- テクスチャキャッシュは画面解像度・描画品質に応じて自動生成・管理される。
- タイトルBGMはIRサインイン画面へ遷移する際には解放せず、IRサインイン画面側でフェードアウト・解放処理を行う。
- カーソル移動のアニメーションは30フレーム補間により滑らかに移動する（行707）。
- カーソルの点滅はsin波（周期150ms）を用いたアルファブレンディングで表現される（行709）。

---

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

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

### 推奨読解順序

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

まず、シーン管理とグローバル変数の定義を理解することが重要である。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | kshootmania.hsp | `kshootmania.hsp` | 行11-18でシーン列挙定数（SCENE_TITLE=0等）が定義されている。scene変数がどの画面を表示するかを制御する |
| 1-2 | kshootmania.hsp | `kshootmania.hsp` | 行21-77で定数定義（mode_on/off、画面サイズ、レーン幅等）を確認 |

**読解のコツ**: HSP3では`#enum`で列挙定数を定義し、`#define`でマクロ定数を定義する。scene変数にSCENE_*定数を代入することで画面遷移が実現される。

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

タイトル画面の主処理関数`start_title`を特定する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | title.hsp | `src/scene/title.hsp` | 行1の`#deffunc start_title`がタイトル画面のエントリーポイント |

**主要処理フロー**:
1. **行1**: `start_title`関数の定義開始
2. **行6-561**: `is_scene_initial_frame=1`の場合の初期化処理（ジョイスティック初期化、テクスチャ読み込み）
3. **行14-561**: `prev_scene=SCENE_OPTION`かつ`imgrefresh=1`の場合の大規模テクスチャリフレッシュ
4. **行530-560**: コマンドライン引数処理
5. **行562-580**: 背景画像・メニュー画像の読み込みとBGM再生開始
6. **行594-744**: メインループ（描画・入力処理・遷移判定）

#### Step 3: メニュー選択・遷移処理を理解する

メインループ内の入力処理と画面遷移ロジックを確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | title.hsp | `src/scene/title.hsp` | 行604-698: キー入力判定とメニュー操作。getesckey()、getkeyマクロ、getjoykeystatによる入力検出 |
| 3-2 | title.hsp | `src/scene/title.hsp` | 行614-662: Enter押下時の分岐。selnow値に応じたscene変数の設定と遷移アニメーション |

**主要処理フロー**:
- **行606**: ESCキー検出。selnow=3（終了）に設定
- **行614**: Enterキー検出条件判定
- **行617-631**: selnow=0: SCENE_IR_SIGN_INへ遷移
- **行635-642**: selnow=1: SCENE_OPTIONへ遷移
- **行643-651**: selnow=2: SCENE_GATEへ遷移
- **行652-658**: selnow=3: アプリケーション終了

#### Step 4: 描画処理を理解する

メインループ内の描画処理を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | title.hsp | `src/scene/title.hsp` | 行595-600: 背景描画（buffer 27からのgcopy） |
| 4-2 | title.hsp | `src/scene/title.hsp` | 行709-716: メニュー項目とカーソルの描画。gmode 5によるアルファブレンディング |
| 4-3 | title.hsp | `src/scene/title.hsp` | 行717-722: フェードインアニメーション（500ms） |

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

```
kshootmania.hsp (メインループ)
    |
    +-- start_title (src/scene/title.hsp:1)
    |       |
    |       +-- JStickSearchID (行7) ... ジョイスティック初期化
    |       +-- *joyinit (行9) ... ジョイスティック設定
    |       +-- テクスチャリフレッシュ (行14-561) ... imgrefresh=1時
    |       |       +-- alCreateImageByFile ... 画像ファイル読み込み
    |       |       +-- alStretchImageToImage ... 画像リサイズ
    |       |       +-- generate_cache_imgs (行519) ... キャッシュ生成
    |       |
    |       +-- BASS_StreamCreateFile (行576) ... タイトルBGM読み込み
    |       +-- BASS_ChannelPlay (行579) ... BGM再生開始
    |       +-- メインループ (行594-744)
    |               +-- *getjoystat (行596) ... ジョイスティック状態取得
    |               +-- getesckey() (行605) ... ESCキー判定
    |               +-- getjoykeystat() (行613) ... ジョイスティックボタン判定
    |               +-- blackout (行630,639,648,656) ... 画面遷移アニメーション
    |               +-- *volactive (行737) ... ボリューム制御
    |
    +-- picload_zoom_cache (行768) ... キャッシュ付き画像読み込みユーティリティ
```

### データフロー図

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

キーボード入力 ---------> getkey / getesckey() ---------> selnow (メニュー選択状態)
ジョイスティック -------> getjoykeystat() ------------->
                                |
                                v
                        selnow値の判定
                                |
                    +-----------+-----------+
                    |           |           |
                    v           v           v
              scene=         scene=       scene=
              SCENE_IR_      SCENE_      SCENE_
              SIGN_IN        OPTION      GATE
              (行631)        (行641)     (行650)

se/title_bgm.ogg --> BASS_StreamCreateFile --> titlebgmid --> BASS_ChannelPlay
imgs/standby.jpg --> imgbufload_bg ----------> buffer 27 ----> gcopy (背景描画)
imgs/standby_cur.gif -> picload -------------> buffer 19 ----> gcopy (カーソル描画)
imgs/standby_item.gif -> picload ------------> buffer 20 ----> gcopy (メニュー描画)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| title.hsp | `src/scene/title.hsp` | ソース | タイトル画面の主処理（start_title関数、テクスチャリフレッシュ、メニュー操作） |
| kshootmania.hsp | `kshootmania.hsp` | ソース | メインエントリーポイント。シーン定数定義（行11-18）、メインループでのシーン分岐 |
| standby.jpg | `imgs/standby.jpg`（キャッシュ: `cache/standby.jpg`） | リソース | タイトル画面背景画像 |
| standby_cur.gif | `imgs/standby_cur.gif` | リソース | メニューカーソル画像 |
| standby_item.gif | `imgs/standby_item.gif` | リソース | メニュー項目テキスト画像 |
| title_bgm.ogg | `se/title_bgm.ogg` | リソース | タイトルBGM音声ファイル |
| config.ini | `config.ini` | 設定 | キーバインド・HiSpeed・画面設定等の設定ファイル |
