feat: initial commit

Author: aarthificial

.docfx/.gitignore

@@ -0,0 +1,4 @@
+/api/
+/_site/
+/node_modules/
+/_exported_templates/

.docfx/.prettierrc

@@ -0,0 +1,8 @@
+{
+  "bracketSpacing": false,
+  "singleQuote": true,
+  "printWidth": 80,
+  "trailingComma": "all",
+  "arrowParens": "avoid",
+  "proseWrap": "always"
+}

.docfx/CNAME

@@ -0,0 +1 @@
+safekeeper.aarthificial.com

.docfx/docfx.json

@@ -0,0 +1,93 @@
+{
+  "metadata": [
+    {
+      "src": [
+        {
+          "src": "..",
+          "files": [".project/Aarthificial.Safekeeper.csproj"]
+        }
+      ],
+      "dest": "api/runtime",
+      "includePrivateMembers": false,
+      "disableGitFeatures": false,
+      "disableDefaultFilter": false,
+      "noRestore": false,
+      "namespaceLayout": "flattened",
+      "memberLayout": "samePage",
+      "allowCompilationErrors": false
+    },
+    {
+      "src": [
+        {
+          "src": "..",
+          "files": [".project/Aarthificial.Safekeeper.Editor.csproj"]
+        }
+      ],
+      "dest": "api/editor",
+      "includePrivateMembers": false,
+      "disableGitFeatures": false,
+      "disableDefaultFilter": false,
+      "noRestore": false,
+      "namespaceLayout": "flattened",
+      "memberLayout": "samePage",
+      "allowCompilationErrors": false
+    }
+  ],
+  "build": {
+    "globalMetadata": {
+      "_lang": "en",
+      "_appFaviconPath": "images/favicon.svg",
+      "_appLogoPath": "images/logo.svg",
+      "_appLogoDarkPath": "images/logo-dark.svg",
+      "_appBannerUrl": "https://safekeeper.aarthificial.com/images/banner.png",
+      "_appName": "Safekeeper",
+      "_appTitle": "Safekeeper",
+      "_appFooter": "Made with <a href=\"https://dotnet.github.io/docfx\">docfx</a></span>",
+      "_enableSearch": true,
+      "_gitContribute": {
+        "repo": "https://github.com/aarthificial-gamedev/safekeeper",
+        "branch": "main",
+        "apiSpecFolder": ".project/apispec"
+      }
+    },
+    "content": [
+      {
+        "files": ["api/**.yml"]
+      },
+      {
+        "files": ["editor/index.md", "runtime/index.md"],
+        "src": "docs/api",
+        "dest": "api"
+      },
+      {
+        "files": ["docs/**.md", "docs/**/toc.yml", "toc.yml"],
+        "exclude": ["docs/api/**", "docs/index.md"]
+      },
+      {
+        "files": ["index.md"],
+        "src": "docs",
+        "dest": "."
+      }
+    ],
+    "resource": [
+      {
+        "files": ["images/**", "CNAME"]
+      }
+    ],
+    "overwrite": [
+      {
+        "files": ["docs/api/*.md"],
+        "exclude": ["docs/api/runtime/index.md", "docs/api/editor/index.md"]
+      }
+    ],
+    "output": "_site",
+    "globalMetadataFiles": [],
+    "fileMetadataFiles": [],
+    "template": ["default", "modern", "template"],
+    "xref": ["https://normanderwan.github.io/UnityXrefMaps/xrefmap.yml"],
+    "xrefService": ["https://xref.docs.microsoft.com/query?uid={uid}"],
+    "postProcessors": [],
+    "keepFileLink": false,
+    "disableGitFeatures": false
+  }
+}

.docfx/docs/api/editor/index.md

@@ -0,0 +1 @@
+# Editor API

.docfx/docs/api/runtime/index.md

@@ -0,0 +1 @@
+# Runtime API

.docfx/docs/concepts.md

