# 機能設計書 127-ksmcore.dll

## 概要

本ドキュメントは、KShootManiaにおけるコアDLL(ksmcore.dll)の設計を記述する。ゲームシステム管理、カメラ値計算、キー音再生管理を担うネイティブDLLである。

### 本機能の処理概要

ksmcore.dllは、KShootManiaのゲームプレイにおけるコアロジックを担うネイティブDLLである。ゲームシステムの生成・更新・破棄、カメラ制御パラメータの計算、キー音(効果音)の再生管理を提供する。HSP3のスクリプト処理速度では対応しきれない高精度な計算処理をDLL側で実行することで、ゲームのパフォーマンスを確保している。

**業務上の目的・背景**：音楽ゲームでは、カメラ制御値の高精度なリアルタイム計算やキー音の低レイテンシ再生管理が要求される。HSP3のスクリプト実行速度では処理が間に合わないため、C/C++で実装されたネイティブDLLにこれらの処理を委譲している。

**機能の利用シーン**：
- ゲームプレイ画面でのカメラ値計算（Zoom Top/Bottom/Side、Center Split、Manual Tilt）
- ゲームプレイ画面でのゲームシステム更新（タイミング同期）
- キー音の再生管理（ポリフォニー制御付き）

**主要な処理内容**：
1. CreateGameSystem: 譜面ファイルからゲームシステムオブジェクトを生成
2. UpdateGameSystem: ゲーム進行に合わせてシステム状態を更新
3. DestroyGameSystem: ゲームシステムオブジェクトを破棄
4. GetCurrentCamValue: 現在のカメラ制御パラメータ値を取得
5. CreateKeySound: キー音オブジェクトの生成
6. PlayKeySound: キー音の再生
7. DestroyKeySound: キー音オブジェクトの破棄
8. StartsWith: 文字列の先頭一致判定

**関連システム・外部連携**：ksmcore.dll (ネイティブDLL)。譜面ファイル(.ksh)を入力として読み込む。

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

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 5 | ゲームプレイ画面 | 主機能 | カメラ値計算(GetCurrentCamValue)、ゲームシステム更新(UpdateGameSystem) |

## 機能種別

計算処理・データ連携（ネイティブDLL連携）

## 入力仕様

### 入力パラメータ

#### CreateGameSystem

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| chartFile | sptr | Yes | 譜面ファイルのパス | 存在するファイルであること |
| offset | double | Yes | タイミングオフセット値(t_moex) | 数値 |
| pGameSystem | int(var) | Yes | GameSystemポインタの格納先 | varptr指定 |

#### UpdateGameSystem

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| pGameSystem | int | Yes | GameSystemポインタ | CreateGameSystemで取得した値 |
| time | double | Yes | 現在の再生時間(ms) | 数値 |

#### GetCurrentCamValue

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| pGameSystem | int | Yes | GameSystemポインタ | 有効なポインタ |
| camParam | int | Yes | カメラパラメータ種別(CAM_*定数) | 0-4の範囲 |

#### CreateKeySound

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| soundFile | sptr | Yes | キー音ファイルのパス | 存在するファイルであること |
| maxPolyphony | int | Yes | 最大同時発音数 | 1以上 |
| pKeySound | int(var) | Yes | KeySoundポインタの格納先 | varptr指定 |

### 入力データソース

譜面ファイル(.ksh)、キー音ファイル(.wav等)

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| CreateGameSystem戻り値 | int | 0=失敗, 非0=成功 |
| GetCurrentCamValue戻り値 | double(float) | カメラパラメータの現在値 |
| CreateKeySound戻り値 | int | 0=失敗, 非0=成功 |
| StartsWith戻り値 | int | 0=不一致, 1=一致 |

### 出力先

呼び出し元のHSPスクリプト変数

## 処理フロー

### 処理シーケンス

