# 機能設計書 85-マスターボリューム設定

## 概要

本ドキュメントは、K-ShootManiaにおけるマスターボリュームの調整機能の設計を記述する。オプション設定画面のページ0(画面設定)のselnow=8として提供される。

### 本機能の処理概要

**業務上の目的・背景**：音楽ゲームにおいて、環境に応じた音量調整は基本的な要件である。マスターボリュームはゲーム全体の音量を一括で制御し、BGM・効果音・プレビュー音全てに影響する。プレイヤーが自分の環境に合った音量でプレイできるようにするための機能である。

**機能の利用シーン**：オプション設定画面のページ0でselnow=8を選択し、左右キーで5%刻みのマスターボリュームを調整する。変更は即座にオプションBGMの音量に反映される。

**主要な処理内容**：
1. mastervol変数の5%刻み増減（0〜100の範囲）
2. BASS_ChannelSetAttributeによるオプションBGM音量へのリアルタイム反映
3. config.iniへのmastervol値の保存
4. 各シーンでのBASSチャンネルへの音量適用（double(mastervol)/100）

**関連システム・外部連携**：BASS Audio Library（音量制御）

**権限による制御**：特になし。全プレイヤーが変更可能。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 8 | オプション設定画面 | 主画面 | mastervol変数による0-100%範囲でのマスターボリューム調整（5%刻み） |

## 機能種別

設定変更 / オーディオ制御

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| mastervol | int | Yes | マスターボリューム値(0-100) | 0以上100以下、5刻み |

### 入力データソース

- オプション設定画面上の左右キー操作
- config.iniのmastervol設定値

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| mastervol | int | マスターボリューム値(0-100) |

### 出力先

- config.ini（mastervol設定値）
- BASS Audio Libraryチャンネル属性（即時音量反映）

## 処理フロー

### 処理シーケンス

```
1. 左キー押下時（pagenow=0, selnow=8）
   └─ mastervol = max(mastervol-5, 0)
2. 右キー押下時
   └─ mastervol = min(mastervol+5, 100)
3. 表示
   └─ str(mastervol) + "%"のテキスト表示
4. 音量反映
   └─ *volactiveサブルーチンでBASSチャンネルにdouble(mastervol)/100を適用
5. Esc押下時
   └─ *saveconfigでconfig.iniに保存
```

### フローチャート

```mermaid
flowchart TD
    A[selnow=8選択] --> B{左右キー?}
    B -->|左| C[mastervol = max{mastervol-5, 0}]
    B -->|右| D[mastervol = min{mastervol+5, 100}]
    C --> E[表示更新]
    D --> E
    E --> F[BASS音量反映]
    F --> G{Esc押下?}
    G -->|No| B
    G -->|Yes| H[config.ini保存]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-85-01 | 音量範囲制限 | 0(ミュート)〜100(最大)の範囲に制限 | 左右キー操作時 |
| BR-85-02 | 5%刻み | 1回の操作で5%ずつ増減 | 左右キー操作時 |
| BR-85-03 | リアルタイム反映 | 変更即座にオプションBGMの音量に反映 | 値変更時 |
| BR-85-04 | デフォルト値 | mastervol=100(最大音量) | 初回起動時 |
| BR-85-05 | BASS音量変換 | double(mastervol)/100で0.0-1.0に正規化してBASSに適用 | 音量適用時 |

### 計算ロジック

**BASS音量値変換**:
```
bass_volume = double(mastervol) / 100
// 例: mastervol=75 → bass_volume=0.75
```

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

本機能はデータベースを使用しない。

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

| 操作 | 対象ファイル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| 設定保存 | config.ini | WRITE | mastervol値の保存 |

## エラー処理

### エラーケース一覧

特になし。値はmax/min関数により常に有効範囲内に収まる。

### リトライ仕様

なし。

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

config.iniへの保存は*saveconfigサブルーチンによる一括書き込み。

## パフォーマンス要件

音量変更は即座にBASSチャンネル属性に反映され、遅延なく音量が変化する。

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

特になし。

## 備考

- mastervolはゲーム全体の全オーディオチャンネルに適用される
- BASS_ChannelSetAttributeの属性値2がボリューム属性を示す
- *volactiveサブルーチンは各シーンのメインループから呼ばれ、現在再生中の全チャンネルにmastervolを適用する

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | kshootmania.hsp | `kshootmania.hsp` | **298行目**: mastervol=100のデフォルト値 |

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | option.hsp | `src/scene/option.hsp` | **252-253行目**: 左キーでmax(mastervol-5,0)、**403-404行目**: 右キーでmin(mastervol+5,100) |

**主要処理フロー**:
1. **252行目**: `mastervol=max(mastervol-5,0)` - 左キーで5%減
2. **403行目**: `mastervol=min(mastervol+5,100)` - 右キーで5%増
3. **567-574行目**: 表示処理（str(mastervol)+"%"、左右矢印状態）
4. **60-62行目**: オプションBGMへの音量適用

#### Step 3: 音量適用を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | kshootmania.hsp | `kshootmania.hsp` | mastervolが参照される全箇所（BASS_ChannelSetAttribute呼び出し） |

**主要処理フロー**:
- `BASS_ChannelSetAttribute {channel}, 2, double(mastervol)/100` パターンがゲーム全体で使用

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

```
on_update_option (option.hsp:1)
    │
    ├─ 左右キー処理 (selnow=8)
    │      └─ mastervol = max/min(mastervol +/- 5, 0/100)
    │
    ├─ 表示処理 (pagenow=0)
    │      └─ *drawconfigitem (音量%表示)
    │
    ├─ 音量反映
    │      └─ BASS_ChannelSetAttribute optionbgmid, 2, double(mastervol)/100
    │
    └─ Esc押下時
           └─ *saveconfig → config.ini保存
```

### データフロー図

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

左右キー操作        ───> mastervol変更(0-100)      ───> 画面表示更新

mastervol           ───> double(mastervol)/100      ───> BASS音量適用
                                                         (全チャンネル)

config.ini          ───> mastervol読み込み          ───> mastervol設定
(起動時)                  (568-569行目)

Escキー押下         ───> *saveconfig               ───> config.ini更新
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| option.hsp | `src/scene/option.hsp` | ソース | マスターボリューム設定の操作処理 |
| kshootmania.hsp | `kshootmania.hsp` | ソース | 変数初期化・config読み込み・保存・*volactive |
| config.ini | `config.ini` | 設定 | mastervol設定値の保存 |
