# 非機能要件定義書

## 概要

本ドキュメントは、K-Shoot MANIA v1.x（Windows用音楽ゲーム）の非機能要件を定義するものである。本アプリケーションはHSP (Hot Soup Processor) 3.51 + C++で開発されたスタンドアロンデスクトップアプリケーションであり、サーバー/クライアント型のWebアプリケーションとは異なるため、非機能要件もリアルタイム音楽ゲームとしての特性に基づいて定義する。

## 性能要件

### レスポンスタイム

| 処理種別 | 目標値 | 備考 |
| --- | --- | --- |
| フレーム描画 | モニターリフレッシュレート準拠（16.7ms以内 @60Hz） | VSync有効時はモニターリフレッシュレートに同期。`mod_d3d9vsync.hsp`にてDirect3D 9のVSync制御を実装 |
| 音声再生遅延 | デフォルト200ms（最小6ms） | `config.ini`の`#bufferlength:`で調整可能。BASS Audio LibraryのバッファサイズとしてBASSに設定（`kshootmania.hsp:775`） |
| 入力遅延 | 設定可能（デフォルト0ms） | `config.ini`の`inputdelay=`で設定。`play_init.hsp:20-32`にて適用 |
| グローバルオフセット | 設定可能（デフォルト0ms） | `config.ini`の`globaloffset=`で音声同期オフセットを調整 |
| レーザー入力遅延 | 設定可能（デフォルト0ms） | `config.ini`の`laserdelay=`で設定 |
| SFXエフェクト遅延 | 設定可能（デフォルト0ms） | `config.ini`の`soundfx_delay=`で設定 |
| ビジュアルオフセット | 設定可能（デフォルト0ms） | `config.ini`の`visual_offset=`で映像と音声のずれを補正 |

### スループット

| 項目 | 目標値 | 備考 |
| --- | --- | --- |
| フレームレート | モニターリフレッシュレート（通常60fps） | `mod_d3d9vsync.hsp`にてリフレッシュレートを取得し同期。フレームスキップオプションあり（`frameskip=`設定） |
| タイミング同期精度 | 指数平滑化フィルタによる補正 | `play_audio.hsp`にて`timingdif=(timingdif*7+double(t-at))/8f`で時間差を平滑化 |
| CPU使用率 | フレーム単位で計測 | `play_update.hsp:15-25`にてフレーム処理時間を120ms/60ms/30ms単位でモニタリング |
| 低品質モード | 有効/無効切替可能 | `config.ini`の`lowquality=`で描画品質を下げ、パフォーマンスを優先 |

## 可用性要件

| 項目 | 目標値 | 備考 |
| --- | --- | --- |
| 稼働率 | N/A（スタンドアロンアプリケーション） | ローカル実行のため、サーバー稼働率の概念は適用外 |
| 計画停止時間 | N/A | アプリケーション更新時のみ停止が必要 |
| 障害復旧時間（RTO） | アプリケーション再起動（数秒） | エラー発生時はダイアログ表示後にユーザーが手動で対処 |
| 目標復旧時点（RPO） | プレイデータ：直前のスコア保存時点 | スコアデータは`*reloadscore`/`*refreshscore`で管理。プレイ中のクラッシュ時は当該プレイのスコアが失われる可能性あり |

### 音声再生の可用性

| 項目 | 実装内容 | 備考 |
| --- | --- | --- |
| 音声再生リトライ | 再生位置が500ms以上ずれた場合に自動リトライ | `play_audio.hsp:3-12`にて`mrepeat`フラグで制御。チャンネルのボリュームをスライドで0にしてからリトライ |
| メモリ内バッファ | `#bufferfrommemory:enable`で有効化可能 | 音声データをメモリ上に展開し、ディスクI/O遅延を回避 |

## セキュリティ要件

### 認証・認可

| 項目 | 実装状況 | 備考 |
| --- | --- | --- |
| オンライン認証 | 削除済み | ソースコード公開に伴い、インターネットランキング（IR）機能、INPUT GATE（オンラインチャートダウンロード）、Twitter連携機能はすべて削除。`src/ir.hsp`にスタブのみ残存 |
| ローカル認証 | なし | スタンドアロンアプリケーションのため不要 |

### データ保護

