# インフラ設計書

## 概要

本ドキュメントは、K-Shoot MANIA v1.xx（Windows用音楽ゲーム）の実行環境・インフラ構成を記載する。本アプリケーションはHot Soup Processor（HSP）3.51で開発されたWindowsネイティブデスクトップアプリケーションであり、サーバーインフラを持たないスタンドアロン構成である。オーディオ処理にBASS Audio Library、グラフィックス描画にDirectX 9（hgimg3経由）を使用し、オプションでインターネットランキング（IR）サーバーとHTTP通信を行う。

## システム構成

### 全体構成

K-Shoot MANIAは単一のWindowsクライアントアプリケーションとして動作する。サーバー構成やコンテナ化は行わず、ユーザーのWindows PC上でローカルに実行される。

- **アプリケーション形態**: Windows 32bit ネイティブ実行ファイル（HSPコンパイル済み .exe）
- **実行モデル**: シングルプロセス・シングルスレッド（`hsp3mt`マルチスレッドランタイムはコメントアウトされ未使用）
- **配布形態**: ZIP配布またはインストーラによるローカルインストール

### サーバー構成

| サーバー種別 | 役割 | スペック | 台数 |
| --- | --- | --- | --- |
| クライアントPC | ゲーム実行環境 | Windows 7以降、DirectX 9対応GPU | ユーザー各自 |
| IRサーバー（外部） | インターネットランキング | kshootmania.com上で稼働（詳細非公開） | 1（推定） |

※ 本プロジェクトはデスクトップアプリケーションであり、自前のサーバーインフラは持たない。

### ネットワーク構成

本アプリケーションのネットワーク通信は以下に限定される:

1. **インターネットランキング（IR）通信**: `hspinet.dll`経由でHTTP GET/POSTリクエストをIRサーバー（`https://www.kshootmania.com/`）へ送信（※ソースコード公開版では実装コード削除済み）
2. **Twitter Web Intent**: リザルト画面からブラウザを起動し`https://twitter.com/intent/tweet`へリダイレクト（ネットワークライブラリは不使用）
3. **プロキシ対応**: `config.ini`の`proxy_host`/`proxy_port`設定によりHTTPプロキシ経由の通信に対応

```
[クライアントPC] --(HTTP/HTTPS)--> [IRサーバー (kshootmania.com)]
[クライアントPC] --(ブラウザ起動)--> [Twitter Web Intent]
```

## ミドルウェア

| ミドルウェア | バージョン | 用途 |
| --- | --- | --- |
| Hot Soup Processor (HSP) | 3.51 (Win32, x86, ANSI) | アプリケーションランタイム |
| MSVCR100.dll | Visual C++ 2010 Redistributable | C++ランタイムライブラリ（同梱） |
| DirectX 9 (d3d9.dll) | DirectX 9.0c | 3D/2D描画・VSync制御 |
| BASS Audio Library (bass.dll) | ※バージョンは動的取得 | オーディオ再生エンジン（44.1kHz, 200msバッファ） |
| BASS FX (bass_fx.dll) | ※バージョンは動的取得 | テンポ変更エフェクト |
| BASS VST (bass_vst.dll) | ※バージョンは動的取得 | VSTプラグインホスト |
| bassconv.dll | - | BASS再生位置変換ユーティリティ（ms単位） |
| ksmcore.dll | - | ゲームエンジンコア（カメラ制御・キー音管理） |
| kshlib.dll | ≥1663（バージョンチェック有） | 独自ライブラリ（譜面解析・HMAC-SHA1・MD5等） |
| kson.dll | ≥1752（バージョンチェック有） | KSON/KSH譜面フォーマット相互変換 |
| hspinet.dll | HSP 3.51標準 | HTTP通信・JSON解析・URLエンコード |
| hspda.dll | HSP 3.51標準 | データアクセス |
| hspext.dll | HSP 3.51標準 | 拡張機能 |
| GDI Plus | Windows標準 | 画像処理（PNG/JPEG保存・伸縮描画） |
| Msftedit.dll | Windows標準（オプション） | リッチエディットコントロール（テキスト入力） |
| winmm.dll | Windows標準 | 高精度タイマー（timeGetTime/timeBeginPeriod） |

