f8-features-storage-workflow

---
name: f8-features-storage-workflow
description: Use when implementing, documenting, or troubleshooting Storage workflows in F8Framework, including local persistence, user-scoped keys, AES encryption, Gzip compression, generic collections, and common Unity value types.
---

# Storage Feature Workflow

> **⚠️ IMPORTANT**: Before using this feature, you **MUST** formally initialize F8Framework in the launch sequence. Ensure `ModuleCenter.Initialize(this);` has run first, then create the required module, for example `FF8.Storage = ModuleCenter.CreateModule<StorageManager>();`.

## Use this skill when

- The task is about local save/load, persistence, storage paths, or per-user save data.
- The user asks about `FF8.Storage`, `StorageManager`, AES encryption, compression, or file-based save operations.
- The task needs storage examples, troubleshooting guidance, or docs updates.

## Path resolution

1. Prefer runtime source under `Assets/F8Framework/Runtime/Storage`.
2. Prefer examples under `Assets/F8Framework/Tests/Storage`.
3. If docs need updates, keep these files aligned:
   - `Assets/F8Framework/Tests/Storage/DemoStorage.cs`
   - `Assets/F8Framework/Tests/Storage/README.md`
   - `Assets/F8Framework/Tests/Storage/README_EN.md`

## Sources of truth

- Runtime module: `Assets/F8Framework/Runtime/Storage/StorageManager.cs`
- Storage tests and docs: `Assets/F8Framework/Tests/Storage`

## Key classes

| Class | Role |
|-------|------|
| `StorageManager` | Core storage module, accessed via `FF8.Storage`. |
| `StorageManager.Settings` | Runtime storage configuration. |
| `Util.OptimizedAES` | AES configuration used by `StorageManager`. |

## Initialization checklist

1. Initialize module center.
2. Create `StorageManager` before first storage access.
3. Configure storage before any dependent read/write.
4. If user-isolated keys are required, call `SetUser()` first.
5. Call `Save()` after writes in `File` mode.

## API quick reference

```csharp
FF8.Storage.Configure(new StorageManager.Settings
{
    location = StorageManager.Location.File,
    directory = StorageManager.Directory.PersistentDataPath,
    defaultFilePath = "Save/PlayerData.json",
    compressionType = StorageManager.CompressionType.Gzip,
    encryption = new Util.OptimizedAES(key: "AES_Key", iv: null)
});

FF8.Storage.SetUser("User_10001");

// Primitive types
FF8.Storage.SetString("nickname", "F8Player", user: true);
FF8.Storage.SetInt("coins", 2560);
FF8.Storage.SetFloat("music_volume", 0.75f);
FF8.Storage.SetBool("guide_finished", true);

// Extended numeric types
FF8.Storage.SetChar("grade", 'S');
FF8.Storage.SetByte("byte_value", 128);
FF8.Storage.SetShort("short_value", 1024);
FF8.Storage.SetLong("long_value", 9876543210L);
FF8.Storage.SetDouble("double_value", 12.3456789d);
FF8.Storage.SetDecimal("decimal_value", 99.99m);
FF8.Storage.SetSByte("sbyte_value", -12);
FF8.Storage.SetUShort("ushort_value", 65530);
FF8.Storage.SetUInt("uint_value", 1234567890U);
FF8.Storage.SetULong("ulong_value", 1234567890123456789UL);

// Enum and tuple
FF8.Storage.SetEnum("save_mode", SaveMode.Hardcore);
FF8.Storage.SetValueTuple("tuple2", (1, "tuple"));
FF8.Storage.SetValueTuple("tuple7", (1, 2, 3, 4, 5, 6, 7));

// Object and collections
FF8.Storage.SetObject("profile", profile);
FF8.Storage.Set("int_array", new[] { 1, 2, 3, 4 });
FF8.Storage.SetList("string_list", new List<string> { "A", "B", "C" });
FF8.Storage.SetDictionary("map", new Dictionary<int, string> { { 1, "one" } });
FF8.Storage.SetQueue("queue", new Queue<int>(new[] { 10, 20, 30 }));
FF8.Storage.SetHashSet("hashset", new HashSet<string> { "fire", "ice" });
FF8.Storage.SetStack("stack", new Stack<int>(new[] { 7, 8, 9 }));
FF8.Storage.SetRectangularArray("grid", new int[,] { { 1, 2 }, { 3, 4 } });
FF8.Storage.SetJaggedArray("jagged", new int[][] { new[] { 1, 2 }, new[] { 3, 4, 5 } });

// Unity types currently exposed by StorageManager.cs
FF8.Storage.SetVector2("vector2", new Vector2(1.5f, 2.5f));
FF8.Storage.SetVector3("vector3", new Vector3(3f, 4f, 5f));
FF8.Storage.SetVector4("vector4", new Vector4(6f, 7f, 8f, 9f));
FF8.Storage.SetVector2Int("vector2int", new Vector2Int(10, 11));
FF8.Storage.SetVector3Int("vector3int", new Vector3Int(12, 13, 14));
FF8.Storage.SetQuaternion("rotation", Quaternion.Euler(15f, 30f, 45f));
FF8.Storage.SetColor("color", new Color(0.1f, 0.2f, 0.3f, 1f));
FF8.Storage.SetColor32("color32", new Color32(10, 20, 30, 255));
FF8.Storage.SetMatrix4x4("matrix", Matrix4x4.identity);
FF8.Storage.SetBounds("bounds", new Bounds(Vector3.zero, Vector3.one * 2));
FF8.Storage.SetRect("rect", new Rect(5f, 10f, 100f, 50f));
FF8.Storage.SetRectOffset("rect_offset", new RectOffset(1, 2, 3, 4));
FF8.Storage.SetLayerMask("layer_mask", (LayerMask)(1 << 8));

// Save / remove / clear
FF8.Storage.Save();
FF8.Storage.Save("Save/PlayerData.backup.json");
FF8.Storage.Remove("coins", filePath: "Save/PlayerData.backup.json");
FF8.Storage.Clear("Save/TempPlayerData.json");
```