| 項目 | 実装内容 | 備考 |
| --- | --- | --- |
| チャートファイル難読化 | RC4暗号化 | `third_party/rc4_crypt.hsp`に実装。KSA（Key Scheduling Algorithm）を使用したRC4ストリーム暗号でチャートデータを難読化 |
| チャートIR検証 | MD5ハッシュ | `src/ir.hsp:47-68`にて`varmd5`関数でチャートのMD5ハッシュを算出。ただし現在はIR機能が削除されているため未使用 |
| URLエンコード | UTF-8対応 | `src/ir.hsp:119-132`にてURL安全なエンコード/デコード処理を実装。BOM処理も考慮 |
| Base64エンコード | 実装あり | `third_party/mbase64.as`で実装 |

### セキュリティ上の留意事項

| 項目 | 内容 |
| --- | --- |
| RC4の脆弱性 | RC4は既知の脆弱性を持つ暗号方式であり、難読化目的での使用に限定すべき。高度なセキュリティが必要な場合はAES等への置き換えを検討 |
| MD5の脆弱性 | MD5は衝突攻撃に対して脆弱であり、整合性検証目的での使用にはSHA-256等のより安全なハッシュ関数への置き換えを検討 |
| ファイルパス処理 | `GetTempPath`/`GetLongPathName` APIでパス取得。ディレクトリトラバーサルへの明示的対策は確認されない |

## 拡張性要件

### アーキテクチャの拡張性

| 項目 | 現状 | 備考 |
| --- | --- | --- |
| モジュール化 | 限定的 | 大部分のコードが`#module`を使用せずグローバル変数で動作。`key_sound`モジュール等一部例外あり。README.mdにも「基本的にモジュールが使用されていない」と記載 |
| シーンベース設計 | 実装済み | タイトル（`title.hsp`）→ 曲選択（`select.hsp`）→ プレイ（`play.hsp` + `play/*`）→ 結果（`result.hsp`）のシーン遷移構造 |
| プレイシーン分割 | 実装済み | `play_init.hsp`, `play_update.hsp`, `play_audio.hsp`, `play_draw_frame.hsp`, `play_game_logic.hsp`等に機能分割 |
| DLL拡張 | 実装済み | `ksmcore.dll`（C++）、`kson.dll`（KSON形式）、`bass.dll`（BASS Audio）等のネイティブDLLで機能拡張 |
| コンテナ化 | 未対応 | スタンドアロンWindows EXEのため、Docker/Kubernetes等は適用外 |

### 設定の拡張性

| 項目 | 実装内容 | 備考 |
| --- | --- | --- |
| `config.ini` | 30以上の設定項目 | キーバインド、ジョイスティック、表示設定、音声設定、タイミング補正等を外部ファイルで設定可能 |
| 多言語対応 | 言語ファイル方式 | 外部言語ファイルを読み込む仕組み。ファイル不在時はエラーダイアログ表示（`kshootmania.hsp:1264-1270`） |
| スキン/テーマ | 画像ファイル差替え | 背景画像（`background=` 設定で0-3段階）、ゲート画面等をキャッシュ管理 |

## 保守性要件

| 項目 | 現状 | 備考 |
| --- | --- | --- |
| コード品質ツール | 未導入 | HSPにはネイティブなLinter/Formatterが存在しない |
| CI/CDパイプライン | 未導入 | GitHub Actions、GitLab CI等の自動化ツール未実装 |
| 自動テスト | 未実装 | ユニットテスト/統合テストフレームワーク未導入 |
| ドキュメント自動生成 | Claude Agents活用 | `.claude/skills/`配下のスキルで設計書等を自動生成 |
| 変数命名規則 | 不統一 | 変数名が無意味に省略されている箇所が多数（README.mdに記載）。`stat1`, `stat2`等の仮変数が多用 |
| マジックナンバー | 多数存在 | ハードコードされた数値が各所に散在。定数定義（`#define`）は一部のみ |
| ビルドプロセス | 手動 | `#packopt name "kshootmania"`でHSPコンパイラによるEXEパッケージ作成。自動ビルドスクリプトなし |

## 運用・監視要件

### ロギング