### VSTプラグイン（音声エフェクト）

| DLLファイル | エフェクト名 | 用途 |
| --- | --- | --- |
| lib/regawo.dll | Retrigger / Gate / Echo / Wobble | リトリガー・ゲート・エコー・ワブル |
| lib/pitc.dll | PitchShift | ピッチシフト |
| lib/bitc.dll | BitCrusher | ビットクラッシャー（ローファイ効果） |
| lib/tstp.dll | TapeStop | テープストップ |
| lib/phas.dll | Phaser | フェイザー |
| lib/flan.dll | Flanger | フランジャー |
| lib/sich.dll | SideChain | サイドチェーン |

## 外部サービス連携

| サービス名 | 用途 | 接続方式 |
| --- | --- | --- |
| kshootmania.com（IRサーバー） | インターネットランキング（スコア送信・取得） | HTTP GET/POST（hspinet.dll経由）※実装コード非公開 |
| Twitter (X) | リザルト画面からのスコアツイート | Web Intent（ブラウザ起動、`exec`コマンド） |

### IR（インターネットランキング）詳細

- 接続先: `https://www.kshootmania.com/`
- 認証: ログイン機能あり（`ir_login`）※実装コード削除済み
- データ送信: スコア送信（`ir_send_score`）、譜面送信（`ir_send_chart`）※実装コード削除済み
- 譜面照合: 譜面データのMD5ハッシュ（`getChartIRHash`）を使用してサーバー側と照合
- プロキシ対応: `config.ini`で`proxy_host`/`proxy_port`を指定可能

### Twitter連携詳細

- 方式: `twitter.com/intent/tweet` のWeb Intentを使用
- ツイート内容: 楽曲名・アーティスト・難易度・スコア・ハッシュタグ`#kshootmania`を含むテキスト
- 呼び出し箇所: リザルト画面（`src/scene/result.hsp`）、コースリザルト画面（`src/scene/course_result.hsp`）

## スケーリング設計

本アプリケーションはスタンドアロンデスクトップアプリケーションであり、水平・垂直スケーリングの概念は適用されない。

- **画面解像度**: `config.ini`の`windowsize`/`fullscrsize`設定により複数解像度に対応
- **VSync制御**: Direct3D 9のラスタースキャン検出によるVSync（`third_party/mod_d3d9vsync.hsp`）
- **オーディオバッファ**: `config.ini`の`updateperiod`(デフォルト100ms)・`bufferlength`(デフォルト200ms)で調整可能

## 可用性設計

デスクトップアプリケーションのため、サーバー冗長構成やフェイルオーバーは不要。以下のローカルレベルでの耐障害性を備える:

- **起動時DLLチェック**: 必須DLL（msvcr100.dll, kshlib.dll, kson.dll, hspinet.dll, bass_vst.dll, bassconv.dll, bass.dll）の存在チェックを起動時に実行し、不足時はダイアログ表示して終了
- **DLLバージョンチェック**: kshlib.dll（≥1663）およびkson.dll（≥1752）のバージョン互換性チェック
- **楽曲キャッシュ**: `cache/songs/`配下にキャッシュファイルを生成し、次回起動時の楽曲リスト読み込みを高速化。ディレクトリ更新検知（`KSHLib_IsDirectoryUpdated`）によるキャッシュ無効化
- **安全なディレクトリ変更**: `filesystem_utils.as`によるsafe_chdirで不正なパス遷移を防止
- **IR通信障害時**: ランキング機能が利用不可になるのみで、ゲーム本体のプレイには影響しない

## バックアップ設計

