# 機能設計書 68-リアルタイムUI表示

## 概要

本ドキュメントは、K-Shoot MANIA のプレイ画面におけるリアルタイムUI表示機能の設計を記述する。コンボ数・スコア・ゲージバー・FPS・タイミング調整値・楽曲情報・HiSpeed値をプレイ中にリアルタイムで表示する。

### 本機能の処理概要

**業務上の目的・背景**：プレイヤーがゲーム進行状況をリアルタイムで把握するため、スコア・ゲージ・各種パラメータを常時表示する必要がある。これらの情報はプレイの戦略（ゲージ管理、HiSpeed調整等）に直接影響する。

**機能の利用シーン**：ゲームプレイ画面（SCENE_PLAY）の毎フレーム描画処理として、drawFrame 関数の後半で実行される。

**主要な処理内容**：
1. 楽曲情報パネル表示（ジャケット画像、曲名、BPM、HiSpeed値、再生進捗バー）
2. スコア表示（8桁0埋め、最大10,000,000）
3. FPS表示（d3getfps による実測値）
4. タイミング調整値表示（sync 変数、±符号付き）
5. ゲージ（エフェクティブレート）表示
   - ゲージ外枠の描画（ゲージタイプに応じた画像切替）
   - ゲージ内部（縦棒）の描画（ゲージ値に応じた高さ変化）
   - ゲージエフェクト（パターンアニメーション）
   - ゲージパーセンテージ数値表示
6. プレイ結果表示（プレイ終了後のクリア/フルコンボ/パーフェクト表示）
7. HARDゲージ落下時のフェードアウト演出
8. プレイ開始時のフェードイン演出
9. 動画再生時の外枠描画

**関連システム・外部連携**：HGIMG4（hgzoom/hgcopy/hgzoom_a/hgcopy_a）によるテクスチャ描画。d3timer / d3getfps によるタイマー・FPS取得。

**権限による制御**：output 変数が 0 の場合のみ FPS・タイミング調整値を表示（スクリーンショット出力モードでは非表示）。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 5 | ゲームプレイ画面 | 主画面 | play_draw_frame.hsp によるコンボ数・スコア・ゲージバー・FPS・タイミング調整値の UI 表示 |

## 機能種別

描画処理 / UI表示

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| totalscore_disp | int | Yes | 表示用スコア（アニメーション付き） | 0-10,000,000 |
| chainnow | int | Yes | 現在のCOMBO数 | 0以上 |
| gauge | int | Yes | 現在のゲージ値 | - |
| gaugemax | int | Yes | ゲージ最大値 | - |
| effratetype | int | Yes | ゲージタイプ（<=0:通常, >0:HARD） | - |
| bpm | int | Yes | 現在のBPM（1000倍整数） | - |
| hsr/hso/hsc/hsm/hsa | int | Yes | 各HiSpeed方式の値 | - |
| sync | double | Yes | タイミング調整値（ms） | - |
| fps | int | Yes | 現在のFPS | - |
| output | int | Yes | スクリーンショット出力モード（0=通常） | - |

### 入力データソース

play_game_logic.hsp で計算されるスコア・ゲージ値。d3getfps によるFPS。

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| 画面描画 | テクスチャ | HGIMG4 経由のテクスチャ描画 |

### 出力先

画面バッファへの直接描画（hgzoom / hgcopy / hgzoom_a / hgcopy_a）。

## 処理フロー

### 処理シーケンス