| 項目 | 実装内容 | 備考 |
| --- | --- | --- |
| エラーログ出力方式 | ダイアログ表示 | `dialog`コマンドによるユーザー通知。ファイルへのログ出力は未実装 |
| エラー種別 | サウンドエラー、テクスチャエラー、ファイル不在エラー | `key_sound.as:58-74`にてサウンド読み込みエラー、テクスチャ読み込みエラー等を検出 |
| デバッグ出力 | コメント化されたデバッグオプション | `kshootmania.hsp:1-4`にて`#runtime "hsp3mt"`（マルチスレッド）、`#cmpopt ppout 1`（プリプロセッサ出力）がコメント化 |

### エラーハンドリング

| 項目 | 実装内容 | 備考 |
| --- | --- | --- |
| サウンドファイルエラー | ダイアログ表示して継続 | ファイル不在時・読み込み失敗時にエラーダイアログを表示し、該当キー音のポインタを0に設定して処理継続 |
| テクスチャエラー | ステータスコードで検出 | `"Texture Error("+stat+")"`形式でエラー報告 |
| 言語ファイルエラー | 致命的エラーとして処理 | ファイル不在時にエラーダイアログ表示 |
| BASSライブラリエラー | エラーコード取得可能 | `BASS_ErrorGetCode`関数でエラーコードを取得 |
| エラー無視処理 | `*ignoreerror`ラベル | 一部のエラーは意図的に無視して処理継続（`kshootmania.hsp:1058-1059`） |

### リソース管理

| 項目 | 実装内容 | 備考 |
| --- | --- | --- |
| メモリリーク対策 | `onexit`による自動解放 | `BASS_Free`を`onexit`で登録し、終了時にBASSライブラリを自動解放（`src/bass.as`） |
| キー音リソース解放 | ハッシュテーブル一括クリア | `clearKeySoundLibrary`（`onexit`登録）でキー音ライブラリの全リソースを解放（`key_sound.as:101-108`） |
| キャッシュ管理 | ファイルキャッシュの削除 | `cache/`, `cache/bg/`, `cache/gate/`ディレクトリ内のキャッシュファイルを管理（`kshootmania.hsp:2083-2104`） |
| イメージバッファ管理 | バッファID方式 | `buffer`コマンドでバッファを確保し、`gsel`で切替。`#define`で定数管理（`IMG_LOADING=167`, `IMG_DRAWTXT_TEMP=153`等） |
| サウンドストリーム解放 | 個別解放関数 | `BASS_StreamFree`, `BASS_SampleFree`で個別のストリーム/サンプルを解放 |

### タイムアウト設定

| 項目 | 実装内容 | 備考 |
| --- | --- | --- |
| 音声再生タイムアウト | 再生位置500msずれでリトライ | `play_audio.hsp`にて音声チャンネルの再生位置が目標位置から500ms以上ずれた場合にリトライ処理を実行 |
| ゲーム終了判定 | 楽曲終了時点で自動終了 | `mlength<=stat1`（楽曲長≦再生位置）で終了フラグを設定（`play_audio.hsp`） |
| フレーム待機 | `await`コマンドで制御 | `await 0`（即座）、`await 7`（7ms待機）、`await 100`（100ms待機）でフレーム間隔を制御 |

## 備考

### プラットフォーム制約

- **対応OS**: Windows（x86 ANSI版HSP 3.51ランタイム）
- **グラフィックスAPI**: Direct3D 9（ハードウェアアクセラレーション必須）
- **音声API**: BASS Audio Library（bass.dll, bass_fx.dll, bass_vst.dll）
- **実行形式**: スタンドアロンEXE + DLL群

### オンライン機能の削除について

ソースコード公開に伴い、以下のオンライン機能がすべて削除されている（`src/ir.hsp`にスタブのみ残存）：

- インターネットランキング（IR）送信・受信
- INPUT GATE（オンラインチャートダウンロード）
- Twitter連携

これらの機能に関連する非機能要件（ネットワーク遅延、サーバー可用性、認証セキュリティ等）は現在のコードベースでは適用外である。

### マルチスレッド対応について

`kshootmania.hsp`の先頭にマルチスレッドランタイム（`hsp3mt`）の使用がコメント化されている。現在はシングルスレッドで動作しており、マルチスレッド化は将来的な拡張の選択肢として残されている。
