diff --git a/docs/guide/advanced-concepts/creating-features.md b/docs/guide/advanced-concepts/creating-features.md index 114ec134..413ba42a 100644 --- a/docs/guide/advanced-concepts/creating-features.md +++ b/docs/guide/advanced-concepts/creating-features.md @@ -2,4 +2,4 @@ \# TODO -Because typescript does not emit JS, if a value is supposed to be a function it is impossible to determine if a given function is the intended value or a function that returns the actual value. For this reason it is not recommended for any feature types to include properties that are `Computable`s, and all functions _will_ be wrapped in `computed`. The notable exception to this is [JSX](./coercable#http://localhost:3000/guide/coercable.html#render-functions-jsx), which uses a utility function to mark that a function should not be wrapped. +Because typescript does not emit JS, if a value is supposed to be a function it is impossible to determine if a given function is the intended value or a function that returns the actual value. For this reason it is not recommended for any feature types to include properties that are `Computable`s, and all functions _will_ be wrapped in `computed`. The notable exception to this is [JSX](../important-concepts/coercable#render-functions-jsx), which uses a utility function to mark that a function should not be wrapped. diff --git a/docs/guide/important-concepts/features.md b/docs/guide/important-concepts/features.md index 0610e2d6..7aed9c30 100644 --- a/docs/guide/important-concepts/features.md +++ b/docs/guide/important-concepts/features.md @@ -17,7 +17,7 @@ const addGainUpgrade = createUpgrade(() => ({ The result will be a [lazy proxy](./layers#lazy-proxies) of the feature being created. The feature can then be used throughout the rest of the layer. The main thing to keep in mind when creating features is that they should typically be included in the layer object that gets returned. If a feature has any [persistent refs](./reactivity#persistent) they must be included or else they will not have their values saved and loaded correctly. -While the structure of layers is intentionally left up to the creator, it is recommended to avoid storing them in arrays. If you ever remove an upgrade from an array, or add an upgrade in between others, then it will interfere with the save data of existing users. You can manually fix these issues in [fixOldSave](./project-entry.md#fixoldsave), but it's recommended to avoid the error entirely. +While the structure of layers is intentionally left up to the creator, it is recommended to avoid storing them in arrays. If you ever remove an upgrade from an array, or add an upgrade in between others, then it will interfere with the save data of existing users. You can manually fix these issues in [fixOldSave](../creating-your-project/project-entry.md#fixoldsave), but it's recommended to avoid the error entirely. Since usually you want to access a specific feature, storing them in an object is much more reliable and makes the code easier to read. For things like checking number of upgrades bought, for example, you can still use `Object.values` to get an array of the objects instead. diff --git a/docs/guide/important-concepts/layers.md b/docs/guide/important-concepts/layers.md index efa2b87a..1411da7d 100644 --- a/docs/guide/important-concepts/layers.md +++ b/docs/guide/important-concepts/layers.md @@ -4,7 +4,7 @@ Profectus content is organized into units called "Layers". When displaying conte Each layer is ultimately a collection of different features, and a display function. While there are a couple reserved properties for layers, most of its structure is fully up to the creator. -Layers can be dynamically added or removed at any time, which also allows for effectively disabling or enabling content based on arbitrary conditions. Just make sure [getInitialLayers](./project-entry.md#getinitiallayers) can process the player save data object and determine which layers should be currently active. +Layers can be dynamically added or removed at any time, which also allows for effectively disabling or enabling content based on arbitrary conditions. Just make sure [getInitialLayers](../creating-your-project/project-entry.md#getinitiallayers) can process the player save data object and determine which layers should be currently active. ## Lazy Proxies diff --git a/docs/guide/important-concepts/persistence.md b/docs/guide/important-concepts/persistence.md index b010eedc..06992851 100644 --- a/docs/guide/important-concepts/persistence.md +++ b/docs/guide/important-concepts/persistence.md @@ -8,4 +8,4 @@ Many features in Profectus, such as upgrades, milestones, and challenges, intern 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. +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](../creating-your-project/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/important-concepts/reactivity.md b/docs/guide/important-concepts/reactivity.md index 97d4a8dc..0dd32dd6 100644 --- a/docs/guide/important-concepts/reactivity.md +++ b/docs/guide/important-concepts/reactivity.md @@ -2,7 +2,7 @@ Profectus takes large advantage of Vue's reactivity system. It's recommended to read up on how [refs](https://vuejs.org/guide/essentials/reactivity-fundamentals.html#reactive-variables-with-ref) and [computed](https://vuejs.org/guide/essentials/computed.html) refs work. Ultimately this means that sometimes you'll need to type `.value` to get the actual value of something, but also you are able to pass things around by reference instead of by value. Indeed, it is recommended to only unwrap the actual value when you actually need it. `.value` is guaranteed to be correct and up to date only on the exact moment it is accessed. -With a proper IDE, such as [Visual Studio Code](./setup#visual-studio-code-setup), you should be able to see whether or not something is a ref or not from type hints. If in doubt, you can always wrap the property in an `unref` call. +With a proper IDE, such as [Visual Studio Code](../getting-started/setup#visual-studio-code-setup), you should be able to see whether or not something is a ref or not from type hints. If in doubt, you can always wrap the property in an `unref` call. 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.