diff --git a/README.md b/README.md index c40eca6..ae76094 100644 --- a/README.md +++ b/README.md @@ -13,7 +13,7 @@ There are many ways to import the `@workadventure/scripting-api-extra` package. If you only want to use the extra "features", you can directly import the package in your map, by adding a "script" property at the map level, pointing to the "bundled" package: -`script: https://unpkg.com/@workadventure/scripting-api-extra@1.0.0-alpha.2/dist/bundle.js` +`script: https://unpkg.com/@workadventure/scripting-api-extra@^1/dist/bundle.js` Please note that you can change the version number of the package in the URL. @@ -22,181 +22,24 @@ Please note that you can change the version number of the package in the URL. If you are developing your own scripts, you can import the library using NPM. ``` -npm install --save @workadventure/scripting-api-extra@ +npm install --save @workadventure/scripting-api-extra ``` -## Functions +## Table of content -### Utility class to analyze properties +### Features -The JSON map can already be fetched using `WA.room.getTiledMap`. But when it comes to analyzing the JSON map, you are on your own. +- [Doors](docs/doors.md) +- [Bells](docs/bells.md) +- [Generic action zones](docs/generic-action-zones.md) -This library comes with helpers to help you read the map. +### Functions -The `Properties` class can be used to analyze properties (that can be put on a variety of objects in Tiled). +- [`Properties`](docs/functions-properties.md) related functions (utility functions to acces properties...) +- [`Variables`](docs/functions-variables.md) related functions (access variables metadata...) +- [`Layers`](docs/functions-layers.md) related functions (get a list of all layers, find layers boundaries...) -Usage: - -```typescript -const map = await WA.room.getTiledMap(); - -const mapProperties = new Properties(map.properties); - -// getOne fetches the value of the property passed in parameter. -// Note that it will throw an exception if many properties have the same name. -const name = mapProperties.getOne('name') as string; - -// getMany returns an array of values for all properties whose name is passed in parameter. -const scripts = mapProperties.getMany('scripts'); - -// getOneString is the same as getOne except it ensures the value is a string (and throws an exception if it is not) -const name = mapProperties.getOneString('name'); -``` - -### Return a list of all variables defined in the map - -`getAllVariables(): Promise>`: returns a list of all the variables defined in the map. - -Variables are returned as a Map. The key is the name of the variable, the value if an object representing the variable. -You can fetch individual properties defined in Tiled for this variable using this object's `properties` attribute. - -For instance: - -```typescript -import { getAllVariables, VariableDescriptor } from '../VariablesExtra'; - -const variables = await getAllVariables(); -console.log(variables['my_variable'].properties.getOne('persist')); -``` - -```typescript -class VariableDescriptor { - name: string // the name of the variable - properties: Properties // an object representing the properties of the variable -} -``` - -### Return a Map of all layers - -Layers can be nested in group layers. - -The `getLayersMap()` function returns a map of all layers in a uni-dimensional map. -Layers are renamed: if they are in a group layer, the name of the group layer is prepended with a "/" as a separator. -Layers are indexed by name. - -```typescript -const layers = await getLayersMap(); -const mylayer = layers.get('my_layer'); -for (const layer of layers.values()) { - // Iterate over all layers -} -``` - -### Get boundaries of a layer - -`findLayerBoundaries()` can be used to find the boundaries of a given layer. - - - -## Features - -### Changing the value of a variable using an action message in a zone - -`bindVariable`: The name of a variable that will be altered when one enters/leaves the zone -`zone`: You need to define a zone property for the layer that contains `bindVariable`. -`enterValue`: The value the variable will be set to when entering the zone -`leaveValue`: The value the variable will be set to when leaving the zone -`triggerMessage` (optional): You can optionally add a "trigger message". In this case, the message will be displayed when entering the zone and the variable will only change value when the trigger message is activated by pressing the space bar. -`tag` (optional): Only users with the "tag" passed in parameter will be allowed to set the value. (Note: this is only enforced client side and could be circumvented) - -### Doors - -In order to create a door, you need to create a "variable" that will contain the state of the door (so "opened" or "closed"). - -Set the "default" property to "true" (opened by default) or "false" (closed by default). - -Then, add a new "door" boolean property and set it to true. - -Add 2 layers in your map. One will contain the open door, and the other one the closed door. - -Now, add 2 properties to the variable: - -- `openLayer`: this will contain the name of the layer that has the opened door -- `closeLayer`: this will contain the name of the layer that has the closed door - -Note: for both `openLayer` and `closeLayer`, you can input several layer names separated by a new line character. - -Whenever the value of the variable switches from true to false (or the opposite), the door will open or close. - -#### Door sound - -You can add an opening or closing sound to the door by using the `openSound` or `closeSound` properties of the door variable. - -The value of these properties should be a URL to a MP3 file of a sound opening or closing the door. - -- `openSound`: URL of the sound of a door opening -- `closeSound`: URL of the sound of a door closing - -Anybody on the map will hear the sound of the door opening or closing. -If you want to limit the sound to a certain area, you can use the `soundRadius` property. -`soundRadius` is expressed in pixels. If you are further than `soundRadius` pixels from the center of the door, -you will not hear the door opening or closing. Also, the further you are, the fainter will be the sound. - - -### Door step - -To open or close a door, you can define a special "doorstep" layer that will trigger the opening/closing -when the user walks on it. - -You can configure the doorstep to open/close **automatically** or **manually** (by pressing the space key). -You can define special tags a user must have to open/close a door, or even add a code on the door. - -``` -zone: string // Compulsory: the name of a zone -doorVariable: string // The name of the variable holding the state of the door -autoOpen: boolean // True to open automatically. False to force an interaction -autoClose: boolean // True to close automatically when zone is left. False to force an interaction -openTriggerMessage: string // Message to be displayed to open the door -closeTriggerMessage: string // Message to be displayed to close the door -code: string // The code to open the door (clear text, so not very secure) -codeVariable: string // The name of the variable containing the secret code -tag: string // If set, a user needs to have the given tag to open this door. -``` - -Note that if you set both a `tag` and a `code`, the door will open without asking the code for people who have the requested tag. - -### Bells / Knocking on a door - -You can add a bell that will ring automatically or manually when a user walks in a given zone. - -In order to create a bell, you need to create a "variable" that will be used to share the fact the bell is ringing. -The value of the variable has no importance, it is just used to propagate the event that the bell is ringing. - -Add a new "bell" boolean property and set it to true. - -Unlike with classical variables, the position of the variable object is important. The sound will be emitted from this point. - -Then add 2 properties - -- `bellSound`: URL of the sound of the bell ringing (you can also use a knock-knock-knock sound if you have a door :) ) -- `soundRadius` (optional): The radius at which one can hear the sound (expressed in pixels, the sound center being the position of the variable) - -The farther you are from the sound center, the less you will hear the sound. If you don't set any soundRadius, the whole -map will hear the sound. - -Now, we need to define the position on the map from where the bell sound will be triggered. - -Add a tile layer in your map. - -On the layer add those properties: - -- `zone`: (Compulsory) the name of a zone -- `bellVariable`: (Compulsory) the name of the "bell" variable that will be triggered when someone walks on this layer -- `bellPopup`: the name of a square object on an object layer in the map that will display the "Ring" button to ring the bell. If not set, the bell - will ring automatically when a player enters the zone. -- `bellButtonText`: the text to display in the button to ring the bell. Defaults to "Ring" - -### Contributing +## Contributing ```console # install dependencies diff --git a/docs/about.md b/docs/about.md new file mode 100644 index 0000000..c6439e6 --- /dev/null +++ b/docs/about.md @@ -0,0 +1,21 @@ +{.section-title.accent.text-primary} +# About the extended features + +WorkAdventure features can be extended through the use of the [scripting API](https://workadventu.re/map-building/scripting). + +This means anyone can write "scripts" that can be imported in any map and that add new properties to WorkAdventure. +If you are a developer, do not hesitate to have a look at the [scripting API](https://workadventu.re/map-building/scripting) +and to create your own custom properties / features. + +The WorkAdventure team also provides its own scripts that add various features. We put those features +in a common package we call [Scripting API Extra](https://github.com/workadventure/scripting-api-extra). + +In this section, you will find a list of these extended features. + +## Importing the "extended features" + +Because a script is hosting the extended features, you need to import that script explicitly into your map. + +You can do so by adding a "script" property at the top level of your map, pointing to the URL: +`https://unpkg.com/@workadventure/scripting-api-extra@^1/dist/bundle.js` + diff --git a/docs/bells.md b/docs/bells.md new file mode 100644 index 0000000..164a008 --- /dev/null +++ b/docs/bells.md @@ -0,0 +1,82 @@ +{.section-title.accent.text-primary} +# Bells / Knocking on a door + +{.alert.alert-info} +**Important!** To use the "bells" feature, you need to [import the "Scripting API Extra" script in your map](about.md#importing-the-extended-features) + +Bells are usually used next to [doors](doors.md) (even if they can be used independently) + +You can: + +- decide if the bell will ring automatically or by pressing a button +- decide the sound of the bell (or a knocking on the door sound if you prefer) +- decide if the bell can be heard on all the map, or only at a given radius around the bell + +## The bell variable + +In order to create a bell, you need to create a ["variable"](https://workadventu.re/map-building/api-state.md) that will +be used to share the fact the bell is ringing. +The value of the variable has no importance, it is just used to propagate the event that the bell is ringing. + +In order to add a variable, you need to create a "Point" on any "object layer" in your map, in Tiled. + +Unlike with classical variables, the position of the variable object is important. The sound will be emitted from this point. + +- You can give this variable any name. +- The "type" of the object MUST be "variable". +- You MUST define a custom boolean property named `bell`. The "bell" checkbox must be checked. + +Then add 2 properties + +- `bellSound`: URL of the sound of the bell ringing (you can also use a knock-knock-knock sound if you have a door :) ) +- `soundRadius` (optional): The radius at which one can hear the sound (expressed in pixels, the sound center being **the position of the variable**) + +The farther you are from the sound center, the less you will hear the sound. If you don't set any soundRadius, the whole +map will hear the sound. + +The URL of the sound can be absolute or relative. If you choose a relative URL, it is is relative to the map. + +
+ +
The bell variable
+
+ +## The bell display layer + +Now, we need to define the position on the map from where the bell sound can be triggered. + +Add a tile layer in your map. + +On the layer add those properties: + +- `zone` (string): a unique identifier for your bell layer (the need to define this property will be removed in a future version) +- `bellVariable`: (Compulsory) the name of the "bell" variable that will be triggered when someone walks on this layer + +With only those 2 properties, whenever a user walks into the layer, the bell will automatically ring. + +## Adding a bell button + +Of course, most of the time, you want the bell to be triggered by a manual user interaction (pressing the bell button). + +To add this button, you should create a "rectangle" object on any object layer in Tiled. The button will appear within this +rectangle object on the map. + +Give this rectangle object any name. + +
+ +
The bell "popup" rectangle
+
+ +Now, on the bell layer, create 2 properties: + +- `bellPopup`: the name of a rectangle object on the object layer in the map that will display the "Ring" button to ring the bell. +- `bellButtonText`: the text to display in the button to ring the bell. Defaults to "Ring" + +
+ +
Complete list of properties for the bell layer
+
+ +{.alert.alert-info} +**Pro tip:** the `bellButtonText` can contain emojis. So you can use the "bell" emoji in the text: 🔔 diff --git a/docs/doors.md b/docs/doors.md new file mode 100644 index 0000000..2b43611 --- /dev/null +++ b/docs/doors.md @@ -0,0 +1,238 @@ +{.section-title.accent.text-primary} +# Doors + +{.alert.alert-info} +**Important!** To use the "doors" feature, you need to [import the "Scripting API Extra" script in your map](about.md#importing-the-extended-features) + +Doors are extremely customizable in your map. You can: + +- decide to open/close the door automatically or on user interaction +- decide who can operate the door (based on the user's tags) +- lock a door with a digit code +- you can even add a bell (look at the [bell](bell.md) dedicated document) + +In order to create a door, you will need: + +- a tileset containing sprites for the door in an opened and in a closed state +- optionally 2 MP3 files containing the opening and closing sound + +{.alert.alert-info} +Looking for cool door sprites? Checkout out [door sprites by Pipoya on itch.io](https://pipoya.itch.io/pipoya-rpg-tileset-32x32/devlog/222435/add-door-animation) + +Doors are made of 1 variable and 4 layers. We will see how to build one step by step in this document. + +## The open / close layers + +The first step is to add 2 layers on your map. One will contain the opened door and one the closed door. + + + + + + +
+
+
+ +
The layer with the closed door
+
+
+ 		+
+
+ +
The layer with the opened door
+
+
+
+ +{.alert.alert-info} +If you have complex doors that span on several layers, that is fine. + +{.alert.alert-warning} +Do not forget to make the closed door tiles "collidable" (using the `collides` property), otherwise users will be able +to walk through your open door! + +## The door variable + +Then, add a ["variable"](https://workadventu.re/map-building/api-state.md). The variable will control +the "state" of the door and to share that state between the players. If the variable value is `true`, +the door will be open, if it is `false`, the door will be closed. + +In order to add a variable, you need to create a "Point" on any "object layer" in your map, in Tiled. + +
+ +
The door variable
+
+ +- You can give this variable any name. +- The "type" of the object MUST be "variable". +- You MUST define a custom boolean property named `door`. The "door" checkbox must be checked. +- You can set the `default` custom property to `true` (opened by default) or `false` (closed by default). This will be used + the first time a user enters the map. +- You can set the `persist` custom property to `true` if you want to save the state of the door. Otherwise, the door state + will reset to the `default` property when the room is empty. + +Now, add 2 properties to the variable: + +- `openLayer`: this MUST contain the name of the opened door layer +- `closeLayer`: this MUST contain the name of the closed door layer + +{.alert.alert-info} +**Note:** if your door is spanning over several layers, for both the `openLayer` and `closeLayer` properties, you can input +several layer names separated by a new line character. + +### Opening / closing sound + +You can add an opening or closing sound to the door by using the `openSound` or `closeSound` properties of the door variable. + +The value of these properties should be a URL to a MP3 file of a sound opening or closing the door. + +- `openSound`: URL of the sound of a door opening +- `closeSound`: URL of the sound of a door closing + +Anybody on the map will hear the sound of the door opening or closing. + +If you want to limit the sound to a certain area, you can use the `soundRadius` property. +`soundRadius` is expressed in pixels. If you are further than `soundRadius` pixels from the center of the door, +you will not hear the door opening or closing. Also, the further you are, the fainter the sound. + +{.alert.alert-info} +If you are looking for opening/closing door sounds, [FesliyanStudios provides a variety of sounds](https://www.fesliyanstudios.com/royalty-free-sound-effects-download/opening-closing-door-54) + +## Door steps + +So far, our door is controlled by the state of a variable. Unless you are mastering the scripting API, you +need a way to change the "state" of the door variable. This is what "door steps" are for! + +Door steps are layers (usually one in front of the door and one behind) that control the opening / closing of the door. + + + + + + +
+
+
+ +
The front door step
+
+
+ 		+
+
+ +
The back door step
+
+
+
+ +Each door step can have a different set of rules. For instance, you can have the back door step that triggers +automatically the opening of the door, while the front door step requires to enter a code to open the door. + +In order to create a door step, you MUST put the following properties on the doorstep layer: + +- `zone` (string): a unique identifier for your doorstep (the need to define this property will be removed in a future version) +- `doorVariable` (string): the name of the door variable that this door step controls + +Those 2 properties are enough to control the door. + +You should see something similar to the video below: + + + +### Automatically VS manually opening the door + +By default, when a player walks next to the door, a user interaction (pressing SPACE) is required to open or close the +door. + +You can change this behaviour by setting the `autoOpen` and `autoClose` boolean properties on the **door step layer**. + +By setting `autoOpen` to true, the door will automatically open when someone walks in the door step layer. +By setting `autoClose` to true, the door will automatically close when someone walks out of the door step layer. + +
+ +
The autoOpen and autoClose properties
+
+ +
+ + + +{.alert.alert-info} +Because you set the `autoOpen` and `autoClose` properties on the door step (and not on the door variable), +you can have different behaviour depending on the side of the door you are on. You can create doors +that are opening automatically on one side, but that require manual opening on the other side. + +### Configuring the open/close door message + +You can change the message displayed to the user to open / close a door with the `openTriggerMessage` and +`closeTriggerMessage` properties, on the doorstep layer. + +### Limiting who can open/close the door + +You can decide who is allowed to operate the door based on user tags. + +{.alert.alert-info} +User tags is a feature of the "pro" accounts. + +Use the `tag` property on the "door step" layer. In order to operate the door from this layer, the player +will need to have the specified tag. + +
+ +
Only players with the "collaborator" tag can open/close this door
+
+ +{.alert.alert-info} +You set the `tag` property on the door step (and not on the door variable). +You can therefore put the tag variable outside (the door can be opened only by authorized people), but not on the doorstep +inside (people inside can exit the room, whether they have the tag or not) + +### Setting a digital code access on your door + +You can protect your door with a digital access code. + +Putting a code is as simple as adding a `code` property on your door. + + + + + + +
+
+
+ +
The "code" property
+
+
+ 		+
+
+ +
The digital access code
+
+
+
+ +The digital access code will be displayed at the right of the closed door. + +{.alert.alert-warning} +Protection provided by the "code" property is weak. Indeed, the code is stored in the map that is downloaded by the browser. +Therefore, it is quite easy for an attacker to read the code. The digital access code will prevent regular users from +entering your room, but won't stop someone willing to hack your room. + diff --git a/docs/functions-layers.md b/docs/functions-layers.md new file mode 100644 index 0000000..4fa6587 --- /dev/null +++ b/docs/functions-layers.md @@ -0,0 +1,77 @@ +{.section-title.accent.text-primary} +# Layers utility functions + +{.alert.alert-info} +**Important!** To use these functions, you need to [import the "Scripting API Extra"](utils.md#importing-the-utility-functions) library. + +### Return a Map of all layers + +Layers can be nested in group layers. + +The `getLayersMap()` function returns a map of all layers in a uni-dimensional map. + +Layers are **renamed**: if they are in a group layer, the name of the group layer is prepended with a "/" as a separator. + +Layers are indexed by name. + +```typescript +import {getLayersMap} from '@workadventure/scripting-api-extra'; + +const layers = await getLayersMap(); + +// Access a layer directly by name +const mylayer = layers.get('my_layer'); + +// Iterate over all layers +for (const layer of layers.values()) { + // ... +} +``` + +### Get boundaries of a layer + +`findLayerBoundaries` returns the boundaries of a given layer as an object with properties: { top: number, left: number, right: number, bottom: number } + +Numbers are expressed in "tiles", not pixels. + +``` +findLayerBoundaries(layer: ITiledMapTileLayer): { + top: number; + left: number; + right: number; + bottom: number; +} +``` + +Example: + +```typescript +import {getLayersMap, findLayerBoundaries} from '@workadventure/scripting-api-extra'; +import {ITiledMapTileLayer} from "@workadventure/tiled-map-type-guard/dist/ITiledMapTileLayer"; + +const layers = await getLayersMap(); + +const layer = layers.get("my_layer") as ITiledMapTileLayer; + +const boundaries = findLayerBoundaries(layer); +console.log('Top:' , boundaries.top); +console.log('Left:' , boundaries.left); +console.log('Bottom:' , boundaries.bottom); +console.log('Right:' , boundaries.right); +``` + +### Get boundaries of several layers + +If you are looking for the boundaries of several layers at once, you can use the `findLayersBoundaries` variant. + +``` +findLayersBoundaries(layers: ITiledMapTileLayer[]): { + top: number; + left: number; + right: number; + bottom: number; +} +``` + +It will return a square containing all the tiles of all the layers passed in parameters. + diff --git a/docs/functions-properties.md b/docs/functions-properties.md new file mode 100644 index 0000000..f3facac --- /dev/null +++ b/docs/functions-properties.md @@ -0,0 +1,39 @@ +{.section-title.accent.text-primary} +# Tiled properties + +{.alert.alert-info} +**Important!** To use these functions, you need to [import the "Scripting API Extra"](utils.md#importing-the-utility-functions) library. + +In your Tiled map, a number of items can have "properties" (the map itself, layers, tiles, tilesets, objects...). + +The JSON map can be fetched using `WA.room.getTiledMap`. But when it comes to analyzing the JSON map, you are on your own. + +The Scripting API Extra package comes with a useful `Properties` class to analyze these properties. + +Usage: + +```typescript +const map = await WA.room.getTiledMap(); + +const mapProperties = new Properties(map.properties); + +// getOne fetches the value of the property passed in parameter. +const name = mapProperties.get('name') as string; + +// getString is the same as get except it ensures the value is a string (and throws an exception if it is not) +const name = mapProperties.getString('name'); +``` + +Methods available: + +```typescript +class Properties { + get(name: string): string | boolean | number | undefined; // returns the property + getString(name: string): string | undefined; // returns the property (and checks it is a string) + getNumber(name: string): number | undefined; // returns the property (and checks it is a number) + getBoolean(name: string): boolean | undefined; // returns the property (and checks it is a boolean) + mustGetString(name: string): string; // returns the property as a string (throws an Error if not found) + mustGetNumber(name: string): string; // returns the property as a number (throws an Error if not found) + mustGetBoolean(name: string): string; // returns the property as a boolean (throws an Error if not found) +} +``` diff --git a/docs/functions-variables.md b/docs/functions-variables.md new file mode 100644 index 0000000..4dde7ae --- /dev/null +++ b/docs/functions-variables.md @@ -0,0 +1,41 @@ +{.section-title.accent.text-primary} +# Variables metadata + +{.alert.alert-info} +**Important!** To use these functions, you need to [import the "Scripting API Extra"](utils.md#importing-the-utility-functions) library. + +## Return a list of all variables defined in the map + +``` +// returns a list of all the variables defined in the map. +getAllVariables(): Promise> +``` + +Variables are returned as a Map. The key is the name of the variable, the value if an object representing the variable. +You can fetch individual properties defined in Tiled for this variable using this object's `properties` attribute. + +For instance: + +```typescript +import { getAllVariables, VariableDescriptor } from '@workadventure/scripting-api-extra'; + +const variables = await getAllVariables(); +console.log(variables['my_variable'].properties.getOne('persist')); +``` + +Note: the `VariableDescriptor` class returned does not contain the value of the variable itself. It represents the +variable object as defined in the Tiled map. This can be useful to access additional metadata that can be stored +in special properties of the variable, or to access the variable "position" in the map (since a variable is represented +by a "Point" object in a map). + +```typescript +class VariableDescriptor { + // the name of the variable + name: string + // an object representing the properties of the variable + properties: Properties + // The position of the variable + x: number + y: number +} +``` diff --git a/docs/generic-action-zones.md b/docs/generic-action-zones.md new file mode 100644 index 0000000..cf3d212 --- /dev/null +++ b/docs/generic-action-zones.md @@ -0,0 +1,33 @@ +{.section-title.accent.text-primary} +# Action zones + +{.alert.alert-info} +**Important!** To use these action zones, you need to [import the "Scripting API Extra" script in your map](about.md#importing-the-extended-features) + +You can define special zones that will **alter the value of a ["variable"](https://workadventu.re/map-building/api-state.md)** +when walked upon. + +To define such a zone, create a new "tile layer" in Tiled. + +In this layer, add these properties: + +- `zone`: A unique name for this zone +- `bindVariable`: The name of the variable that will be altered when one enters/leaves the zone +- `enterValue`: (optional) The value the variable will be set to when entering the zone +- `leaveValue`: (optional) The value the variable will be set to when leaving the zone + +## User interaction + +By default, as soon as anyone enters or leaves the zone, the value of the variable will be changed. + +Optionally, you can request a user interaction to trigger the change of the value. Use the `triggerMessage` property +to display a message to the player. When the player presses "SPACE", the value of the variable will be changed to `enterValue`. + +## Managing rights + +You can restrict who will trigger an action zone using user **tags**. + +{.alert.alert-info} +User tags is a feature of the "pro" accounts. + +Add a `tag` property on the layer. The variable will only change value if the player walking on the layer has the specified tag. diff --git a/docs/images/autoopen.png b/docs/images/autoopen.png new file mode 100644 index 0000000..3e7315d Binary files /dev/null and b/docs/images/autoopen.png differ diff --git a/docs/images/back_doorstep.png b/docs/images/back_doorstep.png new file mode 100644 index 0000000..bc87303 Binary files /dev/null and b/docs/images/back_doorstep.png differ diff --git a/docs/images/bell_layer.png b/docs/images/bell_layer.png new file mode 100644 index 0000000..12a090a Binary files /dev/null and b/docs/images/bell_layer.png differ diff --git a/docs/images/bell_popup.png b/docs/images/bell_popup.png new file mode 100644 index 0000000..1a5e2c2 Binary files /dev/null and b/docs/images/bell_popup.png differ diff --git a/docs/images/bell_variable.png b/docs/images/bell_variable.png new file mode 100644 index 0000000..3709770 Binary files /dev/null and b/docs/images/bell_variable.png differ diff --git a/docs/images/close_door_layer.png b/docs/images/close_door_layer.png new file mode 100644 index 0000000..23fd74c Binary files /dev/null and b/docs/images/close_door_layer.png differ diff --git a/docs/images/code_property.png b/docs/images/code_property.png new file mode 100644 index 0000000..956a9c2 Binary files /dev/null and b/docs/images/code_property.png differ diff --git a/docs/images/digicode.png b/docs/images/digicode.png new file mode 100644 index 0000000..bbef68d Binary files /dev/null and b/docs/images/digicode.png differ diff --git a/docs/images/door_manual.mp4 b/docs/images/door_manual.mp4 new file mode 100644 index 0000000..526b816 Binary files /dev/null and b/docs/images/door_manual.mp4 differ diff --git a/docs/images/door_variable.png b/docs/images/door_variable.png new file mode 100644 index 0000000..c97b453 Binary files /dev/null and b/docs/images/door_variable.png differ diff --git a/docs/images/doorsteptag.png b/docs/images/doorsteptag.png new file mode 100644 index 0000000..c152c93 Binary files /dev/null and b/docs/images/doorsteptag.png differ diff --git a/docs/images/front_doorstep.png b/docs/images/front_doorstep.png new file mode 100644 index 0000000..954fa21 Binary files /dev/null and b/docs/images/front_doorstep.png differ diff --git a/docs/images/open_door_layer.png b/docs/images/open_door_layer.png new file mode 100644 index 0000000..77bb0f8 Binary files /dev/null and b/docs/images/open_door_layer.png differ diff --git a/docs/images/open_doors_auto.mov b/docs/images/open_doors_auto.mov new file mode 100644 index 0000000..eb40b7b Binary files /dev/null and b/docs/images/open_doors_auto.mov differ diff --git a/docs/images/open_doors_auto.mp4 b/docs/images/open_doors_auto.mp4 new file mode 100644 index 0000000..0af8c85 Binary files /dev/null and b/docs/images/open_doors_auto.mp4 differ diff --git a/docs/menu.php b/docs/menu.php new file mode 100644 index 0000000..ff6d3d4 --- /dev/null +++ b/docs/menu.php @@ -0,0 +1,28 @@ + 'Extended features', + 'url' => '/map-building-extra/about.md', + 'markdown' => 'scripting_api_extra_doc.about', + 'collapse' => true, + 'children' => [ + [ + 'title' => 'Doors', + 'url' => '/map-building-extra/doors.md', + 'markdown' => 'scripting_api_extra_doc.doors' + ], + [ + 'title' => 'Bells', + 'url' => '/map-building-extra/bells.md', + 'markdown' => 'scripting_api_extra_doc.bells' + ], + [ + 'title' => 'Action zones', + 'url' => '/map-building-extra/generic-action-zones.md', + 'markdown' => 'scripting_api_extra_doc.generic-action-zones' + ], + ], +]; diff --git a/docs/menu_functions.php b/docs/menu_functions.php new file mode 100644 index 0000000..7288335 --- /dev/null +++ b/docs/menu_functions.php @@ -0,0 +1,28 @@ + 'Utility functions', + 'url' => '/map-building-extra/utils.md', + 'markdown' => 'scripting_api_extra_doc.utils', + 'collapse' => true, + 'children' => [ + [ + 'title' => 'Properties', + 'url' => '/map-building-extra/functions-properties.md', + 'markdown' => 'scripting_api_extra_doc.functions-properties' + ], + [ + 'title' => 'Variables metadata', + 'url' => '/map-building-extra/functions-variables.md', + 'markdown' => 'scripting_api_extra_doc.functions-variables' + ], + [ + 'title' => 'Layers', + 'url' => '/map-building-extra/functions-layers.md', + 'markdown' => 'scripting_api_extra_doc.functions-layers' + ], + ], +]; diff --git a/docs/utils.md b/docs/utils.md new file mode 100644 index 0000000..998bd6c --- /dev/null +++ b/docs/utils.md @@ -0,0 +1,25 @@ +{.section-title.accent.text-primary} +# About the extended utility functions + +The utility functions described in this section are not part of WorkAdventure core solution. +Instead, they are provided in a separate NPM package called [Scripting API Extra](https://github.com/workadventure/scripting-api-extra). + +In this section, you will find a list of these extended functions. + +## Importing the "utility functions" + +Import these functions in your project using NPM: + +``` +npm install --save @workadventure/scripting-api-extra +``` + +Note: these functions are provided as an ES6 module. You will need a "bundler" (like Webpack) to package your script. +If you don't have a bundler already, have a look at the [WorkAdventure Map Starter Kit](https://github.com/thecodingmachine/workadventure-map-starter-kit/). +It provides a complete development environment ready with Typescript enabled. + +## Utility functions + +- [Property related functions](functions-properties.md) +- [Variable related functions](functions-variables.md) +- [Layer related functions](functions-layers.md) diff --git a/package.json b/package.json index 6f0c704..68a03dc 100644 --- a/package.json +++ b/package.json @@ -96,6 +96,7 @@ "publishConfig": { "access": "public" }, + "unpkg": "dist/bundle.js", "dependencies": { "@workadventure/tiled-map-type-guard": "^1.0.2", "play-dtmf": "^0.1.1" diff --git a/src/index.ts b/src/index.ts index 81c276a..57fd9e2 100644 --- a/src/index.ts +++ b/src/index.ts @@ -4,5 +4,6 @@ export * from "./VariablesExtra"; export * from "./Properties"; export * from "./LayersFlattener"; +export * from "./LayersExtra"; export * from "./Features/doors"; export * from "./Features/variable_actions";