# 画面設計書 2-IRサインイン画面

## 概要

本ドキュメントは、K-Shoot MANIA のIRサインイン画面の設計仕様を記述する。IR（Internet Ranking）オンラインシステムへのログイン画面であり、ユーザー認証を行った後に曲選択画面へ遷移する。

### 本画面の処理概要

IRサインイン画面は、オンラインランキングシステム（Internet Ranking）へのログインまたはスキップを選択する画面である。

**業務上の目的・背景**：K-Shoot MANIAはオンラインランキング機能（IR）を持っており、プレイスコアをオンラインで共有・比較できる。本画面はIRへのログイン認証を行うためのインターフェースを提供する。ログインせずにスキップすることも可能であり、ローカルプレイのみの利用にも対応している。

**画面へのアクセス方法**：タイトル画面でメニュー項目0番（IRログイン）を選択してEnterキーを押下することで遷移する。

**主要な操作・処理内容**：
1. IRサインイン画像（ir_signin.png）の中央表示
2. 上下キーまたはジョイスティックによるログイン/スキップの選択（ir_selnow変数、0:ログイン、1:スキップ）
3. Enterキー押下時のログイン実行またはスキップ処理
4. ログイン選択時：ir_login関数によるユーザー認証処理（session_id, ksm_id設定）
5. スキップ選択時：session_id=""、ksm_id=0にリセット
6. タイトルBGMのフェードアウトと解放
7. ESCキーによるタイトル画面への復帰

**画面遷移**：
- 遷移先：曲選択画面（SCENE_SELECT、ログイン成功またはスキップ後）、タイトル画面（SCENE_TITLE、ESCキー）
- 遷移元：タイトル画面（メニュー0番選択）

**権限による表示制御**：特になし。ログイン/スキップの2択が全ユーザーに表示される。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 7 | シーン遷移管理 | 主機能 | IRログイン選択またはスキップ後にSCENE_SELECT（曲選択画面）へ遷移、Esc押下でSCENE_TITLE（タイトル画面）へ戻る |
| 95 | IRハッシュ計算 | 補助機能 | IRログイン時のユーザー認証処理でsession_id・ksm_idを設定 |
| 58 | キーボード入力 | 補助機能 | 方向キーとEnter/Escキーによるログイン/スキップの選択操作 |
| 59 | ジョイスティック入力 | 補助機能 | getjoykeystatによるジョイスティック入力でのIRサインイン操作 |
| 42 | 音量制御 | 補助機能 | BASS_ChannelSetAttributeによるタイトルBGMフェードアウト・SE再生時のマスターボリューム適用 |
| 130 | BASS Audio Library | 補助機能 | BASS_ChannelSlideAttribute/BASS_StreamFreeによるタイトルBGMのフェードアウトと解放 |
| 2 | 選曲画面 | 遷移先機能 | ログインまたはスキップ後に曲選択画面(SCENE_SELECT)へ遷移 |
| 1 | タイトル画面 | 遷移先機能 | Escキー押下でタイトル画面(SCENE_TITLE)へ戻る |

## 画面種別

選択画面（ログイン/スキップの2択選択）

## URL/ルーティング

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

## 入出力項目

| 項目名 | 入出力 | データ型 | 説明 |
|--------|--------|----------|------|
| ir_selnow | 内部状態 | int | 現在選択中の項目（0:ログイン、1:スキップ） |
| session_id | 出力 | string | IRログイン成功時に設定されるセッションID。スキップ時は空文字 |
| ksm_id | 出力 | int | IRログイン成功時に設定されるユーザーID。スキップ時は0 |
| titlebgmid | 入力 | int | タイトルBGMのBASSチャンネルID（フェードアウト・解放に使用） |
| mastervol | 入力 | int | マスターボリューム値（0-100） |
| standbyselp | 出力 | int | タイトル画面復帰時のデフォルト選択位置（ESC時に0を設定） |

## 表示項目

| 項目名 | 表示位置 | 説明 |
|--------|----------|------|
| 背景画像 | 画面全体 | buffer 29（bg2.jpg）を背景として描画 |
| IRサインイン画像 | 画面中央 | IMG_IR_SIGNIN（ir_signin.png）を画面中央に表示。サイズはgetsize(480) x getsize(320) |
| カーソル画像 | 選択項目上 | IMG_IR_SIGNIN_CURSOR（ir_signin_cursor.png）をir_selnow値に応じた位置に表示。sin波によるアルファブレンディングで点滅 |
| フェードイン演算 | 画面全体 | 250msのフェードインアニメーション |

## イベント仕様

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

方向キー上下・ジョイスティック対応キーの入力により、ir_selnow変数を切り替える。下キー押下でir_selnow=1（スキップ）、上キー押下でir_selnow=0（ログイン）に設定される。選択変更時にSE（titleselid）を再生する。

### 2-ログイン/スキップ決定（Enterキー）

Enterキーまたはジョイスティックボタン11の押下で処理を実行する。

- **ir_selnow=0（ログイン）**：ir_login関数を呼び出しIR認証処理を実行。session_idとksm_idが設定される（行1143-1144）。
- **ir_selnow=1（スキップ）**：session_id=""、ksm_id=0にリセット（行1146-1147）。

