LCOV - code coverage report
Current view: top level - save - manager.go Coverage Total Hit
Test: coverage.lcov Lines: 83.8 % 179 150
Test Date: 2026-11-19 00:25:22 Functions: - 0 0

            Line data    Source code
       1              : package save
       2              : 
       3              : import (
       4              :         "encoding/json"
       5              :         "errors"
       6              :         "fmt"
       7              :         "slices"
       8              :         "strings"
       9              :         "time"
      10              : 
      11              :         gc "github.com/kijimaD/ruins/internal/components"
      12              :         w "github.com/kijimaD/ruins/internal/world"
      13              :         "github.com/kijimaD/ruins/internal/world/query"
      14              : )
      15              : 
      16              : const saveDataVersion = "2.0.0"
      17              : 
      18              : const maxAutoSaves = 4
      19              : 
      20              : // autoSavePrefix はオートセーブスロット名の接頭辞
      21              : const autoSavePrefix = "auto_"
      22              : 
      23              : const defaultSaveDir = "./saves"
      24              : 
      25              : var (
      26              :         // errChecksumMissing はセーブデータにチェックサムが無いときに返す
      27              :         errChecksumMissing = errors.New("checksum field is missing: this save data is tampered or from an old version")
      28              :         // errChecksumMismatch はセーブデータのチェックサムが内容と一致しないときに返す
      29              :         errChecksumMismatch = errors.New("checksum mismatch")
      30              :         // errUnsupportedVersion はセーブデータのバージョンが現行と異なるときに返す
      31              :         errUnsupportedVersion = errors.New("unsupported save data version")
      32              :         // errPlayerNameNotFound はセーブデータにプレイヤー名が無いときに返す
      33              :         errPlayerNameNotFound = errors.New("player name not found in save data")
      34              :         // errAutoSave はオートセーブの保存に失敗したときに返す
      35              :         errAutoSave = errors.New("failed to auto save")
      36              :         // errNoSingleton は復元データにシングルトンが無いときに返す
      37              :         errNoSingleton = errors.New("restored data has no singleton entity that holds Dungeon")
      38              :         // errInvalidStageKey は復元したステージキーが不正なときに返す
      39              :         errInvalidStageKey = errors.New("restored stage key is invalid")
      40              : )
      41              : 
      42              : // Option はSerializationManagerの設定を変更する関数
      43              : type Option func(*SerializationManager)
      44              : 
      45              : // WithSaveDir はセーブディレクトリを変更する
      46              : func WithSaveDir(dir string) Option {
      47            1 :         return func(sm *SerializationManager) {
      48            1 :                 sm.saveDirectory = dir
      49            1 :         }
      50              : }
      51              : 
      52              : // SerializationManager は ark-serde ベースのワールドシリアライゼーションを管理する
      53              : type SerializationManager struct {
      54              :         saveDirectory string
      55              : }
      56              : 
      57              : // NewSerializationManager は新しいSerializationManagerを作成する
      58              : func NewSerializationManager(opts ...Option) (*SerializationManager, error) {
      59            1 :         sm := &SerializationManager{
      60            1 :                 saveDirectory: defaultSaveDir,
      61            1 :         }
      62            1 :         for _, opt := range opts {
      63            1 :                 opt(sm)
      64            1 :         }
      65            1 :         if err := sm.initImpl(); err != nil {
      66            1 :                 return nil, err
      67            1 :         }
      68            1 :         return sm, nil
      69              : }
      70              : 
      71              : // GenerateWorldJSON はワールドからJSON文字列を生成する
      72              : func (sm *SerializationManager) GenerateWorldJSON(world w.World) (string, error) {
      73            1 :         worldJSON, err := serializeWorld(world)
      74            1 :         if err != nil {
      75            0 :                 return "", fmt.Errorf("failed to serialize world: %w", err)
      76            0 :         }
      77              : 
      78            1 :         env := saveEnvelope{
      79            1 :                 Version:    saveDataVersion,
      80            1 :                 Timestamp:  time.Now(),
      81            1 :                 PlayTime:   query.GetPlayTime(world).Elapsed(),
      82            1 :                 PlayerName: extractPlayerName(world),
      83            1 :                 World:      worldJSON,
      84            1 :         }
      85            1 :         env.Checksum = checksumOf(&env)
      86            1 : 
      87            1 :         data, err := json.MarshalIndent(env, "", "  ")
      88            1 :         if err != nil {
      89            0 :                 return "", fmt.Errorf("failed to marshal save data: %w", err)
      90            0 :         }
      91            1 :         return string(data), nil
      92              : }
      93              : 
      94              : // storeSaveJSON はJSONを gzip 圧縮してスロットへ書き込む。保存先はプラットフォームごとに違うが、
      95              : // WASM の localStorage が容量に厳しいので全プラットフォーム共通で圧縮する。
      96              : func (sm *SerializationManager) storeSaveJSON(slotName string, jsonData []byte) error {
      97            1 :         compressed, err := gzipBytes(jsonData)
      98            1 :         if err != nil {
      99            0 :                 return err
     100            0 :         }
     101            1 :         return sm.saveDataImpl(slotName, compressed)
     102              : }
     103              : 
     104              : // loadSaveJSON はスロットから読み込み圧縮を解いてJSONバイト列を返す。メタ情報だけを読む
     105              : // 抽出処理もこれを通し、圧縮の有無を呼び出し側が気にせず済むようにする。
     106              : func (sm *SerializationManager) loadSaveJSON(slotName string) ([]byte, error) {
     107            1 :         data, err := sm.loadDataImpl(slotName)
     108            1 :         if err != nil {
     109            1 :                 return nil, err
     110            1 :         }
     111            1 :         return gunzipBytes(data)
     112              : }
     113              : 
     114              : // SaveWorld はワールド全体をファイルに保存する
     115              : func (sm *SerializationManager) SaveWorld(world w.World, slotName string) error {
     116            1 :         jsonData, err := sm.GenerateWorldJSON(world)
     117            1 :         if err != nil {
     118            0 :                 return err
     119            0 :         }
     120            1 :         return sm.storeSaveJSON(slotName, []byte(jsonData))
     121              : }
     122              : 
     123              : // LoadWorldJSON はJSON文字列をファイルから読み込む
     124              : func (sm *SerializationManager) LoadWorldJSON(slotName string) (string, error) {
     125            1 :         data, err := sm.loadSaveJSON(slotName)
     126            1 :         if err != nil {
     127            1 :                 return "", fmt.Errorf("failed to load save data: %w", err)
     128            1 :         }
     129            1 :         return string(data), nil
     130              : }
     131              : 
     132              : // RestoreWorldFromJSON はJSON文字列からワールドを復元する
     133              : func (sm *SerializationManager) RestoreWorldFromJSON(world w.World, jsonData string) error {
     134            1 :         var env saveEnvelope
     135            1 :         if err := json.Unmarshal([]byte(jsonData), &env); err != nil {
     136            1 :                 return fmt.Errorf("failed to unmarshal save data: %w", err)
     137            1 :         }
     138              : 
     139            1 :         if err := validateChecksum(&env); err != nil {
     140            1 :                 return fmt.Errorf("save data validation failed: %w", err)
     141            1 :         }
     142              : 
     143            1 :         if env.Version != saveDataVersion {
     144            1 :                 return fmt.Errorf("%w: %s", errUnsupportedVersion, env.Version)
     145            1 :         }
     146              : 
     147              :         // 本番ワールドを破壊する前に、使い捨ての probe ワールドで復元の全工程を検証する。
     148              :         // ark-serde の Deserialize はリセット済みワールドを要求し、途中で失敗しても巻き戻せない。
     149              :         // 先に probe を通し、成功したときだけ本番ワールドへ適用することで、ロード失敗時も
     150              :         // 本番ワールドを無傷で残し、呼び出し側がアプリを継続できるようにする。
     151              :         // 復元を2回走らせるコストは、ロードがゲーム開始時の1回きりの操作なので許容する。
     152            1 :         probe, err := w.InitWorld(&gc.Components{}, world.Resources.Config)
     153            1 :         if err != nil {
     154            0 :                 return fmt.Errorf("failed to create probe world: %w", err)
     155            0 :         }
     156            1 :         if err := restoreInto(probe, env.World, env.PlayTime); err != nil {
     157            1 :                 return err
     158            1 :         }
     159              : 
     160            1 :         return restoreInto(world, env.World, env.PlayTime)
     161              : }
     162              : 
     163              : // restoreInto はリセット済みワールドへ復元の全工程を適用する。deserialize は事前の
     164              : // world.ECS.Reset() を要求する。probe と本番ワールドの両方でこの手順を共有する。
     165              : func restoreInto(world w.World, worldJSON []byte, playTime time.Duration) error {
     166              :         // ark-serdeのDeserializeはリセット済みワールドを要求する
     167            1 :         world.ECS.Reset()
     168            1 : 
     169            1 :         if err := deserializeWorld(world, worldJSON); err != nil {
     170            0 :                 return fmt.Errorf("failed to restore world data: %w", err)
     171            0 :         }
     172              : 
     173              :         // スキップした一時コンポーネントとシングルトン参照を再確立する
     174            1 :         if err := reestablishSingleton(world, playTime); err != nil {
     175            1 :                 return fmt.Errorf("failed to reestablish singleton: %w", err)
     176            1 :         }
     177              : 
     178              :         // 信頼境界。復元したステージキーの整合を検査する
     179            1 :         if err := validateStages(world); err != nil {
     180            1 :                 return fmt.Errorf("failed to validate stages: %w", err)
     181            1 :         }
     182            1 :         return nil
     183              : }
     184              : 
     185              : // LoadWorld はファイルからワールドを復元する
     186              : func (sm *SerializationManager) LoadWorld(world w.World, slotName string) error {
     187            1 :         jsonData, err := sm.LoadWorldJSON(slotName)
     188            1 :         if err != nil {
     189            0 :                 return err
     190            0 :         }
     191            1 :         return sm.RestoreWorldFromJSON(world, jsonData)
     192              : }
     193              : 
     194              : // SaveFileExists はセーブファイルが存在するかチェックする
     195              : func (sm *SerializationManager) SaveFileExists(slotName string) bool {
     196            1 :         return sm.saveFileExistsImpl(slotName)
     197            1 : }
     198              : 
     199              : // GetSaveFileTimestamp はセーブファイルのタイムスタンプを取得する。
     200              : // セーブデータ全体をデシリアライズせず、タイムスタンプだけを抽出する。
     201              : func (sm *SerializationManager) GetSaveFileTimestamp(slotName string) (time.Time, error) {
     202            1 :         data, err := sm.loadSaveJSON(slotName)
     203            1 :         if err != nil {
     204            1 :                 return time.Time{}, err
     205            1 :         }
     206            1 :         var partial struct {
     207            1 :                 Timestamp time.Time `json:"timestamp"`
     208            1 :         }
     209            1 :         if err := json.Unmarshal(data, &partial); err != nil {
     210            1 :                 return time.Time{}, fmt.Errorf("failed to parse save data: %w", err)
     211            1 :         }
     212            1 :         return partial.Timestamp, nil
     213              : }
     214              : 
     215              : // ListSaves はセーブデータの一覧を新しい順に返す
     216              : func (sm *SerializationManager) ListSaves() ([]string, error) {
     217            1 :         names, err := sm.listSavesImpl()
     218            1 :         if err != nil {
     219            1 :                 return nil, err
     220            1 :         }
     221              : 
     222              :         // タイムスタンプを取得できたもののみ返す
     223            1 :         var valid []string
     224            1 :         timestamps := make(map[string]time.Time, len(names))
     225            1 :         for _, name := range names {
     226            1 :                 ts, err := sm.GetSaveFileTimestamp(name)
     227            1 :                 if err != nil {
     228            0 :                         continue
     229              :                 }
     230            1 :                 valid = append(valid, name)
     231            1 :                 timestamps[name] = ts
     232              :         }
     233              : 
     234            1 :         slices.SortFunc(valid, func(a, b string) int {
     235            1 :                 return timestamps[b].Compare(timestamps[a])
     236            1 :         })
     237            1 :         return valid, nil
     238              : }
     239              : 
     240              : // ListAutoSaves はオートセーブスロット名の一覧を返す。
     241              : func (sm *SerializationManager) ListAutoSaves() ([]string, error) {
     242            1 :         saves, err := sm.ListSaves()
     243            1 :         if err != nil {
     244            0 :                 return nil, err
     245            0 :         }
     246            1 :         var autoSaves []string
     247            1 :         for _, name := range saves {
     248            1 :                 if strings.HasPrefix(name, autoSavePrefix) {
     249            1 :                         autoSaves = append(autoSaves, name)
     250            1 :                 }
     251              :         }
     252            1 :         return autoSaves, nil
     253              : }
     254              : 
     255              : // AutoSave はオートセーブを実行する。
     256              : // スロット名の生成、保存、古いオートセーブのローテーションを一括で行う。
     257              : func (sm *SerializationManager) AutoSave(world w.World) error {
     258            1 :         slotName := fmt.Sprintf("%s%d", autoSavePrefix, time.Now().UnixNano())
     259            1 :         if err := sm.SaveWorld(world, slotName); err != nil {
     260            1 :                 return fmt.Errorf("%w: %w", errAutoSave, err)
     261            1 :         }
     262            1 :         if err := sm.rotateAutoSaves(); err != nil {
     263            0 :                 return fmt.Errorf("failed to delete old auto save: %w", err)
     264            0 :         }
     265            1 :         return nil
     266              : }
     267              : 
     268              : // rotateAutoSaves はオートセーブを最大件数まで削減する。
     269              : // 古い順に削除して maxAutoSaves 件を保持する。
     270              : func (sm *SerializationManager) rotateAutoSaves() error {
     271            1 :         autoSaves, err := sm.ListAutoSaves()
     272            1 :         if err != nil {
     273            0 :                 return err
     274            0 :         }
     275              : 
     276            1 :         if len(autoSaves) <= maxAutoSaves {
     277            1 :                 return nil
     278            1 :         }
     279              : 
     280            1 :         for _, name := range autoSaves[maxAutoSaves:] {
     281            1 :                 if err := sm.deleteSaveImpl(name); err != nil {
     282            0 :                         return fmt.Errorf("failed to prune auto save %s: %w", name, err)
     283            0 :                 }
     284              :         }
     285            1 :         return nil
     286              : }
     287              : 
     288              : // GetSavePlayerName はセーブデータからプレイヤー名を取得する。
     289              : // セーブデータ全体をデシリアライズせず、envelopeのメタ情報だけを読む。
     290              : func (sm *SerializationManager) GetSavePlayerName(slotName string) (string, error) {
     291            1 :         data, err := sm.loadSaveJSON(slotName)
     292            1 :         if err != nil {
     293            1 :                 return "", err
     294            1 :         }
     295            1 :         var partial struct {
     296            1 :                 PlayerName string `json:"playerName"`
     297            1 :         }
     298            1 :         if err := json.Unmarshal(data, &partial); err != nil {
     299            0 :                 return "", fmt.Errorf("failed to parse save data: %w", err)
     300            0 :         }
     301            1 :         if partial.PlayerName == "" {
     302            1 :                 return "", errPlayerNameNotFound
     303            1 :         }
     304            1 :         return partial.PlayerName, nil
     305              : }
     306              : 
     307              : // GetSavePlayTime はセーブデータから累積プレイ実時間を取得する。
     308              : // セーブデータ全体をデシリアライズせず、envelopeのメタ情報だけを読む。0は新規開始直後の正常値なので
     309              : // エラー扱いにしない。
     310              : func (sm *SerializationManager) GetSavePlayTime(slotName string) (time.Duration, error) {
     311            1 :         data, err := sm.loadSaveJSON(slotName)
     312            1 :         if err != nil {
     313            0 :                 return 0, err
     314            0 :         }
     315            1 :         var partial struct {
     316            1 :                 PlayTime time.Duration `json:"playTime"`
     317            1 :         }
     318            1 :         if err := json.Unmarshal(data, &partial); err != nil {
     319            0 :                 return 0, fmt.Errorf("failed to parse save data: %w", err)
     320            0 :         }
     321            1 :         return partial.PlayTime, nil
     322              : }
     323              : 
     324              : // validateChecksum はセーブデータのチェックサムを検証する
     325              : func validateChecksum(env *saveEnvelope) error {
     326            1 :         if env.Checksum == "" {
     327            1 :                 return errChecksumMissing
     328            1 :         }
     329            1 :         expected := checksumOf(env)
     330            1 :         if env.Checksum != expected {
     331            1 :                 return fmt.Errorf("%w: expected %s, got %s; data may be tampered",
     332            1 :                         errChecksumMismatch, expected, env.Checksum)
     333            1 :         }
     334            1 :         return nil
     335              : }
        

Generated by: LCOV version 2.0-1