# 機能設計書 129-kson.dll

## 概要

本ドキュメントは、KShootManiaにおけるkson.dllの設計を記述する。KSONフォーマットの読み書きを処理するネイティブDLLであり、譜面エディタでのKSON形式エクスポート・インポートに使用される。

### 本機能の処理概要

kson.dllは、KSON(K-Shoot Mania Object Notation)フォーマットとKSH(K-Shoot Mania)フォーマット間の相互変換を行うネイティブDLLである。主に譜面エディタ(kshooteditor.hsp)から使用され、KSH形式の譜面をKSON形式にエクスポートしたり、KSON形式の譜面をKSH形式に変換してインポートする機能を提供する。

**業務上の目的・背景**：KSONは、KSHフォーマットの後継となる新しい譜面フォーマットである。従来のKSH形式のテキストベースの譜面データを、より構造化されたJSON形式(KSON)に変換することで、他の音楽ゲームシステムとの互換性を向上させる。エディタでKSON形式へのエクスポートを可能にすることで、譜面データの可搬性を高める。

**機能の利用シーン**：
- 譜面エディタでのKSONエクスポート（File→Export as KSON）
- 譜面エディタでのKSONインポート（File→Open→.ksonファイル選択）
- エクスポート時の診断警告(DiagWarning)の表示

**主要な処理内容**：
1. KSON_GetVersion: kson.dllのバージョン取得
2. KSON_ToKSH: KSONデータをKSH形式に変換
3. KSON_FromKSH: KSHデータをKSON形式に変換
4. KSON_FromKSH_URLEncoded: KSHデータをURLエンコードされたKSON形式に変換
5. KSON_GetLastEditorDiagWarning: 最後のエディタ用診断警告を取得
6. KSON_GetLastPlayerDiagWarning: 最後のプレイヤー用診断警告を取得

**関連システム・外部連携**：kson.dll (ネイティブDLL)。KSH/KSONファイルフォーマット。

**権限による制御**：特になし。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | 譜面エディタ | 主機能 | KSONエクスポート・インポート(kshooteditor.hsp) |

## 機能種別

データ変換処理（KSH⇔KSON形式変換）

## 入力仕様

### 入力パラメータ

#### KSON_ToKSH

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| ksonData | sptr | Yes | KSONフォーマットのデータ（文字列） | 有効なKSON形式であること |
| outputBuffer | int | Yes | 0=サイズ取得のみ, varptr(buf)=変換結果格納 | なし |

#### KSON_FromKSH

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| kshData | sptr | Yes | KSHフォーマットのデータ（文字列） | 有効なKSH形式であること |
| outputBuffer | int | Yes | 0=サイズ取得のみ, varptr(kson)=変換結果格納 | なし |
| appName | sptr | Yes | アプリケーション名 | 文字列 |
| appVersion | sptr | Yes | アプリケーションバージョン | 文字列 |

#### KSON_GetLastEditorDiagWarning

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| outputBuffer | int | Yes | 0=サイズ取得のみ, varptr(diagwarning)=警告文格納 | なし |

### 入力データソース

譜面エディタのメモリ上のKSH/KSONデータ。

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| KSON_GetVersion戻り値 | int | DLLバージョン番号（最低要求: 1752） |
| KSON_ToKSH出力 | str | KSH形式に変換された譜面データ |
| KSON_FromKSH出力 | str | KSON形式に変換された譜面データ |
| stat (サイズ取得時) | int | 出力データのサイズ(バイト数) |

### 出力先

譜面エディタのメモリ上のバッファ、またはファイル（notesaveで書き出し）

## 処理フロー

### 処理シーケンス

