# 機能設計書 121-Base64エンコード

## 概要

本ドキュメントは、KShootManiaにおけるBase64エンコード・デコード機能の設計を記述する。マシン語レベルで実装されたBase64変換処理により、バイナリデータと文字列間の相互変換を提供する。

### 本機能の処理概要

本機能は、バイナリデータをBase64形式の文字列にエンコードする処理、およびBase64形式の文字列をバイナリデータにデコードする処理を提供する。HSP (Hot Soup Processor) のモジュールとして実装されており、マシン語埋め込みによる高速な変換を実現している。

**業務上の目的・背景**：ゲーム内で扱うバイナリデータ(スコアデータ、設定データ等)をテキストベースの形式で安全に保存・転送するために、Base64エンコード・デコード機能が必要となる。特に、IRサーバーとの通信やデータの永続化において、バイナリデータを文字列として扱う場面で使用される。

**機能の利用シーン**：IR(インターネットランキング)サーバーへのスコア送信時のデータエンコード、設定値の保存・読み込み時のバイナリデータ変換など、バイナリデータをテキスト形式で扱う必要がある場面全般で利用される。

**主要な処理内容**：
1. Base64Encode: バイナリデータを受け取り、Base64文字列に変換して返す
2. Base64Decode: Base64文字列を受け取り、元のバイナリデータに復元して返す
3. マシン語(x86)による高速な変換処理の実行

**関連システム・外部連携**：IRサーバーとの通信においてデータのエンコード・デコードに使用される可能性がある。

**権限による制御**：特になし。全てのコンテキストから呼び出し可能。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | - | - | 直接的な画面関連なし（ユーティリティモジュール） |

## 機能種別

データ変換処理（バイナリ⇔テキスト相互変換）

## 入力仕様

### 入力パラメータ

#### Base64Encode

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| src | var | Yes | エンコード対象のバイナリデータ（変数参照） | なし |
| size | int | Yes | エンコード対象のデータサイズ（バイト数） | 0以上の整数 |
| dest | var | Yes | エンコード結果を格納する変数（変数参照） | 事前にsdimで十分なサイズを確保すること |

#### Base64Decode

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| src | var | Yes | デコード対象のBase64文字列（変数参照） | 有効なBase64文字列であること |
| size | int | Yes | デコード対象のデータサイズ（バイト数） | 0以上の整数 |
| dest | var | Yes | デコード結果を格納する変数（変数参照） | 事前にsdimで十分なサイズを確保すること |

### 入力データソース

呼び出し元モジュールから直接渡されるバイナリデータまたはBase64文字列。

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| dest (Encode時) | var | Base64エンコードされた文字列。改行コード(\r\n)が76文字ごとに挿入される |
| dest (Decode時) | var | デコードされたバイナリデータ |
| stat (戻り値) | int | 処理結果のサイズ(callfuncの戻り値) |

### 出力先

呼び出し元モジュールの変数（dest引数で指定された変数に格納）

## 処理フロー

### 処理シーケンス

```
1. Base64Encode処理
   └─ Base64文字テーブル("ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/")を初期化
   └─ マシン語バッファ(base64enc)を確保し、x86マシンコードを配置
   └─ VirtualProtectで実行可能属性を付与
   └─ callfuncでマシン語コードを直接実行
   └─ 3バイトずつ読み取り、4文字のBase64文字に変換
   └─ 76文字ごとに改行(\r\n)を挿入
   └─ 末尾にパディング('=')を付与

2. Base64Decode処理
   └─ Base64文字テーブルを初期化
   └─ マシン語バッファ(base64dec)を確保し、x86マシンコードを配置
   └─ VirtualProtectで実行可能属性を付与
   └─ callfuncでマシン語コードを直接実行
   └─ 4文字のBase64文字を3バイトのバイナリデータに変換
   └─ パディング('=')の処理
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B[Base64文字テーブル初期化]
    B --> C[マシン語バッファ確保]
    C --> D[VirtualProtect: 実行可能属性付与]
    D --> E[パラメータ配列構築]
    E --> F[callfunc: マシン語コード実行]
    F --> G{エンコード or デコード?}
    G -->|エンコード| H[3バイト→4文字変換]
    G -->|デコード| I[4文字→3バイト変換]
    H --> J[76文字ごとに改行挿入]
    J --> K[パディング付与]
    I --> L[パディング除去]
    K --> M[結果をdestに格納]
    L --> M
    M --> N[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-121-01 | Base64文字セット | A-Z, a-z, 0-9, +, / の64文字を使用 | 全てのエンコード・デコード処理 |
| BR-121-02 | パディング処理 | 入力データが3の倍数でない場合、'='でパディング | エンコード時 |
| BR-121-03 | 改行挿入 | エンコード結果に76文字ごとに\r\nを挿入 | エンコード時 |
| BR-121-04 | メモリ保護変更 | VirtualProtectでPAGE_EXECUTE_READWRITE(0x40)を設定 | マシン語コード実行前 |

### 計算ロジック

- エンコード後のサイズ: ceil(入力サイズ / 3) * 4 + 改行分
- デコード後のサイズ: (入力サイズ / 4) * 3 - パディング分

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

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

該当なし。本機能はデータベースを使用しない純粋なデータ変換処理である。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | メモリ不足 | dest変数のバッファサイズ不足 | 呼び出し元でsdimにより十分なサイズを事前確保 |
| - | 不正Base64 | デコード時に無効な文字が含まれる | マシン語レベルで処理されるため明示的なエラー処理なし |

### リトライ仕様

リトライ処理なし。

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

該当なし。

## パフォーマンス要件

マシン語(x86)による直接実装のため、HSPスクリプトレベルの実装と比較して高速に動作する。

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

- VirtualProtectを使用してメモリの実行可能属性を変更しているため、セキュリティソフトウェアによる検知の可能性がある
- Base64は暗号化ではなくエンコーディングであるため、機密データの保護には別途暗号化(RC4等)と組み合わせる必要がある

## 備考

- 本モジュールはthird_partyフォルダに配置されており、外部ライブラリとして取り込まれたものである
- HSP3のモジュール機能(`#module`/`#global`)を使用して名前空間を分離している
- `xdim`マクロによりメモリ確保と実行可能属性の設定を一括で行っている
- 現時点のコードベースでは、kshootmania.hspおよびkshooteditor.hspからの直接呼び出しは確認されていないが、他のモジュール経由での間接的な使用が想定される