| 対象 | 方式 | 頻度 | 保持期間 |
| --- | --- | --- | --- |
| config.ini | ローカルファイル（ユーザー管理） | ユーザー任意 | 無期限 |
| スコアデータ (score/*.ksc) | ローカルファイル（プレイ完了時自動保存） | プレイ毎 | 無期限 |
| 楽曲データ (songs/) | ユーザー管理 | ユーザー任意 | 無期限 |
| キャッシュ (cache/) | 自動生成・再生成可能 | 楽曲リスト更新時 | 再生成可能のため不要 |

※ サーバー側バックアップは本アプリケーションの範囲外（IRサーバーはkshootmania.com側で管理）。

## 監視設計

デスクトップアプリケーションのため、サーバー監視は不要。以下のローカルレベルでのエラー検出機能を持つ:

- **起動時環境チェック**: 必須DLL・バージョン互換性の検証（`kshootmania.hsp` 行748-832）
- **オーディオデバイス初期化**: BASS_Init失敗時のエラーハンドリング
- **ファイルI/Oエラー**: 楽曲ファイル・設定ファイルの読み込み失敗時のフォールバック処理
- **IR通信タイムアウト**: hspinet.dllの`netexec`によるHTTP通信のステータスチェック

## ファイル/ディレクトリ構成

### 実行ディレクトリ構造

```
{インストールディレクトリ}/
├── kshootmania.exe          # メイン実行ファイル
├── config.ini               # 設定ファイル
├── msvcr100.dll             # VC++ 2010ランタイム（同梱）
├── bass.dll                 # BASSオーディオエンジン
├── bass_fx.dll              # BASSテンポ変更
├── bass_vst.dll             # BASS VSTプラグインホスト
├── bassconv.dll             # BASS位置変換ユーティリティ
├── kshlib.dll               # 独自ライブラリ
├── ksmcore.dll              # ゲームエンジンコア
├── kson.dll                 # KSON/KSH変換
├── hspinet.dll              # ネットワーク通信
├── hspda.dll                # データアクセス
├── hspext.dll               # 拡張機能
├── lib/                     # VSTプラグイン群
│   ├── regawo.dll, pitc.dll, bitc.dll, tstp.dll
│   ├── phas.dll, flan.dll, sich.dll
├── imgs/                    # 画像リソース
├── se/                      # 効果音ファイル（.wav/.ogg）
├── lang/                    # 言語ファイル
├── songs/                   # 楽曲データ（ユーザー追加）
│   └── {フォルダ}/{譜面}.ksh or .kson
├── courses/                 # コースデータ
│   └── score/{player}/      # コーススコアデータ
├── score/                   # スコアデータ（自動生成）
│   └── {player}/{song}/{chart}.ksc
├── cache/                   # キャッシュ（自動生成）
│   ├── songs/               # 楽曲リストキャッシュ
│   └── bg/                  # 背景画像キャッシュ
└── third_party_license.txt  # サードパーティライセンス
```

### 一時ディレクトリ

```
%TEMP%\kshootmania\          # Windows一時ディレクトリ配下に作成
```

起動時に`GetTempPathA` → `GetLongPathNameA`で一時ディレクトリパスを取得し、`kshootmania`サブディレクトリを作成。

## 備考

- 本アプリケーションはHSP 3.51（x86, ANSI版）専用であり、HSP 3.6以降では正常動作しない
- HSPのUTF-8版は開発当時（2013年）に存在しなかったため非対応（移植も困難）
- Win32 APIを多用しているため、HSPのLinux版では動作しない（Wine経由でのコンパイル済みバイナリ実行は可能）
- VSTプラグイン群（lib/配下）はカスタム実装であり、BASS VST経由でロードされる
- RC4暗号化モジュール（`third_party/rc4_crypt.hsp`）が含まれるが、用途はソースコード内で限定的
- IR関連の実装コードはセキュリティ上の理由からソースコード公開時に削除されている