```
1. KSONインポート (.ksonファイルの開読み)
   ├─ .ksonファイルをnoteloadでメモリに読み込み
   ├─ KSON_ToKSH(ksonbuf, 0): サイズ取得
   ├─ sdim buf, stat+1: バッファ確保
   ├─ KSON_ToKSH(ksonbuf, varptr(buf)): KSH形式に変換
   └─ KSON_GetLastEditorDiagWarning: 警告メッセージ取得

2. KSONエクスポート (KSH→KSON変換・保存)
   ├─ KSON_FromKSH(buf, 0, aname, aversion): サイズ取得
   ├─ sdim kson, stat+1: バッファ確保
   ├─ KSON_FromKSH(buf, varptr(kson), aname, aversion): KSON形式に変換
   ├─ notesel kson: notesave用に選択
   ├─ notesave fname_kson_export: ファイルに保存
   └─ KSON_GetLastEditorDiagWarning: 警告メッセージ取得
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B{操作種別}
    B -->|インポート| C[.ksonファイル読み込み]
    C --> D[KSON_ToKSH: サイズ取得]
    D --> E[バッファ確保]
    E --> F[KSON_ToKSH: KSH変換]
    F --> G[KSON_GetLastEditorDiagWarning]
    G --> H{警告あり?}
    H -->|Yes| I[警告ダイアログ表示]
    H -->|No| J[KSHデータをエディタに読み込み]
    B -->|エクスポート| K[KSON_FromKSH: サイズ取得]
    K --> L[バッファ確保]
    L --> M[KSON_FromKSH: KSON変換]
    M --> N[notesave: ファイル保存]
    N --> O[KSON_GetLastEditorDiagWarning]
    I --> P[終了]
    J --> P
    O --> P
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-129-01 | バージョンチェック | KSON_GetVersion()の戻り値が1752以上であること | DLL読み込み時 |
| BR-129-02 | 2段階呼び出し | サイズ取得(引数=0)→バッファ確保→実変換の2段階で呼び出す | ToKSH/FromKSH/DiagWarning |
| BR-129-03 | DLL存在確認 | kson.dllの存在確認を行い、なければエラーで終了 | エディタ起動時 |
| BR-129-04 | KSON拡張子 | エクスポート時に.kson拡張子が付与されていなければ自動付加 | エクスポート時 |

### 計算ロジック

KSH⇔KSON変換のアルゴリズムはDLL内部に実装されている。

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

該当なし。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | DLL不存在 | kson.dllが見つからない | エラーダイアログ表示→終了(kshooteditor.hsp 635行目) |
| - | バージョン不足 | DLLバージョンが1752未満 | エラーダイアログ表示→終了(kshooteditor.hsp 636-637行目) |
| - | 変換エラー | KSH/KSONの変換に失敗 | DiagWarning経由で警告メッセージを表示 |

### リトライ仕様

リトライ処理なし。

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

該当なし。

## パフォーマンス要件

ネイティブDLL実装であり、譜面データの変換は高速に完了する。変換データサイズに比例した処理時間。

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

- ファイル入出力を行うため、ファイルパスの検証が必要
- DLLの改ざんリスクへの注意

## 備考

- kson.dllバイナリファイルはプロジェクトルートに配置
- kshooteditor.hsp(14行目)でのみインクルードされ、kshootmania.hspでは使用されない
- KSONフォーマットはKSHの後継として設計された新しい譜面形式
- is_kson_exportフラグ(kshooteditor.hsp 447行目)でKSONエクスポートモードの有効/無効を管理
- KSON_FromKSH_URLEncoded関数も定義されているが、エディタ内での使用箇所は限定的

---

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

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

### 推奨読解順序

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

DLL関数のインターフェースを理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | kson.as | `src/kson.as` | 全DLL関数宣言(5-10行目) |

**読解のコツ**: KSON_ToKSHとKSON_FromKSHは「2段階呼び出し」パターンを使用する。第2引数が0の場合はサイズ取得のみ(statに結果サイズ)、varptr(buf)の場合は実際の変換結果をバッファに格納する。

#### Step 2: DLL初期化とバージョンチェックを理解する

エディタ起動時のDLL検証処理を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | kshooteditor.hsp | `kshooteditor.hsp` | kson.dll存在確認とバージョンチェック(634-637行目) |

**主要処理フロー**:
1. **634行目**: `exist "kson.dll"` - DLLファイルの存在確認
2. **635行目**: 存在しない場合(`strsize=-1`)はエラーダイアログで終了
3. **636行目**: `if(KSON_GetVersion()<1752)` - バージョンチェック
4. **637行目**: バージョン不足の場合はエラーダイアログで終了

#### Step 3: KSONインポートを理解する

.ksonファイルの読み込みとKSH変換処理を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | kshooteditor.hsp | `kshooteditor.hsp` | KSONインポート処理(2337-2355行目) |

**主要処理フロー**:
- **2337行目**: `.kson`拡張子の判定
- **2339行目**: `notesel ksonbuf` → `noteload` でKSONファイル読み込み
- **2341行目**: `KSON_ToKSH ksonbuf, 0` - 出力サイズ取得
- **2350行目**: `KSON_ToKSH ksonbuf, varptr(buf)` - 実変換
- **2352行目**: `KSON_GetLastEditorDiagWarning 0` - 警告サイズ取得
- **2355行目**: `KSON_GetLastEditorDiagWarning varptr(diagwarning)` - 警告テキスト取得

#### Step 4: KSONエクスポートを理解する

KSH→KSON変換とファイル保存処理を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | kshooteditor.hsp | `kshooteditor.hsp` | KSONエクスポートダイアログ(5154-5163行目) |
| 4-2 | kshooteditor.hsp | `kshooteditor.hsp` | KSONエクスポート実処理(15336-15347行目) |

**主要処理フロー**:
- **5154行目**: `dialog "kson",17` - KSON形式保存ダイアログ
- **5159行目**: 拡張子が.ksonでなければ自動付加
- **15336行目**: `if(is_kson_export)` - エクスポートフラグ判定
- **15337行目**: `KSON_FromKSH buf, 0, aname, aversion` - サイズ取得
- **15344行目**: `KSON_FromKSH buf, varptr(kson), aname, aversion` - 実変換
- **15346行目**: `notesave fname_kson_export` - ファイル保存

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

```
kshooteditor.hsp (14行目: #include "src/kson.as")
    |
    +-- 起動時チェック (634-637行目)
    |       +-- KSON_GetVersion (kson.dll)
    |
    +-- KSONインポート (2337-2355行目)
    |       +-- KSON_ToKSH (kson.dll) [2段階呼び出し]
    |       +-- KSON_GetLastEditorDiagWarning (kson.dll)
    |
    +-- KSONエクスポート (15336-15347行目)
            +-- KSON_FromKSH (kson.dll) [2段階呼び出し]
            +-- KSON_GetLastEditorDiagWarning (kson.dll)
```

### データフロー図

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

.ksonファイル ------------> KSON_ToKSH ------------------> KSH形式データ
  (noteload)                  |                              (buf変数)
                             +-- KSON→KSH変換
                             +-- DiagWarning取得

KSH形式データ(buf) ------> KSON_FromKSH ----------------> .ksonファイル
  + アプリ名(aname)          |                              (notesave)
  + バージョン(aversion)      +-- KSH→KSON変換
                             +-- DiagWarning取得
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| kson.as | `src/kson.as` | ソース | kson.dllのHSPバインディング定義 |
| kson.dll | `kson.dll` | DLL | KSH⇔KSON変換のネイティブ実装 |
| kshooteditor.hsp | `kshooteditor.hsp` | ソース | kson.dllの使用元(14行目インクルード) |