---

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

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

### 推奨読解順序

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

Base64エンコード・デコードで使用される文字テーブルとマシン語バッファの構造を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | mbase64.as | `third_party/mbase64.as` | Base64文字テーブル(11行目)とxdimマクロ(7行目)の定義 |

**読解のコツ**: HSP3の`#module`/`#global`で名前空間が`_machinebase64_`として定義されている。`xdim`マクロは`dim`(メモリ確保)と`VirtualProtect`(実行可能属性付与)を一括で行うカスタムマクロである。

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

Base64Encode/Base64Decodeの2つの命令がエントリーポイントとなる。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | mbase64.as | `third_party/mbase64.as` | Base64Encode命令の定義(9行目)とBase64Decode命令の定義(25行目) |

**主要処理フロー**:
1. **9行目**: `#deffunc Base64Encode var src, int size, var dest` - エンコード命令の定義
2. **11行目**: Base64文字テーブルの初期化
3. **12行目**: `xdim base64enc,54` - マシン語バッファ(54整数=216バイト)の確保と実行可能化
4. **13-21行目**: x86マシン語コードの配置（16進数リテラル）
5. **22行目**: `prm`配列にパラメータ(src, size, dest, base64テーブル)のポインタを格納
6. **23行目**: `callfunc`でマシン語コードを直接実行し、結果を`return`

#### Step 3: マシン語コードの構造を理解する

マシン語コードはx86(32bit)のCDECL呼び出し規約に従っている。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | mbase64.as | `third_party/mbase64.as` | エンコード用マシンコード(13-21行目)、デコード用マシンコード(29-38行目) |

**主要処理フロー**:
- **13行目**: `0x51EC8B55` = `push ebp; mov ebp,esp; push ecx` (関数プロローグ)
- **22行目**: `prm.0 = varptr(src), size, varptr(dest), varptr(base64)` - 4つのパラメータポインタを配列に格納
- **23行目**: `callfunc(prm, varptr(base64enc), 4)` - 4引数でマシン語関数を呼び出し

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

```
呼び出し元モジュール (kshootmania.hsp等)
    |
    +-- Base64Encode (third_party/mbase64.as:9)
    |       |
    |       +-- VirtualProtect (kernel32.dll) ... メモリ属性変更
    |       +-- callfunc ... マシン語コード実行
    |
    +-- Base64Decode (third_party/mbase64.as:25)
            |
            +-- VirtualProtect (kernel32.dll) ... メモリ属性変更
            +-- callfunc ... マシン語コード実行
```

### データフロー図

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

バイナリデータ(src) ----> Base64Encode(マシン語) ---------> Base64文字列(dest)
  + サイズ(size)            |
                           +-- Base64文字テーブル参照
                           +-- 3byte→4char変換
                           +-- 改行挿入・パディング

Base64文字列(src) ------> Base64Decode(マシン語) ---------> バイナリデータ(dest)
  + サイズ(size)            |
                           +-- Base64文字テーブル参照
                           +-- 4char→3byte逆変換
                           +-- パディング除去
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| mbase64.as | `third_party/mbase64.as` | ソース | Base64エンコード・デコード機能の実装本体 |
| kshootmania.hsp | `kshootmania.hsp` | ソース | メインプログラム（モジュールのインクルード元の候補） |
| kshooteditor.hsp | `kshooteditor.hsp` | ソース | 譜面エディタ（モジュールのインクルード元の候補） |
