Skip to content

Commit

Permalink
Clarify
Browse files Browse the repository at this point in the history
  • Loading branch information
@Shinmera
Shinmera committed Feb 28, 2024
1 parent 4690ff2 commit 3dac5ba
Show file tree
Hide file tree
Showing 2 changed files with 6 additions and 4 deletions.
4 changes: 2 additions & 2 deletions docs/save-data.html
View file
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
<!DOCTYPE html><html><head><title>Trial / Save Data</title><meta property="og:image" content="https://repository-images.githubusercontent.com/54314855/81c55af6-b2c4-45f0-b66d-f29fdd37be7f"><meta property="og:image:alt" content="Most games keep some amount of state between play sessions to track the player's progress. This is separate from the settings. A lot of the time the amount of data to store and the format to best store that in is very heavily dependent on the type of game being made. Sometimes it's a single level number. Sometimes it needs to be complex data structures to store items, placement, story progress etc."><meta property="og:type" content="object"><meta property="og:title" content="Trial / Save Data"><meta property="og:url" content="https://shirakumo.org/docs/trial/save-data.mess.html"><meta property="og:description" content="Most games keep some amount of state between play sessions to track the player's progress. This is separate from the settings. A lot of the time the amount of data to store and the format to best store that in is very heavily dependent on the type of game being made. Sometimes it's a single level number. Sometimes it needs to be complex data structures to store items, placement, story progress etc."></head><body><article><a class="index" href="index.html">Index</a><style>article{max-width:800px;font-size:12pt;font-family:sans-serif;margin:0 auto 3em auto;}article h1{text-align:center;font-size:2em;}article img{margin:0 auto;max-width:100%;}article blockquote{border-left:0.2em solid gray;margin-left:1em;padding-left:1em;}article figcaption{padding:0.2em 1em;background:#E0E0E0;}article code{background:#F0F0F0;padding:0 0.1em;}article .code-block{padding:0.1em 0.5em;overflow-x:auto;}article a.index{display:block;text-decoration:none;text-align:center;font-size:1.1em;background:#151515;border:2px solid #151515;color:#FEFEFE;}article a.index:hover{background:#FEFEFE;color:#151515;}</style><h1 id="save data">Save Data</h1><p>Most games keep some amount of state between play sessions to track the player's progress. This is separate from the <a class="external-link" href="settings.html">settings</a>. A lot of the time the amount of data to store and the format to best store that in is very heavily dependent on the type of game being made. Sometimes it's a single level number. Sometimes it needs to be complex data structures to store items, placement, story progress etc.</p><p>As such, Trial's save-data support is relatively minimal. It provides a general way to preserve and restore data inside a <a class="external-link" href="https://shinmera.github.io/depot">depot</a>, as well as a generic <code>save-file</code> data structure that tracks the most common information, such as who saved in what slot, when, where, how long they've played, and an optional preview image to display in a menu.</p><p>In order to actually define what data to save and how, you should first create a new <code>save-file</code> type. This will also track the version of the save file, ensuring that you can migrate save files over time.</p><code style="display:block" class="code-block" data-language="common lisp"><pre>(defclass my-save-flie (save-file) ())
<!DOCTYPE html><html><head><title>Trial / Save Data</title><meta property="og:image" content="https://repository-images.githubusercontent.com/54314855/81c55af6-b2c4-45f0-b66d-f29fdd37be7f"><meta property="og:image:alt" content="Most games keep some amount of state between play sessions to track the player's progress. This is separate from the settings. A lot of the time the amount of data to store and the format to best store that in is very heavily dependent on the type of game being made. Sometimes it's a single level number. Sometimes it needs to be complex data structures to store items, placement, story progress etc."><meta property="og:type" content="object"><meta property="og:title" content="Trial / Save Data"><meta property="og:url" content="https://shirakumo.org/docs/trial/save-data.mess.html"><meta property="og:description" content="Most games keep some amount of state between play sessions to track the player's progress. This is separate from the settings. A lot of the time the amount of data to store and the format to best store that in is very heavily dependent on the type of game being made. Sometimes it's a single level number. Sometimes it needs to be complex data structures to store items, placement, story progress etc."></head><body><article><a class="index" href="index.html">Index</a><style>article{max-width:800px;font-size:12pt;font-family:sans-serif;margin:0 auto 3em auto;}article h1{text-align:center;font-size:2em;}article img{margin:0 auto;max-width:100%;}article blockquote{border-left:0.2em solid gray;margin-left:1em;padding-left:1em;}article figcaption{padding:0.2em 1em;background:#E0E0E0;}article code{background:#F0F0F0;padding:0 0.1em;}article .code-block{padding:0.1em 0.5em;overflow-x:auto;}article a.index{display:block;text-decoration:none;text-align:center;font-size:1.1em;background:#151515;border:2px solid #151515;color:#FEFEFE;}article a.index:hover{background:#FEFEFE;color:#151515;}</style><h1 id="save data">Save Data</h1><p>Most games keep some amount of state between play sessions to track the player's progress. This is separate from the <a class="external-link" href="settings.html">settings</a>. A lot of the time the amount of data to store and the format to best store that in is very heavily dependent on the type of game being made. Sometimes it's a single level number. Sometimes it needs to be complex data structures to store items, placement, story progress etc.</p><p>As such, Trial's save-data support is relatively minimal. It provides a general way to preserve and restore data inside a <a class="external-link" href="https://shinmera.github.io/depot">depot</a>, as well as a generic <code>save-file</code> data structure that tracks the most common information, such as who saved in what slot, when, where, how long they've played, and an optional preview image to display in a menu.</p><p>In order to actually define what data to save and how, you should first create a new <code>save-file</code> type. This will also track the version of the save file, ensuring that you can migrate save files over time.</p><code style="display:block" class="code-block" data-language="common lisp"><pre>(defclass my-save-file (save-file) ())
(defmethod version ((file my-save-file)) 1)
(defmethod save-version-type ((version (eql 1))) 'my-save-file)
(defmethod save-version-type ((default (eql T))) 'my-save-file)</pre></code><p>With this we have a new save-file type and a way to decode its version. We've also set it as the default version to use when constructing new saves. Now for the decoding.</p><code style="display:block" class="code-block" data-language="common lisp"><pre>(defmethod load-save-data ((file my-save-file) (depot depot:depot))
Expand All @@ -9,4 +9,4 @@
(:decode (depot score)
(setf +score+ score))
(:encode (depot)
(list +score+)))</pre></code><p>This will simply store the hypothetical <code>+score+</code> variable and set it to the loaded value. <code>:decode</code> expects a destructuring-lambda-list, which <code>:encode</code> should return in the same form, so you can store any Lisp value that is readable. This should suffice for a majority of cases. However, since you still also have access to the <code>depot</code> you can also store auxiliary entries or do whatever else necessary.</p><p>In order to list the available save files, simply use <code>list-save-files</code>. This will perform a &quot;minimal load&quot; of the save file, only reading out its metadata without actually decoding it. You can then call <code>load-save-data</code> to actually restore its state. Similarly, you can invoke <code>store-save-data</code> to store the current state. <code>store-save-data</code> can also be passed a fresh path to construct a new save file entirely, rather than updating the existing one.</p><p>Every save file has a unique <code>id</code> that distinguishes it from every other save file. In the storage, each save file however is only distinguished by its <code>slot</code>. Meaning that a save file with the same <code>slot</code> as another will replace it when stored, but will have a different <code>id</code>.</p><p>Setting the save file's <code>image</code> to <code>T</code> or some other parameter suitable for <code>save-image</code> prior to calling <code>store-save-data</code> will generate and store that as a preview image, with <code>T</code> simply referring to the current scene.</p><p>The save file's <code>save-time</code> is automatically updated when stored, but the <code>play-duration</code> must be updated by you, in order to accurately track how much time the player has spent on the save file.</p><p>Finally each save file also keeps a <code>username</code> which can be used to let the user identify the save file for themselves in some way. It defaults to the system's <code>username</code>.</p></article></body></html><link rel="stylesheet" href="highlight-lisp.css"><script type="text/javascript" src="highlight-lisp.js"></script><script type="text/javascript">[...document.querySelectorAll('[data-language="common lisp"] pre')].map(HighlightLisp.highlight_element);</script>
(list +score+)))</pre></code><p>This will simply store the hypothetical <code>+score+</code> variable and set it to the loaded value. <code>:decode</code> expects a destructuring-lambda-list, which <code>:encode</code> should return in the same form, so you can store any Lisp value that is readable. This should suffice for a majority of cases. However, since you still also have access to the <code>depot</code> you can also store auxiliary entries or do whatever else necessary.</p><p>In order to list the available save files, simply use <code>list-save-files</code>. This will perform a &quot;minimal load&quot; of the save file, only reading out its metadata without actually decoding it. You can then call <code>load-save-data</code> to actually restore its state. Similarly, you can invoke <code>store-save-data</code> to store the state. The actual save data is stored where suitable depending on the platform Trial is running under. On PCs this is as a file within the <code>config-directory</code>.</p><p>Every save file has a unique <code>id</code> that distinguishes it from every other save file. In the storage, each save file however is only distinguished by its <code>slot</code>. Meaning that a save file with the same <code>slot</code> as another will replace it when stored, but will have a different <code>id</code>.</p><p>Setting the save file's <code>image</code> to <code>T</code> or some other parameter suitable for <code>save-image</code> prior to calling <code>store-save-data</code> will generate and store that as a preview image, with <code>T</code> simply referring to the current scene.</p><p>The save file's <code>save-time</code> is automatically updated when stored, but the <code>play-duration</code> must be updated by you, in order to accurately track how much time the player has spent on the save file.</p><p>Finally each save file also keeps a <code>username</code> which can be used to let the user identify the save file for themselves in some way. It defaults to the system's <code>username</code>.</p><p>If you want to control the file's metadata precisely, you can simply create an instance of your desired version's respective type. You can also pass a slot name directly to <code>load-save-data</code> or <code>store-save-data</code>; in the latter case a new save-file instance is created and automatically, relying on the default <code>save-version-type</code>.</p></article></body></html><link rel="stylesheet" href="highlight-lisp.css"><script type="text/javascript" src="highlight-lisp.js"></script><script type="text/javascript">[...document.querySelectorAll('[data-language="common lisp"] pre')].map(HighlightLisp.highlight_element);</script>
6 changes: 4 additions & 2 deletions docs/save-data.mess
View file
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ As such, Trial's save-data support is relatively minimal. It provides a general
In order to actually define what data to save and how, you should first create a new ``save-file`` type. This will also track the version of the save file, ensuring that you can migrate save files over time.

:: common lisp
(defclass my-save-flie (save-file) ())
(defclass my-save-file (save-file) ())
(defmethod version ((file my-save-file)) 1)
(defmethod save-version-type ((version (eql 1))) 'my-save-file)
(defmethod save-version-type ((default (eql T))) 'my-save-file)
Expand Down Expand Up @@ -36,7 +36,7 @@ As mentioned, often you won't need to store terribly much or complex data. In th

This will simply store the hypothetical ``+score+`` variable and set it to the loaded value. ``:decode`` expects a destructuring-lambda-list, which ``:encode`` should return in the same form, so you can store any Lisp value that is readable. This should suffice for a majority of cases. However, since you still also have access to the ``depot`` you can also store auxiliary entries or do whatever else necessary.

In order to list the available save files, simply use ``list-save-files``. This will perform a "minimal load" of the save file, only reading out its metadata without actually decoding it. You can then call ``load-save-data`` to actually restore its state. Similarly, you can invoke ``store-save-data`` to store the current state. ``store-save-data`` can also be passed a fresh path to construct a new save file entirely, rather than updating the existing one.
In order to list the available save files, simply use ``list-save-files``. This will perform a "minimal load" of the save file, only reading out its metadata without actually decoding it. You can then call ``load-save-data`` to actually restore its state. Similarly, you can invoke ``store-save-data`` to store the state. The actual save data is stored where suitable depending on the platform Trial is running under. On PCs this is as a file within the ``config-directory``.

Every save file has a unique ``id`` that distinguishes it from every other save file. In the storage, each save file however is only distinguished by its ``slot``. Meaning that a save file with the same ``slot`` as another will replace it when stored, but will have a different ``id``.

Expand All @@ -45,3 +45,5 @@ Setting the save file's ``image`` to ``T`` or some other parameter suitable for
The save file's ``save-time`` is automatically updated when stored, but the ``play-duration`` must be updated by you, in order to accurately track how much time the player has spent on the save file.

Finally each save file also keeps a ``username`` which can be used to let the user identify the save file for themselves in some way. It defaults to the system's ``username``.

If you want to control the file's metadata precisely, you can simply create an instance of your desired version's respective type. You can also pass a slot name directly to ``load-save-data`` or ``store-save-data``; in the latter case a new save-file instance is created and automatically, relying on the default ``save-version-type``.

0 comments on commit 3dac5ba

Please sign in to comment.