@@ -0,0 +1,155 @@
+# Basic concepts
+
+To understand how Safekeeper works, it's important to think about where the save
+data is stored.
+
+The following diagram illustrates the complete process of first loading the data
+and then saving it back:
+
+```mermaid
+sequenceDiagram
+    participant P as Persistent Storage
+    participant M as Memory
+    participant G as Game State
+    P->>M: Load(SaveMode.PersistentOnly)
+    Note over P,M: Fetching the data
+    M->>G: Load(SaveMode.MemoryOnly)
+    G->>M: Save(SaveMode.MemoryOnly)
+    M->>P: Save(SaveMode.PersistentOnly)
+    Note over P,M: Committing the data
+```
+
+### Persistent storage
+
+The persistent storage is the place where the actual save data is stored. It can
+be a file on the disk, a browser's local storage, a cloud, etc. Once the data is
+stored here, it will persist even after the game is closed. From the player's
+perspective, the game has been saved only if it has been committed to the
+persistent storage.
+
+### Memory
+
+The memory is a staging area for our save data. When saving the game state we
+start by serializing it into the memory. The game can then continue as usual
+while the data is asynchronously committed to the persistent storage.
+
+### Game state
+
+As the name suggests, the game state is the current state of our game as
+represented by game objects. Once the save data is loaded into the memory, we
+can deserialize it and apply the values to the objects in the scene.
+
+## Saving and loading
+
+In the diagram above, `loading` means moving the save data from left to right.
+Analogically, `saving` means moving the date in the opposite direction. Note
+that we don't need to always go all the way. For example, sometimes it may be
+useful to save the data only in the memory.
+
+Imagine the following scenario: The player is in `Scene A` and knocks over a
+vase. They then leave `Scene A` and move to `Scene B`. We'd like to store the
+information about the vase so that when the player returns to `Scene A` it's in
+the same state they left it in. At the same time, our game uses a checkpoint
+system, where the game is saved only in key moments of the story. We don't want
+to save it each time the player switches scenes.
+
+In this case, saving the game only in the memory would be a good solution. When
+the player returns to `Scene A`, we can load the data from the memory and apply
+it to the vase. But only commit it to the persistent storage when the player
+reaches a checkpoint.
+
+Additionally, we can allow the player to go back to the previous checkpoint by
+purging the in-memory data and loading it again from the persistent storage.
+
+## Save Controllers
+
+In Safekeeper, each save slot is represented by an instance of the
+[`SaveControllerBase`](xref:Aarthificial.Safekeeper.SaveControllerBase) class.
+It serves as a handle to the underlying data and provides methods to
+[save](<xref:Aarthificial.Safekeeper.SaveControllerBase.Save(Aarthificial.Safekeeper.SaveMode)>),
+[load](<xref:Aarthificial.Safekeeper.SaveControllerBase.Load(Aarthificial.Safekeeper.SaveMode)>),
+and [clear](xref:Aarthificial.Safekeeper.SaveControllerBase.Delete) the slot.
+
+When instantiating a new save controller, you need to provide it with an
+[`ISaveLoader`](xref:Aarthificial.Safekeeper.Loaders.ISaveLoader). The loader is
+responsible for communicating with the persistent storage. Safekeeper comes with
+a few built-in loaders, but you can also implement your own:
+
+- [`FileSaveLoader`](xref:Aarthificial.Safekeeper.Loaders.FileSaveLoader) -
+  Loads and saves the data to a file on the disk using Unity's persistent
+  storage path.
+- [`DummySaveLoader`](xref:Aarthificial.Safekeeper.Loaders.DummySaveLoader) -
+  Does nothing. Useful for testing.
+
+After the save controller is instantiated, you need to initialize it by calling
+the [`Initialize`](xref:Aarthificial.Safekeeper.SaveControllerBase.Initialize)
+method. This is an asynchronous operation, so it may take a while for the
+controller to be ready. You can await the returned task or check its status by
+reading the
+[`IsLoading`](xref:Aarthificial.Safekeeper.SaveControllerBase.IsLoading)
+property.
+
+> [!NOTE]
+>
+> The controller uses a semaphore so its safe to call other methods before the
+> initialization is complete. They will be queued and executed once the
+> controller is ready.
+
+## Save data
+
+Once the save controller has been initialized and the persistent data has been
+fetched for the first time, you can access the in-memory data by reading the
+[`Data`](xref:Aarthificial.Safekeeper.SaveControllerBase.Data) property.
+
+It provides a few method for reading and writing the data, similarly to Unity's
+`JsonUtility`:
+
+```csharp
+class StoredData {
+    public int health;
+    public int mana;
+}
+
+var location = new SaveLocation("global", "player");
+
+// Reading the data as a new instance:
+var data = controller.Data.Read<StoredData>(location);
+
+// Reading the data into an existing instance:
+controller.Data.Read(location, data);
+
+// Writing the data:
+controller.Data.Write(location, data);
+```
+
+### Save locations
+
+In order to read and write the data, we need to specify the
+[`SaveLocation`](xref:Aarthificial.Safekeeper.SaveLocation). It's a simple
+structure that contains two strings: `chunkId` and `objectId`. For
+organizational purposes, objects store in the save data are grouped into chunks.
+This allows us to reuse Unity's [`GlobalObjectId`][GlobalObjectId] to
+automatically generate unique locations for our objects.
+
+If you want to automatically generate the location for a component, add
+[`ObjectLocationAttribute`](xref:Aarthificial.Safekeeper.ObjectLocationAttribute)
+to a serialized `SaveLocation` field:
+
+```csharp
+public class MyComponent : MonoBehaviour {
+  [ObjectLocation]
+  public SaveLocation Location;
+}
+```
+
+For ScriptableObjects, you can use
+[`AssetLocationAttribute`](xref:Aarthificial.Safekeeper.AssetLocationAttribute):
+
+```csharp
+public class MyScriptableObject : ScriptableObject {
+  [AssetLocation("my-assets")]
+  public SaveLocation Location;
+}
+```
+
+[GlobalObjectId]: https://docs.unity3d.com/ScriptReference/GlobalObjectId.html

