SAVE機能の概要

概要

SAVE機能は、ゲームデータの永続化を担当する機能群です。 プレイヤーの進行状況を安全に保存・読み込みし、データの整合性を保証します。

主要機能

データ管理

操作

機能

SAVE

ゲーム進行データの保存

LOAD

保存されたデータの読み込み

DELETE

不要なセーブデータの削除

セーブスロット

  • 3つのスロット: プレイヤーは最大3つのセーブデータを管理可能

  • スロット情報表示: 各スロットの作成日時・プレイ時間を表示

  • 上書き確認: 既存データへの上書き時に確認ダイアログ表示

データ保護

  • 暗号化保存: AES暗号化によるデータ改ざん防止

  • 整合性チェック: 読み込み時のデータ検証

  • バックアップ機能: 自動バックアップによるデータ保護

技術仕様

アーキテクチャ

SAVE機能は3層構造で実装されています：

  1. Controller層 (common/save/*.py)

  2. Service層 (common/save/service/*.py)

  3. Component層 (暗号化・ファイル操作)

データ形式

セーブデータ構造:
- ヘッダー情報（タイムスタンプ、バージョン）
- プレイヤーデータ（レベル、所持アイテム）
- ゲーム進行状況（現在位置、フラグ状態）
- 設定情報（キー設定、音量）

ファイル構成

save/
├── save.dat          # 暗号化されたセーブデータファイル
└── backup/           # 自動バックアップフォルダ
    ├── save_001.dat  # スロット1のバックアップ
    ├── save_002.dat  # スロット2のバックアップ
    └── save_003.dat  # スロット3のバックアップ

暗号化仕様

  • 暗号化方式: AES-128-EAX

  • キー長: 128ビット（16バイト固定）

  • モード: EAX（認証付き暗号化）

  • 認証タグ: 可変長（メタデータで記録）

  • NONCE: 自動生成・可変長管理

  • 完全性: 認証タグによる改ざん検証（復号化時に自動検証）

データフロー

保存処理

ゲームデータ
     ↓
SAVE Controller（保存要求受付）
     ↓
SAVE Service（データ変換・検証）
     ↓
暗号化Component（AES暗号化）
     ↓
ファイルシステム（永続化）

読み込み処理

ファイルシステム
     ↓
復号化Component（AES復号化）
     ↓
SAVE Service（データ検証・変換）
     ↓
SAVE Controller（ゲームへデータ提供）
     ↓
ゲーム状態復元

関連ファイル

Controller層

  • common/save/action.py - セーブ・ロード操作処理

  • common/save/display.py - セーブ画面描画

  • common/save/sound.py - 操作音再生

  • common/save/status.py - 画面遷移管理

Service層

  • common/save/service/action.py - データ操作ロジック

  • common/save/service/display.py - 画面表示制御

  • common/save/service/sound.py - 音声制御

  • common/save/service/status.py - 状態管理

Component層

表示コンポーネント

  • common/save/service/component/displayScreenManager.py - 画面描画管理コンポーネント

    • クラス: DisplayScreenManager

    • 主要メソッド:

      • blit() -> bool - 画面への画像描画

        • None チェック（screen / img / pos）

        • pygame.error / MemoryError / Exception の多段ハンドリング

        • ハンドラの戻り値（True/False）をそのまま返却

        • ハンドラ自体が例外を起こした場合のみ recovery_error パスへ

    • 実装詳細:

      • dataclass(frozen=True) による不変オブジェクト

      • 抽象クラス AbstractScreenComponent の共通エラーハンドラを使用

  • common/save/service/component/displayTextManager.py - テキスト描画管理コンポーネント

    • クラス: DisplayTextManager

    • 主要メソッド:

      • blit() -> bool - フォントレンダリングと画面描画

        • None チェック（screen / font / text / pos）

        • pygame.error / MemoryError / Exception を個別ログ出力

        • 成功時は False、エラー時は True を返却

  • common/save/service/component/displayRequestValidator.py - 表示リクエスト検証コンポーネント

    • クラス: RequestValidator

    • 主要メソッド:

      • raise_if_invalid() -> None - リクエスト属性の一括検証

        • 全属性の存在・None・型チェック

        • 不正な場合は ValueError を raise

サウンドコンポーネント

  • common/save/service/component/soundChannelManager.py - 音声チャンネル管理コンポーネント

    • クラス: SoundChannelManager

    • 主要メソッド:

      • start() -> None - 音声再生開始

        • volume / mp3_path の妥当性検証

        • チャンネル有効性チェック後に再生

        • 失敗時は Exception を raise

      • stop() -> None - 音声再生停止

        • hasattr によるチャンネル確認

        • pygame.error / Exception をログ出力してもみ消す

    • 実装詳細:

      • dataclass(frozen=True) による不変オブジェクト

      • 抽象クラス AbstractSoundManager を継承

  • common/save/service/component/soundChannelCheck.py - 音声チャンネル状態確認コンポーネント

    • クラス: SoundChannelCheck

    • 主要メソッド:

      • can_sound_start() -> bool - 再生開始可否の判定

        • _has_channel_available が True

        • _channel_index が RELEASED_CHANNEL_INDEX

        • _channel が None、の全条件を満たす場合に True を返却

  • common/save/service/component/soundRequestValidator.py - サウンドリクエスト検証コンポーネント

    • クラス: RequestValidator

    • 主要メソッド:

      • raise_if_invalid() -> None - リクエスト属性の一括検証

        • bool属性 11件（save/load/delete タッチ状態等）を検証

        • int属性 2件（volume / channel_index）を検証

        • channel 属性の型検証

        • sound_list 属性の存在・型検証

暗号化・復号化処理

  • common/save/aes.py - AES-EAX暗号化コンポーネント

    • クラス: Aes

    • 主要メソッド:

      • encrypt(text: str) -> bytes - テキスト暗号化

        • AES-EAX モード採用

        • NONCE自動生成

        • 認証タグ付き（改ざん検出可能）

        • 戻り値形式: [tagLen:4bytes][tag][nonceLen:4bytes][nonce][cipherText]

      • decrypt(datalist: list) -> str - テキスト復号化

        • 暗号化データから認証タグ・NONCE・暗号文を抽出

        • 完全性検証後に復号化

        • 改ざん検出時は例外発生

    • 実装詳細:

      • pycryptodome ライブラリ使用

      • EAX モード（認証付き暗号化）

      • 自動デバッグログ出力機能

      • エラー発生時の空バイト列返却

高速化処理

  • pyd/save.cp311-win_amd64.pyd - Cython実装のセーブ処理エンジン

    • 用途: 大規模ゲームデータの高速化

    • インターフェース: pyd.save モジュールとして import

    • 処理対象:

      • バイナリシリアライズ

      • チャンク単位での処理

      • メモリ効率的な大規模データ対応

共通機能

  • common/common.py - 全体共通機能

エラーハンドリング

想定エラー

エラー種別

対応

ファイル破損

バックアップからの自動復旧

暗号化失敗

エラーログ出力・ユーザー通知

容量不足

古いバックアップの自動削除

権限エラー

管理者権限での再試行

復旧手順

  1. 自動復旧: バックアップファイルからの自動復元

  2. 手動復旧: ユーザーによるバックアップ選択復元

  3. 初期化: 全データ消失時の新規作成

今後の拡張予定

  • クラウド同期: オンラインストレージとの同期機能

  • エクスポート機能: セーブデータの外部出力

  • インポート機能: 外部セーブデータの取り込み

  • 圧縮機能: より効率的なデータ保存

  • マルチプロファイル: ユーザー別のセーブデータ管理