## Supported categories in current StorageManager.cs

- Storage backends:
  - `PlayerPrefs`
  - `File`
  - `Resources` (read-only at runtime)
- Compression:
  - `None`
  - `Gzip`
- Primitive APIs:
  - `string`, `int`, `float`, `bool`
  - `char`, `byte`, `short`, `long`, `double`, `decimal`
  - `sbyte`, `ushort`, `uint`, `ulong`
- Generic helpers:
  - `Get<T>/Set<T>`
  - `GetObject<T>/SetObject<T>`
  - `GetEnum<TEnum>/SetEnum<TEnum>`
  - `GetValueTuple/SetValueTuple` for 1 to 7 items
- Collections:
  - arrays
  - `List`
  - `Dictionary`
  - `Queue`
  - `HashSet`
  - `Stack`
  - rectangular arrays
  - jagged arrays
- Unity types currently surfaced by `StorageManager`:
  - `Vector2`
  - `Vector3`
  - `Vector4`
  - `Vector2Int`
  - `Vector3Int`
  - `Quaternion`
  - `Color`
  - `Color32`
  - `Matrix4x4`
  - `Bounds`
  - `Rect`
  - `RectOffset`
  - `LayerMask`

## Workflow

1. Confirm framework initialization and module creation order.
2. Confirm storage backend and file path strategy.
3. Configure `StorageManager.Settings`.
4. Set user scope if required.
5. Prefer typed APIs for primitive and Unity value types.
6. Use `SetObject/GetObject` for plain data classes.
7. Use collection helpers for lists, maps, queues, stacks, and arrays.
8. Call `Save()` after writes when using file storage.
9. If behavior differs in build vs editor, inspect whether the type relies on LitJson reflection for object deserialization.

## Build-time caution

- Unity built-in structs serialized through LitJson `SetObject/GetObject` may behave differently in player builds if deserialization falls back to reflection-based property assignment.
- If a Unity type works in editor but fails in build, prefer one of these:
  - store it via a dedicated typed API already exposed by `StorageManager`
  - convert it to a plain DTO with primitive fields before `SetObject`
  - store it as explicit primitive components instead of relying on LitJson object reflection

## Common troubleshooting

| Problem | Likely cause | Recommended fix |
|--------|--------------|-----------------|
| Data not persisted | `Save()` was not called in file mode | Call `Save()` after writes |
| User data overlaps | `SetUser()` missing before user-scoped keys | Set user id first |
| Read/write mismatch | Storage configured after first access | Configure before any storage usage |
| Decryption fails | AES key changed between sessions | Keep encryption config stable |
| Queue or Stack shape is wrong | LitJson collection support mismatch | Check `JsonMapper.g.cs` collection handling |
| Unity type works in editor but fails in build | Reflection-based value-type deserialization | Use DTO or primitive-component storage |

## Output checklist

- Storage backend chosen.
- Path strategy defined.
- Compression choice defined.
- Encryption choice defined.
- User scope handled if needed.
- Example code updated if docs changed.
- Build-time risks called out when Unity value types rely on LitJson reflection.