From 1d0c86909ff5f04b8a063bb6a07c09c2ae97a3e0 Mon Sep 17 00:00:00 2001 From: thepaperpilot Date: Fri, 18 Mar 2022 22:47:55 -0500 Subject: [PATCH] Added a persistence page to the guide --- docs/.vitepress/config.js | 3 ++- docs/guide/persistence.md | 11 +++++++++++ docs/guide/reactivity.md | 6 ------ 3 files changed, 13 insertions(+), 7 deletions(-) create mode 100644 docs/guide/persistence.md diff --git a/docs/.vitepress/config.js b/docs/.vitepress/config.js index 0bf76cab..d2bbd3da 100644 --- a/docs/.vitepress/config.js +++ b/docs/.vitepress/config.js @@ -56,7 +56,8 @@ module.exports = { { text: "Layers", link: "/guide/layers" }, { text: "Features", link: "/guide/features" }, { text: "Coercable Components", link: "/guide/coercable" }, - { text: "Reactivity", link: "/guide/reactivity" } + { text: "Reactivity", link: "/guide/reactivity" }, + { text: "Persistence", link: "/guide/persistence" } ] }, { diff --git a/docs/guide/persistence.md b/docs/guide/persistence.md new file mode 100644 index 00000000..b010eedc --- /dev/null +++ b/docs/guide/persistence.md @@ -0,0 +1,11 @@ +# Persistence + +Persistence refers to data that is saved, so that it _persists_ when the user closes the tab and opens it again in the future. + +In Profectus, this is handled by creating "persistent refs", which act like [refs](./reactivity.md) but whose value is stored in an object that gets saved to localStorage. Other than that you can treat them like any other ref - when adding the layer, any persistent refs will automatically have their values updated to the ones saved in localStorage. If there isn't a saved value, it'll use the default value passed to the persistent ref constructor. + +Many features in Profectus, such as upgrades, milestones, and challenges, internally have persistent refs to save things like whether the upgrade has been purchased, the milestone achieved, or the challenge completed. Creators can also create their own custom persistent refs to store any arbitrary (but serializable) data they need - that means Numbers (including big numbers), strings, booleans, or objects containing only serializable values. Another notable function is the resource constructor. If you pass a default value into its contructor, it will automatically create a persistent ref for that resource. If you pass in a ref, it will NOT make the ref persistent. + +It's important for saving and loading these properties for these refs to be in a well known location. This is implemented based on the location of the persistent ref within a layer. That means its important that **all persistent refs are located within the object returned by the createLayer options function**. If a persistent ref is not within that object, it will NOT be saved and loaded - regardless of whether its a persistent ref within a feature, one you manually created, or otherwise. + +Additionally, this structure should typically remain consistent between project versions. If a value is in a new location, it will not load the value from localStorage correctly. This is exacerbated if two values swap places, such as when an array is re-ordered. In the event a creator changes this structure anyways, the [fixOldSave](./project-entry.md#fixoldsave) function can be used to migrate the old player save data to the new structure expected by the current version of the project. diff --git a/docs/guide/reactivity.md b/docs/guide/reactivity.md index 56254a3f..97d4a8dc 100644 --- a/docs/guide/reactivity.md +++ b/docs/guide/reactivity.md @@ -6,12 +6,6 @@ With a proper IDE, such as [Visual Studio Code](./setup#visual-studio-code-setup Vue's reactivity is probably the "quirkiest" part of Profectus, and not even the documentation makes all of those quirks clear. It is recommend to read [this thread](https://github.com/vuejs/docs/issues/849) of common misconceptions around Vue reactivity. -## Persistent - -Some refs are "persistent" refs. Most notably, any time you use the `persistent()` function it will be a persistent ref. You access these the same way you would any other ref, but keep in mind its value will be saved and loaded automatically. - -All persistent refs _must_ be included in a layer object in order for persistence to work. Since many [features](./features) will create persistent refs internally its recommended to include all of them just to be safe. - ## Computable Most properties on features will accept `Computable` values. Computable values can either be a raw value, a ref to the value, or a function that returns the value. In the lattermost case it will be wrapped in `computed`, turning it into a ref. The feature type will handle it being a ref or a raw value by using `unref` when accessing those values. With type hints, your IDE should correctly identify these values as refs or raw values so you can treat them as the types they actually are.