# 機能設計書 113-テストプレイ

## 概要

本ドキュメントは、K-Shoot MANIA譜面エディタにおけるテストプレイ機能の設計を記述する。カーソル位置からの通常/AUTOテストプレイ起動機能を提供する。

### 本機能の処理概要

譜面エディタで制作中の譜面を保存した後、外部プロセスとしてkshootmania.exeを起動してゲームプレイを実行する機能である。

**業務上の目的・背景**：譜面制作者がエディタ内のプレビュー再生では確認しきれないゲームプレイ体験(判定、スコア、ゲージ等)を確認するために、実際のゲーム本体で譜面をテストプレイできるようにする。

**機能の利用シーン**：譜面制作の途中・完了時にF5/F6/F11/F12キーまたは再生メニューからテストプレイを起動する。特定のセクションを確認したい場合はカーソル位置から開始するモードを使用する。

**主要な処理内容**：
1. 通常テストプレイ(CMD_PLAY_TESTPLAY): 譜面先頭から通常プレイでkshootmania.exeを起動
2. AUTOテストプレイ(CMD_PLAY_TESTPLAY_AUTO): 譜面先頭からAUTOプレイで起動
3. カーソル位置テストプレイ(CMD_PLAY_TESTPLAY_CURSOR): カーソル位置から通常プレイで起動
4. カーソル位置AUTOテストプレイ(CMD_PLAY_TESTPLAY_AUTO_CURSOR): カーソル位置からAUTOプレイで起動
5. Shift押下でHARDゲージ、Ctrl押下でEASYゲージオプション付加

**関連システム・外部連携**：kshootmania.exe(ゲーム本体)をexec命令で外部プロセスとして起動する。

**権限による制御**：権限による制御はない。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | 譜面エディタ | 主画面 | 再生メニュー > テストプレイ(F5/F6/F11/F12) |

## 機能種別

外部プロセス起動

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| cmd | int | Yes | テストプレイコマンドID | CMD_PLAY_TESTPLAY/TESTPLAY_AUTO/TESTPLAY_CURSOR/TESTPLAY_AUTO_CURSOR |
| fname | str | Yes | 現在編集中の譜面ファイルパス | 空文字でないこと |
| cnowf | int | No | カーソル位置(カーソル位置テストプレイ時) | - |
| shift_key | int | No | Shiftキー押下状態(HARDゲージ) | 0 or 1 |
| ctrl_key | int | No | Ctrlキー押下状態(EASYゲージ) | 0 or 1 |

### 入力データソース

- メニュー操作(再生メニュー > テストプレイ)
- キーボードショートカット(F5/F6/F11/F12)
- 修飾キー(Shift/Ctrl)

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| (外部プロセス) | - | kshootmania.exeプロセスの起動 |

### 出力先

- 外部プロセス(kshootmania.exe)

## 処理フロー

### 処理シーケンス

```
1. ユーザーがF5/F6/F11/F12キーまたはメニューでテストプレイを選択
   └─ CMD_PLAY_TESTPLAY/TESTPLAY_AUTO/TESTPLAY_CURSOR/TESTPLAY_AUTO_CURSOR
2. 修飾キーの状態を取得
   └─ Shift → "-hard"、Ctrl → "-easy"オプション
3. 譜面ファイルが保存済みか確認
   └─ fname=""またはe=1(未保存)の場合はダイアログ表示して中断
4. kshootmania.exeの存在確認
   └─ カレントディレクトリまたは親ディレクトリを検索
5. exec命令でkshootmania.exeを起動
   └─ コマンドライン引数に譜面パス・-auto・-from・-hard/-easyを付加
```

### フローチャート

