# 機能設計書 116-曲設定ダイアログ

## 概要

本ドキュメントは、K-Shoot MANIA譜面エディタにおける曲設定ダイアログ機能の設計を記述する。楽曲メタデータ(タイトル/アーティスト/エフェクター/BPM等)を編集するダイアログ機能を提供する。

### 本機能の処理概要

譜面ファイルに紐づく楽曲メタデータを編集するためのダイアログを表示する機能である。基本設定(CMD_EDIT_SONGSETTINGS)と詳細設定(CMD_EDIT_SONGSETTINGS2)の2種類のダイアログを提供する。

**業務上の目的・背景**：KSH譜面ファイルにはノートデータだけでなく、楽曲のタイトル・アーティスト名・BPM・背景設定等のメタデータが含まれる。これらのメタデータを直感的に編集するためのGUIダイアログを提供する。

**機能の利用シーン**：新規譜面作成時に基本情報を入力する場面、既存譜面のメタデータを修正する場面で利用される。Ctrl+Tで基本設定、Ctrl+Shift+Tで詳細設定のダイアログを開く。

**主要な処理内容**：
1. 基本設定ダイアログ(CMD_EDIT_SONGSETTINGS): タイトル、アーティスト、エフェクター、ジャケット、イラストレーター、難易度、レベル、BPM、音楽ファイル、音量、タイミング、プレビュー開始/長さ、背景、前面レイヤーの15項目を編集
2. 詳細設定ダイアログ(CMD_EDIT_SONGSETTINGS2): 楽曲情報、HiSpeed基準BPM、自動アナログ音量、レーザーエフェクト遅延、TOTAL値、アイコン画像、KSHフォーマットバージョンの7項目を編集
3. 入力値の妥当性チェックと反映
4. 変更がある場合は編集フラグ(e)を立てて描画更新

**関連システム・外部連携**：外部システムとの連携はない。_input関数によるカスタムダイアログUIを使用する。

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

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | 譜面エディタ | 主画面 | 編集メニュー > 曲設定(Ctrl+T/Ctrl+Shift+T) |

## 機能種別

データ編集 / ダイアログUI

## 入力仕様

### 入力パラメータ(基本設定)

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| csongtitle | str | No | 曲タイトル(title) | - |
| csongartist | str | No | アーティスト名(artist) | - |
| csongeffect | str | No | エフェクター名(effect) | - |
| csongjacket | str | No | ジャケット画像ファイル名(jacket) | - |
| csongillustrator | str | No | イラストレーター名(illustrator) | - |
| csongdifficulty | int | No | 難易度(0-3: Light/Challenge/Extended/Infinite) | 選択肢から選択 |
| csonglevel | int | No | レベル(1-20) | 1-20の範囲 |
| bpml.0.1 | int | No | BPM(ミリ単位) | 正の値、65536未満 |
| csongfile | str | No | 音楽ファイル名(m) | - |
| csongvol | int | No | 楽曲音量(%) | 0以上 |
| offset | int | No | 先頭タイミング(msec) | - |
| poffset | int | No | プレビュー開始位置(msec) | - |
| plength | int | No | プレビュー長さ(msec) | - |
| bgname | str | No | 背景名(bg) | 定義済み名称 |
| bgname_l | str | No | 前面レイヤー名(layer) | 定義済み名称 |

### 入力パラメータ(詳細設定)

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| csonginfo | str | No | 楽曲情報(information) | - |
| csongoftbpm | int | No | HiSpeed基準BPM(ミリ単位) | 0以上、65536000未満 |
| disableautoanvol | int | No | 自動アナログ音量制御(0:有効/1:無効) | - |
| laserdelay1 | int | No | LASERエフェクト遅延(msec) | 0以上 |
| csongtotal | int | No | TOTAL値(0:自動、100以上:手動) | 0または100以上 |
| csongicon | str | No | アイコン画像ファイル名 | - |
| csongver | str | No | KSHフォーマットバージョン | 160以上、CURRENT_KSH_VERSION以下 |

### 入力データソース

- メニュー操作(編集メニュー > 曲設定)
- キーボードショートカット(Ctrl+T, Ctrl+Shift+T)
- ダイアログ入力(_input関数)

## 出力仕様

### 出力データ

上記入力パラメータと同一の変数に値が反映される。

### 出力先