```
1. 楽曲情報パネル
   1-1. 楽曲ラベル画像の表示（tex_minfo_label）
   1-2. ジャケット画像の表示（tex_jacket, 38.5px角）
   1-3. 楽曲詳細情報の表示（tex_minfo_detail）
   1-4. BPM値の数値画像表示（小数点対応）
   1-5. HiSpeed値の表示（方式に応じた接頭辞: x/C/m/a/数値）
   1-6. 実効スクロール速度の表示
   1-7. 再生進捗カーソルの表示（tex_minfo_cur）
2. 動画再生枠（cmov=0 かつ vmov=1 かつ output=0 の場合）
3. スコア表示
   3-1. "SCORE" ヘッダ画像（tex_score_header, 240x48）
   3-2. 8桁の数値画像表示（tex_result_scorenum, 24x24px/桁）
4. FPS表示（output=0 の場合のみ）
   4-1. FPS数値の右詰め表示
   4-2. "FPS" ラベル画像
5. タイミング調整値表示（sync!=0 かつ output=0 の場合のみ）
   5-1. 調整値の数値表示
   5-2. "ms" ラベル
   5-3. ±符号表示
   5-4. "TIMING ADJUST" ラベル
6. ゲージ外枠表示
   6-1. ゲージタイプ・クリア状態に応じた画像選択
7. ゲージ内部表示
   7-1. ゲージ値に比例した縦棒の高さ計算
   7-2. ゲージタイプ・クリア状態に応じた色切替
8. ゲージエフェクト（パターンアニメーション）
   8-1. BPM連動のUVスクロール
9. ゲージパーセンテージ表示
   9-1. パーセンテージ数値と % 記号の表示
10. プレイ結果表示（mendt!=-1 の場合）
    10-1. HARDゲージ落下: 赤フラッシュ
    10-2. クリア結果画像: FAILED/CLEAR/FULLCOMBO/PERFECT（800ms後にフェードイン）
    10-3. プレイ終了後のフェードアウト（1000ms～2400ms）
11. プレイ開始時のフェードイン（t<500ms）
```

### フローチャート