```mermaid
flowchart TD
    A[テストプレイコマンド] --> B[修飾キー状態取得]
    B --> C{譜面が保存済み?}
    C -->|No| D[保存要求ダイアログ表示]
    D --> E[処理中断]
    C -->|Yes| F[dir_defaultに移動]
    F --> G{kshootmania.exe存在?}
    G -->|Yes| H[exec kshootmania.exe]
    G -->|No| I{../kshootmania.exe存在?}
    I -->|Yes| J[exec ../kshootmania.exe]
    I -->|No| K[処理終了]
    H --> L[テストプレイ開始]
    J --> L
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-113-01 | 保存必須 | テストプレイ前に譜面が保存されている必要がある | 常時 |
| BR-113-02 | HARDゲージ | Shift押下時に"-hard"オプションを付加する | Shift_key=1 |
| BR-113-03 | EASYゲージ | Ctrl押下時に"-easy"オプションを付加する | Ctrl_key=1 |
| BR-113-04 | AUTO再生 | AUTOモード時に"-auto"オプションを付加する | CMD_PLAY_TESTPLAY_AUTO/AUTO_CURSOR |
| BR-113-05 | カーソル位置 | カーソル位置モード時に"-from N"(小節番号)を付加する | CMD_PLAY_TESTPLAY_CURSOR/AUTO_CURSOR |
| BR-113-06 | exe検索 | カレントディレクトリ→親ディレクトリの順でexeを検索する | 常時 |

### 計算ロジック

- カーソル位置から小節番号への変換: `c2b(cnowf)` 関数で変換(8549行目)

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

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

データベース操作はない。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | 未保存エラー | fname=""またはe=1 | ダイアログで「譜面ファイルを保存してください」と通知 |
| - | exe不在 | kshootmania.exeが見つからない | 処理を中断(エラーメッセージなし) |

### リトライ仕様

リトライ処理はない。

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

トランザクション管理はない。

## パフォーマンス要件

外部プロセス起動のため、即座に制御が戻る。

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

- exec命令で外部プロセスを起動するため、ファイルパスにインジェクション等のリスクはあるが、HSPのexec命令はシェル経由ではないため低リスク

## 備考

- テストプレイ中もエディタは操作可能(非同期起動)
- ツールバーにテストプレイアイコン(21番)とAUTOテストプレイアイコン(22番)が表示される
- F5: 通常テストプレイ、F11: AUTOテストプレイ、F6: カーソル位置テストプレイ、F12: カーソル位置AUTOテストプレイ

---

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

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

### 推奨読解順序

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

テストプレイに関わる変数は少数である。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | kshooteditor.hsp | `kshooteditor.hsp` | **146-149行目**: CMD_PLAY_TESTPLAY~CMD_PLAY_TESTPLAY_AUTO_CURSORのenum定義 |

**読解のコツ**: テストプレイの4種類のコマンドは、通常/AUTO、先頭/カーソル位置の組み合わせで構成される。

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

メニュー登録とコマンドハンドラを確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | kshooteditor.hsp | `kshooteditor.hsp` | **788-791行目**: メニュー項目追加(テストプレイ4種) |
| 2-2 | kshooteditor.hsp | `kshooteditor.hsp` | **10052-10064行目**: F5/F6/F11/F12キーによるコマンド発行 |

**主要処理フロー**:
1. **788行目**: `addmenu hplaymenu, ... CMD_PLAY_TESTPLAY` - テストプレイメニュー
2. **789行目**: `addmenu hplaymenu, ... CMD_PLAY_TESTPLAY_AUTO` - AUTOテストプレイメニュー
3. **790行目**: `addmenu hplaymenu, ... CMD_PLAY_TESTPLAY_CURSOR` - カーソル位置テストプレイ
4. **791行目**: `addmenu hplaymenu, ... CMD_PLAY_TESTPLAY_AUTO_CURSOR` - カーソル位置AUTOテストプレイ

#### Step 3: テストプレイ実行処理を理解する

コマンドハンドラ内のテストプレイ処理を詳細に追う。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | kshooteditor.hsp | `kshooteditor.hsp` | **8489-8511行目**: CMD_PLAY_TESTPLAY処理 |
| 3-2 | kshooteditor.hsp | `kshooteditor.hsp` | **8512-8534行目**: CMD_PLAY_TESTPLAY_AUTO処理 |
| 3-3 | kshooteditor.hsp | `kshooteditor.hsp` | **8535-8557行目**: CMD_PLAY_TESTPLAY_CURSOR処理 |
| 3-4 | kshooteditor.hsp | `kshooteditor.hsp` | **8558-8581行目**: CMD_PLAY_TESTPLAY_AUTO_CURSOR処理 |

**主要処理フロー**:
- **8490-8491行目**: `getkey shift_key,16` / `getkey ctrl_key,17` - 修飾キー取得
- **8493行目**: `if(shift_key=1):stat1=" -hard"` - HARDゲージオプション
- **8494行目**: `if(ctrl_key=1):stat1=" -easy"` - EASYゲージオプション
- **8496行目**: ファイル未保存チェック → ダイアログ表示
- **8503行目**: `exec "kshootmania.exe \""+fname+"\""+stat1` - exe起動
- **8549行目**: `exec "kshootmania.exe \""+fname+"\""+stat1+" -from "+c2b(cnowf)` - カーソル位置指定付き起動

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

```
*OnCommand (2191行目)
    |
    +-- CMD_PLAY_TESTPLAY (8489行目)
    |       +-- getkey (修飾キー取得)
    |       +-- ファイル存在確認 (fname, kshootmania.exe)
    |       +-- exec "kshootmania.exe ..."
    |
    +-- CMD_PLAY_TESTPLAY_AUTO (8512行目)
    |       +-- 同上 + "-auto"オプション
    |
    +-- CMD_PLAY_TESTPLAY_CURSOR (8535行目)
    |       +-- 同上 + "-from N"オプション
    |
    +-- CMD_PLAY_TESTPLAY_AUTO_CURSOR (8558行目)
            +-- 同上 + "-auto -from N"オプション
```

### データフロー図

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

コマンドID ----------+
修飾キー状態 --------+--> コマンドライン構築 -----------> exec kshootmania.exe
ファイルパス(fname) -+    +-- -auto (AUTOモード時)        外部プロセス起動
カーソル位置(cnowf) -+    +-- -from N (カーソル位置時)
                          +-- -hard/-easy (修飾キー時)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| kshooteditor.hsp | `kshooteditor.hsp` | ソース | エディタ本体。テストプレイコマンドハンドラを含む |
| kshootmania.exe | `kshootmania.exe` | 実行ファイル | テストプレイ対象のゲーム本体 |