決定後、共通処理として：
1. タイトルBGMをマスターボリュームに設定後、100msでフェードアウト（行1138-1139）
2. 決定SE（titleenterid）を再生（行1140-1142）
3. 500msブラックアウト（行1150）
4. SCENE_SELECTへ遷移（行1154）
5. タイトルBGMのストリーム解放（行1155）

### 3-ESCキーによる復帰

ESCキー押下時、prev_scene=SCENE_IR_SIGN_INを設定し、SCENE_TITLEへ遷移する（行1126-1128）。standbyselp=0に設定し、500msブラックアウトを実行。タイトルBGMは解放しない（コメントアウトされている行1130）。

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

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

| 操作（イベント） | 対象 | 操作種別 | 概要 |
|----------------|------|---------|------|
| ログイン決定 | IRサーバー | 通信 | ir_login関数によるHTTP通信でIRサーバーに認証要求 |

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

該当なし（ローカルDBは使用しない。IRサーバーとの通信のみ）。

## メッセージ仕様

本画面では明示的なメッセージ表示は行われない。ログイン結果はsession_id/ksm_idの設定状態で判断される。

## 例外処理

| 例外条件 | 処理内容 |
|---------|---------|
| IRサーバー接続失敗 | ir_login関数内で処理。session_idが空のまま曲選択画面へ遷移（オフラインモード） |

## 備考

- IRサインイン画面はkshootmania.hspのメインループ内にインラインで記述されている（行1091-1190）。独立したファイルではない。
- カーソル画像のアルファ値は `0.3 + 0.7*(sin(d3timer()/150)+1.0)/2` で計算され、0.3～1.0の範囲で点滅する（行1112）。
- フェードインは250msで完了する（タイトル画面の500msよりも短い）（行1116-1121）。
- タイトルBGMはタイトル画面から引き継がれ、Enter決定時にのみフェードアウト・解放される。ESC復帰時は維持される。

---

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

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

### 推奨読解順序

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

IR関連のグローバル変数を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | kshootmania.hsp | `kshootmania.hsp` | 行11でSCENE_IR_SIGN_IN定数が定義されている |
| 1-2 | kshootmania.hsp | `kshootmania.hsp` | ir_selnow, session_id, ksm_id のグローバル変数がIR認証状態を管理する |

**読解のコツ**: IRサインイン画面はkshootmania.hspのcase文内にインラインで記述されており、独立ファイルではない点に注意。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | kshootmania.hsp | `kshootmania.hsp` | 行1091の`case SCENE_IR_SIGN_IN`がエントリーポイント |

**主要処理フロー**:
1. **行1092-1098**: 初期化（selnow, curpos, kp1/kp2設定）
2. **行1099-**: メインループ開始
3. **行1107-1114**: 描画処理（背景、IR画像、カーソル描画）
4. **行1123-1190**: 入力処理（ESCキー、Enterキー、上下キー）

#### Step 3: IR認証処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | kshootmania.hsp | `kshootmania.hsp` | 行1143-1148: ir_selnow値による分岐。ir_login関数呼び出しまたはスキップ処理 |

**主要処理フロー**:
- **行1143**: ir_selnow=0（ログイン）の場合、ir_login関数を呼び出し
- **行1146-1147**: ir_selnow=1（スキップ）の場合、session_id=""、ksm_id=0

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

```
kshootmania.hsp メインループ
    |
    +-- case SCENE_IR_SIGN_IN (行1091)
            |
            +-- *getjoystat (行1101) ... ジョイスティック状態取得
            +-- alCopyImageToScreen IMG_IR_SIGNIN (行1111) ... IR画像描画
            +-- alCopyImageToScreen IMG_IR_SIGNIN_CURSOR (行1113) ... カーソル描画
            +-- getesckey() (行1124) ... ESCキー判定
            |       +-- scene=SCENE_TITLE (行1128)
            +-- Enterキー判定 (行1135-1137)
            |       +-- ir_login (行1144) ... IR認証処理
            |       +-- session_id/ksm_id設定 (行1146-1147)
            |       +-- BASS_ChannelSlideAttribute (行1139) ... BGMフェードアウト
            |       +-- BASS_StreamFree (行1155) ... BGM解放
            |       +-- scene=SCENE_SELECT (行1154)
            +-- 上下キー判定 (行1158-1190) ... ir_selnow切替
```

### データフロー図

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

キーボード上下 --------> ir_selnow切替 -----------------> 画面表示更新
ジョイスティック ------> getjoykeystat() ------------->

Enterキー ------------> ir_selnow判定
                            |
                  +---------+---------+
                  |                   |
                  v                   v
            ir_login()          session_id=""
            (認証処理)          ksm_id=0
                  |                   |
                  v                   v
            session_id          scene=SCENE_SELECT
            ksm_id設定

ESCキー --------------> scene=SCENE_TITLE
                        prev_scene=SCENE_IR_SIGN_IN
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| kshootmania.hsp | `kshootmania.hsp` | ソース | IRサインイン画面の全処理（行1091-1190）。メインループ内にインライン記述 |
| ir_signin.png | `imgs/ir_signin.png` | リソース | IRサインイン画面の背景画像（960x640、IMG_IR_SIGNIN） |
| ir_signin_cursor.png | `imgs/ir_signin_cursor.png` | リソース | 選択カーソル画像（80x80、IMG_IR_SIGNIN_CURSOR） |
| bg2.jpg | `imgs/bg2.jpg` | リソース | 背景画像（buffer 29に読み込み済み） |