- エディタ内部変数(各csong*変数、bpml、offset等)
- 編集フラグ(e変数)
- 描画画面(gosub *drawによる再描画)
- タイトルバー(gosub *refreshtitle)

## 処理フロー

### 処理シーケンス

```
1. ユーザーがCtrl+Tまたはメニューで曲設定を選択
   └─ CMD_EDIT_SONGSETTINGS発行
2. 現在の設定値をダイアログ項目配列に展開
   └─ it(項目名), t(入力タイプ), r(現在値), opt(選択肢)の配列準備
3. _input関数でカスタムダイアログを表示
   └─ ユーザーが各項目を編集
4. ダイアログがOKで閉じられた場合(stat!=-1)
   └─ 各項目の変更を検出して変数に反映
5. 変更があった場合は編集フラグを立てる
   └─ e = e | 1
6. 描画とタイトルバーを更新
   └─ gosub *refreshtitle → gosub *draw
```

### フローチャート

```mermaid
flowchart TD
    A[Ctrl+T / メニュー] --> B{再生中?}
    B -->|Yes| C[処理中断]
    B -->|No| D[現在値を配列に展開]
    D --> E[_inputダイアログ表示]
    E --> F{OKで閉じた?}
    F -->|No| G[変更なし]
    F -->|Yes| H[各項目の変更検出]
    H --> I[変数に反映]
    I --> J{BPM妥当性チェック}
    J -->|OK| K[bpml更新]
    J -->|NG| L[BPM変更スキップ]
    K --> M[e=e|1]
    L --> M
    M --> N[gosub *refreshtitle]
    N --> O[gosub *draw]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-116-01 | 再生中制限 | 再生中(pendfl!=-1)はダイアログを開けない | 常時 |
| BR-116-02 | BPM制約 | BPMは正の値かつ65536未満であること | BPM変更時 |
| BR-116-03 | レベル下限 | レベルは最低1に丸められる | レベル変更時 |
| BR-116-04 | TOTAL制約 | TOTAL値は0(自動)または100以上 | TOTAL変更時 |
| BR-116-05 | バージョン制約 | KSHバージョンは160以上CURRENT_KSH_VERSION以下に丸められる | バージョン変更時 |
| BR-116-06 | 背景名マッピング | 13種の定義済み背景名(desert~fantasy)とカスタム背景名に対応 | 背景変更時 |
| BR-116-07 | レイヤー名マッピング | 7種の定義済みレイヤー名(arrow~hidden)とカスタムレイヤー名に対応 | レイヤー変更時 |
| BR-116-08 | バージョン変更時 | KSHバージョン変更時はキー音ライブラリがクリアされる | バージョン変更時 |

### 計算ロジック

- BPMの内部表現: `bpml.0.1 = int(double(r.i) * 1000)` (ミリBPM単位)
- 音量の下限制限: `csongvol = max(int(r.i), 0)`

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

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

データベース操作はない。設定値はKSHファイルの保存時に書き出される。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | BPM範囲外 | BPMが0以下または65536以上 | 変更をスキップ |
| - | レベル範囲外 | レベルが1未満 | 1に丸める |
| - | TOTAL範囲外 | TOTAL値が0でなく100未満 | 0に設定 |
| - | バージョン範囲外 | 160未満または最新バージョン超過 | 範囲内に丸める |

### リトライ仕様

リトライ処理はない。

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

トランザクション管理はない。ダイアログのOK/キャンセルにより一括適用・破棄が行われる。

## パフォーマンス要件

ダイアログの表示・操作に特別なパフォーマンス要件はない。

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

セキュリティに関する考慮事項はない。

## 備考

- 背景名はswitch文で13種(desert, grass, night, deepsea, sky, sunset, ocean, flame, cyber, space, mars, cloudy, fantasy)+カスタムに対応
- 前面レイヤー名はswitch文で7種(arrow, smoke, wave, techno, snow, sakura, hidden)+カスタムに対応
- ダイアログ項目の入力タイプ: t=0(数値入力), t=1(プルダウン選択), t=2(テキスト入力)

---

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

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

### 推奨読解順序

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

ダイアログで編集される変数群を把握する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | kshooteditor.hsp | `kshooteditor.hsp` | **81-82行目**: CMD_EDIT_SONGSETTINGS/SONGSETTINGS2のenum定義 |

**読解のコツ**: _input関数はカスタムダイアログUIを生成する内部関数で、it(項目名配列)、t(型配列)、opt(選択肢配列)、r(値配列)を引数に取る。

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

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | kshooteditor.hsp | `kshooteditor.hsp` | **701-702行目**: メニュー項目追加(基本設定・詳細設定) |
| 2-2 | kshooteditor.hsp | `kshooteditor.hsp` | **9666行目**: Ctrl+Tショートカット |
| 2-3 | kshooteditor.hsp | `kshooteditor.hsp` | **9772行目**: Ctrl+Shift+Tショートカット |
| 2-4 | kshooteditor.hsp | `kshooteditor.hsp` | **14083行目**: ツールバーアイコン |

#### Step 3: 基本設定ダイアログ処理を理解する

CMD_EDIT_SONGSETTINGSの処理を追う。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | kshooteditor.hsp | `kshooteditor.hsp` | **6510-6697行目**: CMD_EDIT_SONGSETTINGS処理全体 |
| 3-2 | kshooteditor.hsp | `kshooteditor.hsp` | **6513-6580行目**: ダイアログ項目配列の構築(15項目) |
| 3-3 | kshooteditor.hsp | `kshooteditor.hsp` | **6611行目**: `_input`関数呼び出し |
| 3-4 | kshooteditor.hsp | `kshooteditor.hsp` | **6613-6696行目**: ダイアログ結果の変数への反映 |

**主要処理フロー**:
- **6518行目**: `t.i=2 : it.i=lang.7.1 : r.i=csongtitle` - タイトル項目(テキスト)
- **6523行目**: `t.i=1 : it.i=lang.7.6 : opt.i="Light\nChallenge..."` - 難易度項目(プルダウン)
- **6530行目**: `t.i=0 : it.i=lang.9.5 : r.i=str(csongvol)` - 音量項目(数値)
- **6615行目**: `if(csongtitle!=r.i) : csongtitle=r.i : e=e|1` - 変更検出と反映
- **6623行目**: BPM妥当性チェック `(int(double(r.i)*1000)>0)&(int(r.i)<65536)`

#### Step 4: 詳細設定ダイアログ処理を理解する

CMD_EDIT_SONGSETTINGS2の処理を追う。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | kshooteditor.hsp | `kshooteditor.hsp` | **6698-6745行目**: CMD_EDIT_SONGSETTINGS2処理全体 |
| 4-2 | kshooteditor.hsp | `kshooteditor.hsp` | **6701-6720行目**: ダイアログ項目配列の構築(7項目) |
| 4-3 | kshooteditor.hsp | `kshooteditor.hsp` | **6732行目**: KSHバージョン変更時のキー音ライブラリクリア |
| 4-4 | kshooteditor.hsp | `kshooteditor.hsp` | **6734-6741行目**: KSHバージョン範囲チェック |

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

```
*OnCommand (2191行目)
    |
    +-- CMD_EDIT_SONGSETTINGS (6510行目)
    |       +-- ダイアログ項目配列構築 (6513-6610行目)
    |       +-- _input関数 (ダイアログ表示)
    |       +-- 変更検出・変数反映 (6613-6696行目)
    |       +-- bgname switch文 (背景名マッピング)
    |       +-- bgname_l switch文 (レイヤー名マッピング)
    |       +-- gosub *refreshtitle
    |       +-- gosub *draw
    |
    +-- CMD_EDIT_SONGSETTINGS2 (6698行目)
            +-- ダイアログ項目配列構築 (6701-6720行目)
            +-- _input関数 (ダイアログ表示)
            +-- 変更検出・変数反映 (6723-6741行目)
            +-- clearKeySoundLibrary (バージョン変更時)
            +-- gosub *refreshtitle
            +-- gosub *draw
```

### データフロー図

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

現在のメタデータ変数 ----+--> ダイアログ項目配列構築 ---+
                         |                              |
ユーザーのダイアログ入力 +--> _input関数 ---------------+--> メタデータ変数更新
                                                        |   編集フラグ(e)更新
                                                        +--> gosub *refreshtitle
                                                        +--> gosub *draw
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| kshooteditor.hsp | `kshooteditor.hsp` | ソース | エディタ本体。曲設定ダイアログの項目定義・表示・反映処理を含む |
