From 76362e81e8dc3359b099ea26a6ede96196c58e4f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?David=20N=C3=A9grier?= Date: Mon, 6 Sep 2021 16:06:49 +0200 Subject: [PATCH] Adding a dedicated doc for variables --- docs/maps/api-state.md | 41 +++-------------------------- docs/maps/variables.md | 59 ++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 63 insertions(+), 37 deletions(-) create mode 100644 docs/maps/variables.md diff --git a/docs/maps/api-state.md b/docs/maps/api-state.md index 1cc4f7fb..a8ee5589 100644 --- a/docs/maps/api-state.md +++ b/docs/maps/api-state.md @@ -14,7 +14,7 @@ WA.state.onVariableChange(key : string).subscribe((data: unknown) => {}) : Subsc WA.state.[any property]: unknown ``` -These methods and properties can be used to save, load and track changes in variables related to the current room. +These methods and properties can be used to save, load and track changes in [variables related to the current room](variables.md). Variables stored in `WA.state` can be any value that is serializable in JSON. @@ -63,44 +63,11 @@ that you get the expected type). For security reasons, the list of variables you are allowed to access and modify is **restricted** (otherwise, anyone on your map could set any data). Variables storage is subject to an authorization process. Read below to learn more. -### Declaring allowed keys +## Defining a variable -In order to declare allowed keys related to a room, you need to add **objects** in an "object layer" of the map. - -Each object will represent a variable. - -
-
- -
-
- -The name of the variable is the name of the object. -The object **type** MUST be **variable**. - -You can set a default value for the object in the `default` property. - -### Persisting variables state - -Use the `persist` property to save the state of the variable in database. If `persist` is false, the variable will stay -in the memory of the WorkAdventure servers but will be wiped out of the memory as soon as the room is empty (or if the -server restarts). - -{.alert.alert-info} -Do not use `persist` for highly dynamic values that have a short life spawn. - -### Managing access rights to variables - -With `readableBy` and `writableBy`, you control who can read of write in this variable. The property accepts a string -representing a "tag". Anyone having this "tag" can read/write in the variable. - -{.alert.alert-warning} -`readableBy` and `writableBy` are specific to the "online" version of WorkAdventure because the notion of tags -is not available unless you have an "admin" server (that is not part of the self-hosted version of WorkAdventure). - -Finally, the `jsonSchema` property can contain [a complete JSON schema](https://json-schema.org/) to validate the content of the variable. -Trying to set a variable to a value that is not compatible with the schema will fail. +Out of the box, you cannot edit *any* variable. Variables MUST be declared in the map. +Check the [dedicated variables page](variables.md) to learn how to declare a variable in a map. ## Tracking variables changes diff --git a/docs/maps/variables.md b/docs/maps/variables.md new file mode 100644 index 00000000..17e803d9 --- /dev/null +++ b/docs/maps/variables.md @@ -0,0 +1,59 @@ +{.section-title.accent.text-primary} +# Variables + +Maps can contain **variables**. Variables are piece of information that store some data. In computer science, we like +to say variables are storing the "state" of the room. + +- Variables are shared amongst all players in a given room. When the value of a variable changes for one player, it changes + for everyone. +- Variables are **invisible**. There are plenty of ways they can act on the room, but by default, you don't see them. + +## Declaring a variable + +In order to declare allowed variables in a room, you need to add **objects** in an "object layer" of the map. + +Each object will represent a variable. + +
+
+ +
+
+ +The name of the variable is the name of the object. +The object **type** MUST be **variable**. + +You can set a default value for the object in the `default` property. + +## Persisting variables state + +Use the `persist` property to save the state of the variable in database. If `persist` is false, the variable will stay +in the memory of the WorkAdventure servers but will be wiped out of the memory as soon as the room is empty (or if the +server restarts). + +{.alert.alert-info} +Do not use `persist` for highly dynamic values that have a short life spawn. + +## Managing access rights to variables + +With `readableBy` and `writableBy`, you control who can read of write in this variable. The property accepts a string +representing a "tag". Anyone having this "tag" can read/write in the variable. + +{.alert.alert-warning} +`readableBy` and `writableBy` are specific to the "online" version of WorkAdventure because the notion of tags +is not available unless you have an "admin" server (that is not part of the self-hosted version of WorkAdventure). + +In a future release, the `jsonSchema` property will contain [a complete JSON schema](https://json-schema.org/) to validate the content of the variable. +Trying to set a variable to a value that is not compatible with the schema will fail. + +## Using variables + +There are plenty of ways to use variables in WorkAdventure: + +- Using the [scripting API](api-state.md), you can read, edit or track the content of variables. +- Using the [Action zones](https://workadventu.re/map-building-extra/generic-action-zones.md), you can set the value of a variable when someone is entering or leaving a zone +- By [binding variable values to properties in the map](https://workadventu.re/map-building-extra/variable-to-property-binding.md) +- By [using automatically generated configuration screens](https://workadventu.re/map-building-extra/automatic-configuration.md) to create forms to edit the value of variables + +In general, variables can be used by third party libraries that you can embed in your map to add extra features. +A good example of such a library is the ["Scripting API Extra" library](https://workadventu.re/map-building-extra/about.md)