```
1. 初期化フェーズ (play_init.hsp)
   ├─ CreateGameSystem(譜面ファイル, オフセット, ポインタ)
   │   └─ 譜面ファイルからカメラ制御データを解析
   │   └─ GameSystemオブジェクトを生成
   │   └─ 生成したポインタをgame_system変数に格納
   └─ CreateKeySound(音声ファイル, ポリフォニー数, ポインタ)
       └─ キー音ファイルを読み込み
       └─ ポリフォニー制御の初期化

2. 更新フェーズ (play_update.hsp)
   └─ UpdateGameSystem(game_system, 現在時間)
       └─ 現在時間に基づくカメラ値の更新

3. 描画フェーズ (play_draw_frame.hsp)
   └─ GetCurrentCamValue(game_system, CAM_*)
       └─ Zoom Top/Bottom/Side, Center Split, Manual Tiltの値を取得

4. 終了フェーズ
   └─ DestroyGameSystem(game_system)
   └─ DestroyKeySound(pKeySound)
```

### フローチャート

```mermaid
flowchart TD
    A[プレイ初期化] --> B[CreateGameSystem]
    B --> C{成功?}
    C -->|Yes| D[ゲームループ開始]
    C -->|No| E[エラー処理・戻る]
    D --> F[UpdateGameSystem: 状態更新]
    F --> G[GetCurrentCamValue: カメラ値取得]
    G --> H[描画処理]
    H --> I{プレイ終了?}
    I -->|No| F
    I -->|Yes| J[DestroyGameSystem]
    J --> K[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-127-01 | カメラパラメータ定数 | CAM_ZOOM_TOP=0, CAM_ZOOM_BOTTOM=1, CAM_ZOOM_SIDE=2, CAM_CENTER_SPLIT=3, CAM_MANUAL_TILT=4 | GetCurrentCamValue呼び出し時 |
| BR-127-02 | ライフサイクル管理 | Create→Update→Destroyのライフサイクルに従うこと | GameSystem/KeySound管理 |
| BR-127-03 | CreateGameSystem失敗時 | falseが返された場合、DestroyGameSystemの呼び出しは不要 | 初期化失敗時 |

### 計算ロジック

カメラ制御値の計算ロジックはDLL内部に実装されている。ksmcore.as内のGetCurrentCamValueラッパーで`ret = 0.0f`を初期値として設定し、DLL関数の結果を受け取る。

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

該当なし。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| 0 | GameSystem生成失敗 | 譜面ファイルの読み込みエラー | play_init.hspでreturnし、プレイを中断 |
| 0 | KeySound生成失敗 | 音声ファイルの読み込みエラー | key_sound.asでエラーダイアログを表示 |

### リトライ仕様

リトライ処理なし。

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

該当なし。

## パフォーマンス要件

ネイティブDLL(C/C++実装)であり、リアルタイム処理に対応した高速な実行が可能。毎フレーム呼び出されるUpdateGameSystemとGetCurrentCamValueは特に低レイテンシが求められる。

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

- ネイティブDLLのためバッファオーバーフロー等のメモリ安全性リスクが存在
- DLLの改ざんによる不正動作のリスク

## 備考

- ksmcore.dllバイナリファイルはプロジェクトルートに配置されている
- kshootmania.hsp(142行目)とkshooteditor.hsp(13行目)の両方でインクルードされている
- GetCurrentCamValue_関数はksmcore.as内でラッパーが定義されており、double(float)の戻り値を安全に取得する
- Center Splitの値は100で除算して使用される（play_draw_frame.hsp 3行目）

---

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

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

### 推奨読解順序

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

DLL関数のインターフェースとカメラパラメータ定数を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | ksmcore.as | `src/ksmcore.as` | DLL関数宣言(5-12行目)とカメラパラメータ定数(14-18行目) |

**読解のコツ**: `#cfunc`は戻り値のある関数、`#func`は戻り値のない関数(命令)として定義される。`sptr`は文字列ポインタ、`double`は倍精度浮動小数点、`var`は変数参照を示す。

#### Step 2: ラッパー関数を理解する

HSP側で定義されたラッパー関数の役割を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | ksmcore.as | `src/ksmcore.as` | GetCurrentCamValueラッパー(21-24行目) |

**主要処理フロー**:
1. **22行目**: `ret = 0.0f` - 戻り値変数の初期化
2. **23行目**: `GetCurrentCamValue_@ pGameSystem, camParam, ret` - DLL関数呼び出し(retに結果格納)
3. **24行目**: `return ret` - float値を返却

#### Step 3: 呼び出し元を理解する