```mermaid
flowchart TD
    A[drawFrame 後半] --> B[楽曲情報パネル描画]
    B --> C[スコア表示]
    C --> D{output=0?}
    D -->|Yes| E[FPS表示]
    D -->|No| G[ゲージ外枠描画]
    E --> F{sync!=0?}
    F -->|Yes| F2[タイミング調整値表示]
    F -->|No| G
    F2 --> G
    G --> H[ゲージ内部描画]
    H --> I[ゲージエフェクト]
    I --> J[ゲージパーセンテージ]
    J --> K{mendt!=-1?}
    K -->|Yes| L[プレイ結果表示/フェード]
    K -->|No| M[return]
    L --> M
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-68-1 | スコア8桁表示 | 先頭0埋めで8桁表示（最大10,000,000） | 常時 |
| BR-68-2 | ゲージ色分け | 通常ゲージ70%以上・HARDゲージ30%以上で色が変化 | 常時 |
| BR-68-3 | FPS非表示条件 | output!=0（スクリーンショットモード）の場合はFPS非表示 | output変数 |
| BR-68-4 | HARDゲージ落下演出 | gauge/1000<=0 で赤フラッシュ表示 | HARDゲージモード |
| BR-68-5 | クリア結果表示 | 800ms後にフェードイン、stat2で結果判定（0=FAILED, 1=CLEAR, 2=FC, 3=PERFECT） | mendt!=-1 |
| BR-68-6 | フェードアウト遅延 | mendtype=0 かつ通常ゲージの場合、追加2400msの遅延あり | プレイ終了時 |

### 計算ロジック

**ゲージパーセンテージ計算**:
- 通常ゲージ: `stat1 = 100 * gauge / gaugemax`
- HARDゲージ: `stat1 = gauge / 1000`（負の場合は0）

**BPM表示値の変換**:
```
stat1 = str(bpm)  // 1000倍整数
stat1 = strmid(stat1, 0, strlen-3) + "." + strmid(stat1, -1, 3)
stat1 = strtrim(stat1, 2, '0')  // 末尾0除去
stat1 = strtrim(stat1, 2, '.')  // 末尾.除去
```

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

該当なし。

## エラー処理

### エラーケース一覧

該当なし。描画処理のみ。

### リトライ仕様

該当なし。

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

該当なし。

## パフォーマンス要件

毎フレーム実行される描画処理。テクスチャのhgzoom/hgcopy呼び出しは軽量で、パフォーマンス上の問題はない。

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

該当なし。

## 備考

- errate1 変数はゲージ画像のスケーリング係数で、画面解像度に応じたゲージサイズの調整に使用される
- erxsh1, erysh1 はゲージの画面上の基準位置（X, Y）
- adjmode=1 の場合、ゲージは強制的に0にリセットされる（1073行目）
- tex_num2 配列は [0]=白数字, [1]=灰色数字 の2色セットで構成される

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | play_graphics.hsp | `src/scene/play/play_graphics.hsp` | **1-48行目**: loadUIGraphics 関数。UI用テクスチャの読み込み（tex_laser_p, tex_score_header, tex_num2, tex_er 等） |

**読解のコツ**: tex_ で始まる変数はテクスチャハンドル。texload2 で画像ファイルからロードされ、hgcopy/hgzoom で画面に描画される。_a 付きの描画関数（hgcopy_a, hgzoom_a）は透過描画対応。

#### Step 2: 楽曲情報パネルを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | play_draw_frame.hsp | `src/scene/play/play_draw_frame.hsp` | **919-1018行目**: 楽曲情報パネル（ラベル、ジャケット、BPM、HiSpeed、進捗カーソル） |

**主要処理フロー**:
1. **921-922行目**: 楽曲ラベルとジャケット画像の描画
2. **927-936行目**: BPM値の数値画像表示（小数点対応）
3. **937-983行目**: HiSpeed値の表示（方式に応じた接頭辞付き）
4. **984-1016行目**: 実効スクロール速度の表示
5. **1017-1018行目**: 再生進捗カーソル

#### Step 3: スコア・FPS・タイミング調整値を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | play_draw_frame.hsp | `src/scene/play/play_draw_frame.hsp` | **1025-1037行目**: スコア表示（8桁0埋め） |
| 3-2 | play_draw_frame.hsp | `src/scene/play/play_draw_frame.hsp` | **1038-1070行目**: FPS・タイミング調整値の表示 |

#### Step 4: ゲージ表示を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | play_draw_frame.hsp | `src/scene/play/play_draw_frame.hsp` | **1075-1106行目**: ゲージ外枠・内部・エフェクト・パーセンテージの描画 |

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

```
drawFrame
    |
    +-- [楽曲情報]
    |       +-- hgcopy (ラベル/ジャケット)
    |       +-- hgcopy_a (BPM/HiSpeed 数値)
    |
    +-- [スコア]
    |       +-- hgzoom_a (ヘッダ)
    |       +-- hgcopy_a (数値 x8)
    |
    +-- [FPS/タイミング]
    |       +-- d3getfps()
    |       +-- hgcopy_a (数値/ラベル/符号)
    |
    +-- [ゲージ]
    |       +-- hgcopy_a (外枠/内部/エフェクト/パーセンテージ)
    |       +-- hgzoom_a (パーセンテージ数値)
    |
    +-- [プレイ結果]
            +-- hgrotate (結果画像)
            +-- hgrect (フェード効果)
```

### データフロー図

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

totalscore_disp    ───>    ┌──────────────────────┐
gauge/gaugemax     ───>    |  drawFrame (UI部)    |
bpm                ───>    |  ├─ 楽曲情報パネル   |
hsr/hso/hsc/hsm/hsa───>    |  ├─ スコア 8桁      |       画面描画
sync               ───>    |  ├─ FPS 表示        |  ──>  (hgcopy/hgzoom)
d3getfps()         ───>    |  ├─ タイミング調整   |
effratetype        ───>    |  └─ ゲージ表示       |
mendt              ───>    |  └─ プレイ結果       |
                            └──────────────────────┘
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| play_draw_frame.hsp | `src/scene/play/play_draw_frame.hsp` | ソース | リアルタイムUI表示（919-1164行目） |
| play_graphics.hsp | `src/scene/play/play_graphics.hsp` | ソース | UI用テクスチャのロード（1-48行目） |
| play_game_logic.hsp | `src/scene/play/play_game_logic.hsp` | ソース | totalscore_disp, gauge 等の計算 |
| cache/ | `cache/` | リソース | UI用キャッシュ画像群 |
| imgs/ | `imgs/` | リソース | UI用リソース画像群 |