.docfx/docs/example.md

@@ -0,0 +1,97 @@
+# Full example
+
+Below is a minimal example of a scene manager that uses safekeeper. Presumably,
+this MonoBehaviour is attached to a game object that persists throughout the
+whole game:
+
+```csharp
+public class SceneManager : MonoBehaviour {
+  private SaveControllerBase _controller;
+
+  private void Awake() {
+    _controller = new SaveControllerBase(
+      new FileSaveLoader("slot1")
+    );
+    _controller.Initialize();
+  }
+
+  public IEnumerator LoadScene(string scenePath) {
+    // Save the current state to memory
+    yield return WaitForTask(_controller.Save());
+    // Switch the scene
+    yield return SceneManager.LoadSceneAsync(scenePath);
+    // Load the state from memory
+    yield return WaitForTask(_controller.Load());
+  }
+
+  public IEnumerator SaveGame() {
+    // Save the current state to memory and commit it to the persistent storage
+    yield return WaitForTask(_controller.Save(SaveMode.Full));
+  }
+
+  public IEnumerator ResetGame() {
+    // Reset memory with the data from the persistent storage
+    yield return WaitForTask(_controller.Load(SaveMode.PersistentOnly));
+    // Reload the scene
+    yield return SceneManager.LoadSceneAsync(
+      SceneManager.GetActiveScene().path
+    );
+    // Load the state from memory
+    yield return WaitForTask(_controller.Load());
+  }
+
+  private IEnumerator WaitForTask(Task task) {
+    while (!task.IsCompleted) {
+      yield return null;
+    }
+
+    if (task.IsFaulted) {
+      ExceptionDispatchInfo.Capture(task.Exception).Throw();
+    }
+  }
+}
+```
+
+With this setup, you can easily save the state of your game by implementing the
+[`ISaveStore`](xref:Aarthificial.Safekeeper.Stores.ISaveStore) interface and
+registering it with the
+[`SaveStoreRegistry`](xref:Aarthificial.Safekeeper.Stores.SaveStoreRegistry):
+
+```csharp
+public class SavedTransform : MonoBehaviour, ISaveStore {
+  private class StoredData {
+    public Vector3 position;
+    public Quaternion rotation;
+  }
+
+  [ObjectLocation]
+  [SerializeField]
+  private SaveLocation _location;
+  private StoredData _data = new();
+
+  public void OnEnable() {
+    SaveStoreRegistry.Register(this);
+  }
+
+  public void OnDisable() {
+    SaveStoreRegistry.Unregister(this);
+  }
+
+  // OnLoad will be invoked right after the scene is loaded.
+  // Before `Start` but after `OnEnable`.
+  public void OnLoad(SaveControllerBase save) {
+    if (save.Data.Read(_location, _data)) {
+      transform.position = _data.position;
+      transform.rotation = _data.rotation;
+    }
+  }
+
+  // OnLoad will be invoked right before the scene in unloaded or whenever
+  // the game is saved.
+  public void OnSave(SaveControllerBase save) {
+    _data.position = transform.position;
+    _data.rotation = transform.rotation;
+    save.Data.Write(_location, data);
+  }
+}
+```