プレイ画面各フェーズでの呼び出し箇所を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | play_init.hsp | `src/scene/play/play_init.hsp` | CreateGameSystem呼び出し(741行目) |
| 3-2 | play_update.hsp | `src/scene/play/play_update.hsp` | UpdateGameSystem呼び出し(41行目) |
| 3-3 | play_draw_frame.hsp | `src/scene/play/play_draw_frame.hsp` | GetCurrentCamValue呼び出し(3,631,685,699,714行目) |

**主要処理フロー**:
- **741行目(play_init.hsp)**: `if (CreateGameSystem(cnotesfile, double(t_moex), varptr(game_system)) == 0)` - 失敗時はreturn
- **41行目(play_update.hsp)**: `UpdateGameSystem game_system, double(t)` - 毎フレーム更新
- **3行目(play_draw_frame.hsp)**: `center_split_now = GetCurrentCamValue(game_system, CAM_CENTER_SPLIT) / 100.0f`
- **631行目(play_draw_frame.hsp)**: `ztiltnow2 = GetCurrentCamValue(game_system, CAM_MANUAL_TILT) * romax`

#### Step 4: キー音関連を理解する

CreateKeySound/PlayKeySoundの使用箇所を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | key_sound.as | `src/audio/key_sound.as` | CreateKeySound呼び出し(68行目)、DestroyKeySound呼び出し(105行目) |
| 4-2 | play_audio.hsp | `src/scene/play/play_audio.hsp` | PlayKeySound呼び出し(207行目) |

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

```
kshootmania.hsp (142行目: #include "src/ksmcore.as")
    |
    +-- play_init.hsp
    |       |
    |       +-- CreateGameSystem (ksmcore.dll)
    |
    +-- play_update.hsp
    |       |
    |       +-- UpdateGameSystem (ksmcore.dll)
    |
    +-- play_draw_frame.hsp
    |       |
    |       +-- GetCurrentCamValue (ksmcore.as ラッパー)
    |               +-- GetCurrentCamValue_ (ksmcore.dll)
    |
    +-- key_sound.as
    |       |
    |       +-- CreateKeySound (ksmcore.dll)
    |       +-- DestroyKeySound (ksmcore.dll)
    |
    +-- play_audio.hsp
            |
            +-- PlayKeySound (ksmcore.dll)
```

### データフロー図

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

譜面ファイル(.ksh) ------> CreateGameSystem -----------> game_systemポインタ
  + オフセット値              |
                             +-- 譜面データ解析
                             +-- カメラ制御データ構築

再生時間(double) ---------> UpdateGameSystem -----------> (内部状態更新)
  + game_system               |
                             +-- タイムライン進行

game_system + CAM_* -------> GetCurrentCamValue ---------> カメラ値(double)
                             |
                             +-- CAM_ZOOM_TOP
                             +-- CAM_ZOOM_BOTTOM
                             +-- CAM_ZOOM_SIDE
                             +-- CAM_CENTER_SPLIT
                             +-- CAM_MANUAL_TILT

音声ファイル(.wav) -------> CreateKeySound -------------> pKeySoundポインタ
  + ポリフォニー数            |
                             +-- 音声データ読み込み

pKeySound + 音量 ---------> PlayKeySound ---------------> (音声再生)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| ksmcore.as | `src/ksmcore.as` | ソース | ksmcore.dllのHSPバインディング定義 |
| ksmcore.dll | `ksmcore.dll` | DLL | コアゲームロジックのネイティブ実装 |
| kshootmania.hsp | `kshootmania.hsp` | ソース | ksmcore.asのインクルード元(142行目) |
| kshooteditor.hsp | `kshooteditor.hsp` | ソース | ksmcore.asのインクルード元(13行目) |
| play_init.hsp | `src/scene/play/play_init.hsp` | ソース | CreateGameSystem呼び出し(741行目) |
| play_update.hsp | `src/scene/play/play_update.hsp` | ソース | UpdateGameSystem呼び出し(41行目) |
| play_draw_frame.hsp | `src/scene/play/play_draw_frame.hsp` | ソース | GetCurrentCamValue呼び出し(3,631,685,699,714行目) |
| key_sound.as | `src/audio/key_sound.as` | ソース | CreateKeySound/DestroyKeySound呼び出し |
| play_audio.hsp | `src/scene/play/play_audio.hsp` | ソース | PlayKeySound呼び出し(207行目) |
