# 機能設計書 83-言語設定

## 概要

本ドキュメントは、K-ShootManiaにおけるJapanese/English/Korean/簡体字中国語/繁体字中国語の5言語切替機能の設計を記述する。オプション設定画面のページ0(画面設定)の設定項目(selnow=3)として提供される。

### 本機能の処理概要

**業務上の目的・背景**：K-ShootManiaは国際的に利用される音楽ゲームであり、多様な言語環境のプレイヤーに対応する必要がある。言語設定機能により、UI上のラベルやメッセージを母国語で表示可能にし、ユーザビリティを向上させる。

**機能の利用シーン**：オプション設定画面のページ0でselnow=3を選択し、左右キーで言語を切り替える。切り替え時に即座にUIテキストが更新され、Esc押下でconfig.iniに保存される。

**主要な処理内容**：
1. curlang変数(言語インデックス)の増減操作
2. clang変数(言語名文字列)の更新
3. *refreshlangサブルーチンによる言語テキストファイルの再読み込み
4. lang配列への多言語テキストの展開
5. config.iniへのcurrentlang設定値の保存

**関連システム・外部連携**：lang/ディレクトリ配下の言語テキストファイル({言語名}.txt)

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

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 8 | オプション設定画面 | 主画面 | curlang/clang変数によるJapanese/English/Korean/簡体字中国語/繁体字中国語の5言語切替 |

## 機能種別

設定変更 / テキスト管理

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| curlang | int | Yes | 言語インデックス（0〜langlist長-1） | 0以上、langlist長未満 |
| langlist | string配列 | Yes | 利用可能言語のファイル名リスト | lang/内のテキストファイル |

### 入力データソース

- オプション設定画面上の左右キー操作
- config.iniのcurrentlang設定値
- lang/ディレクトリの言語テキストファイル一覧

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| clang | string | 現在の言語名（例: "Japanese", "English"） |
| curlang | int | 現在の言語インデックス |
| lang | string配列 | 全UIテキストデータ |

### 出力先

- config.ini（currentlang設定値）
- 画面表示（全UIテキストの即時更新）

## 処理フロー

### 処理シーケンス

```
1. 左キー押下時（pagenow=0, selnow=3）
   ├─ curlang-- (最小0でクランプ)
   ├─ clang = getpath(langlist.curlang, 1)で言語名取得
   └─ gosub *refreshlang で言語テキスト再読み込み
2. 右キー押下時
   ├─ curlang++ (最大langlist長-1でクランプ)
   ├─ clang更新
   └─ gosub *refreshlang
3. 表示
   └─ clang値をテキスト表示（例: "Japanese"）
4. Esc押下時
   └─ *saveconfigでcurrentlang=clangをconfig.iniに保存
```

### フローチャート

```mermaid
flowchart TD
    A[selnow=3選択] --> B{左右キー?}
    B -->|左| C[curlang-- クランプ0]
    B -->|右| D[curlang++ クランプmax]
    C --> E[clang更新]
    D --> E
    E --> F[*refreshlang呼び出し]
    F --> G[UI全テキスト更新]
    G --> H{Esc押下?}
    H -->|No| B
    H -->|Yes| I[config.ini保存]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-83-01 | 言語インデックス範囲制限 | curlang < 0の場合0にクランプ、curlang >= length(langlist)の場合length(langlist)-1にクランプ | 左右キー操作時 |
| BR-83-02 | 単一言語時の無効化 | length(langlist) <= 1の場合、矢印表示を無効化(stat2=3) | 言語ファイルが1つのみの場合 |
| BR-83-03 | 言語名の取得 | getpath(langlist.curlang, 1)でファイル名から拡張子を除いた名前を取得 | 言語変更時 |
| BR-83-04 | デフォルト言語 | clang="Japanese"がデフォルト値、存在しない場合はlanglist.0にフォールバック | 起動時 |

### 計算ロジック

特になし。

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

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

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

| 操作 | 対象ファイル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| 設定保存 | config.ini | WRITE | currentlang=clang値の保存 |
| 言語テキスト読込 | lang/{言語名}.txt | READ | 言語テキストファイルの読み込み |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | 言語ファイル不存在 | 指定言語のテキストファイルが存在しない | clang="Japanese"にフォールバック、さらに不存在ならlanglist.0に再フォールバック |

### リトライ仕様

リトライは実装されていない。

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

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

## パフォーマンス要件

言語テキストファイルの読み込みは即座に完了する軽量処理である。

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

特になし。

## 備考

- 利用可能な言語はlang/ディレクトリ内の.txtファイルにより動的に決定される
- 各言語テキストファイルはlang.{画面番号}.{項目番号}の多次元配列形式で管理される
- デフォルト言語: Japanese

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | kshootmania.hsp | `kshootmania.hsp` | **345行目**: clang="Japanese"のデフォルト値、**1259-1282行目**: 言語ファイル読み込みとlanglist/curlang設定 |

**読解のコツ**: lang配列は多次元(lang.{画面}.{項目})で管理される。langlist配列にはlang/ディレクトリ内の全.txtファイル名が格納される。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | option.hsp | `src/scene/option.hsp` | **235-239行目**: 左キーでcurlang--、**386-390行目**: 右キーでcurlang++ |

**主要処理フロー**:
1. **235行目**: `curlang--` と0でのクランプ
2. **238行目**: `clang=getpath(langlist.curlang,1)` で言語名取得
3. **239行目**: `gosub *refreshlang` で言語テキスト再読み込み
4. **526-540行目**: 表示処理（clang値の表示と矢印状態制御）

#### Step 3: config保存を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | kshootmania.hsp | `kshootmania.hsp` | **1444-1445行目**: currentlang=clang値のconfig.ini書き込み |

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

```
on_update_option (option.hsp:1)
    │
    ├─ 左右キー処理 (selnow=3)
    │      ├─ curlang増減
    │      ├─ getpath(langlist.curlang, 1)
    │      └─ gosub *refreshlang (kshootmania.hsp)
    │             └─ noteload clang+".txt" (言語テキストファイル読み込み)
    │
    ├─ 表示処理 (pagenow=0, selnow=3)
    │      └─ *drawconfigitem (clang表示)
    │
    └─ Esc押下時
           └─ *saveconfig
                  └─ confs+="currentlang="+clang
```

### データフロー図

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

左右キー操作        ───> curlang/clang変更         ───> 画面表示更新

lang/{言語名}.txt   ───> *refreshlang               ───> lang配列更新
                         noteload

config.ini          ───> currentlang読み込み        ───> clang設定
(起動時)

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

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| option.hsp | `src/scene/option.hsp` | ソース | オプション設定画面の言語切替操作処理 |
| kshootmania.hsp | `kshootmania.hsp` | ソース | 言語ファイル読み込み・*refreshlang・config保存 |
| config.ini | `config.ini` | 設定 | currentlang設定値の保存 |
| Japanese.txt | `lang/Japanese.txt` | テキスト | 日本語UIテキスト |
| English.txt | `lang/English.txt` | テキスト | 英語UIテキスト |
| Korean.txt | `lang/Korean.txt` | テキスト | 韓国語UIテキスト |
