Skip to content

Commit

Permalink
Merge pull request #20 from workadventure/docs
Browse files Browse the repository at this point in the history 
Adding documentation for doors and bells
  • Loading branch information
@moufmouf
moufmouf authored Aug 23, 2021
2 parents efd99bd + 5c8e28e commit 8fafe0c
Show file tree
Hide file tree
Showing 28 changed files with 626 additions and 169 deletions.
181 changes: 12 additions & 169 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand All @@ -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<Map<string, VariableDescriptor>>`: 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
Expand Down
21 changes: 21 additions & 0 deletions docs/about.md
View file
Original file line number Diff line number Diff line change
@@ -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`

82 changes: 82 additions & 0 deletions docs/bells.md
View file
Original file line number Diff line number Diff line change
@@ -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.

<figure class="figure">
<img class="figure-img img-fluid rounded" src="images/bell_variable.png" alt="" />
<figcaption class="figure-caption">The bell variable</figcaption>
</figure>

## 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.

<figure class="figure">
<img class="figure-img img-fluid rounded" src="images/bell_popup.png" alt="" />
<figcaption class="figure-caption">The bell "popup" rectangle</figcaption>
</figure>

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"

<figure class="figure">
<img class="figure-img img-fluid rounded" src="images/bell_layer.png" alt="" />
<figcaption class="figure-caption">Complete list of properties for the bell layer</figcaption>
</figure>

{.alert.alert-info}
**Pro tip:** the `bellButtonText` can contain emojis. So you can use the "bell" emoji in the text: 🔔
Loading

0 comments on commit 8fafe0c

Please sign in to comment.