Merge branch 'develop' of github.com:thecodingmachine/workadventure into metadataScriptingApi
This commit is contained in:
GRL
commit
ca3f5c599a
160 changed files with 4066 additions and 3583 deletions
37
docs/maps/api-chat.md
Normal file
37
docs/maps/api-chat.md
Normal file
|
|
@ -0,0 +1,37 @@
|
|||
{.section-title.accent.text-primary}
|
||||
# API Chat functions reference
|
||||
|
||||
### Sending a message in the chat
|
||||
|
||||
```
|
||||
WA.chat.sendChatMessage(message: string, author: string): void
|
||||
```
|
||||
|
||||
Sends a message in the chat. The message is only visible in the browser of the current user.
|
||||
|
||||
* **message**: the message to be displayed in the chat
|
||||
* **author**: the name displayed for the author of the message. It does not have to be a real user.
|
||||
|
||||
Example:
|
||||
|
||||
```javascript
|
||||
WA.chat.sendChatMessage('Hello world', 'Mr Robot');
|
||||
```
|
||||
|
||||
### Listening to messages from the chat
|
||||
|
||||
```javascript
|
||||
WA.chat.onChatMessage(callback: (message: string) => void): void
|
||||
```
|
||||
|
||||
Listens to messages typed by the current user and calls the callback. Messages from other users in the chat cannot be listened to.
|
||||
|
||||
* **callback**: the function that will be called when a message is received. It contains the message typed by the user.
|
||||
|
||||
Example:
|
||||
|
||||
```javascript
|
||||
WA.chat.onChatMessage((message => {
|
||||
console.log('The user typed a message', message);
|
||||
}));
|
||||
```
|
||||
29
docs/maps/api-controls.md
Normal file
29
docs/maps/api-controls.md
Normal file
|
|
@ -0,0 +1,29 @@
|
|||
{.section-title.accent.text-primary}
|
||||
# API Controls functions Reference
|
||||
|
||||
### Disabling / restoring controls
|
||||
|
||||
```
|
||||
WA.controls.disablePlayerControls(): void
|
||||
WA.controls.restorePlayerControls(): void
|
||||
```
|
||||
|
||||
These 2 methods can be used to completely disable player controls and to enable them again.
|
||||
|
||||
When controls are disabled, the user cannot move anymore using keyboard input. This can be useful in a "First Time User Experience" part, to display an important message to a user before letting him/her move again.
|
||||
|
||||
Example:
|
||||
|
||||
```javascript
|
||||
WA.room.onEnterZone('myZone', () => {
|
||||
WA.controls.disablePlayerControls();
|
||||
WA.ui.openPopup("popupRectangle", 'This is an imporant message!', [{
|
||||
label: "Got it!",
|
||||
className: "primary",
|
||||
callback: (popup) => {
|
||||
WA.controls.restorePlayerControls();
|
||||
popup.close();
|
||||
}
|
||||
}]);
|
||||
});
|
||||
```
|
||||
20
docs/maps/api-deprecated.md
Normal file
20
docs/maps/api-deprecated.md
Normal file
|
|
@ -0,0 +1,20 @@
|
|||
{.section-title.accent.text-primary}
|
||||
# API Reference - Deprecated functions
|
||||
|
||||
The list of functions below is **deprecated**. You should not use those but. use the replacement functions.
|
||||
|
||||
- Method `WA.sendChatMessage` is deprecated. It has been renamed to `WA.chat.sendChatMessage`.
|
||||
- Method `WA.disablePlayerControls` is deprecated. It has been renamed to `WA.controls.disablePlayerControls`.
|
||||
- Method `WA.restorePlayerControls` is deprecated. It has been renamed to `WA.controls.restorePlayerControls`.
|
||||
- Method `WA.displayBubble` is deprecated. It has been renamed to `WA.ui.displayBubble`.
|
||||
- Method `WA.removeBubble` is deprecated. It has been renamed to `WA.ui.removeBubble`.
|
||||
- Method `WA.openTab` is deprecated. It has been renamed to `WA.nav.openTab`.
|
||||
- Method `WA.loadSound` is deprecated. It has been renamed to `WA.sound.loadSound`.
|
||||
- Method `WA.goToPage` is deprecated. It has been renamed to `WA.nav.goToPage`.
|
||||
- Method `WA.goToRoom` is deprecated. It has been renamed to `WA.nav.goToRoom`.
|
||||
- Method `WA.openCoWebSite` is deprecated. It has been renamed to `WA.nav.openCoWebSite`.
|
||||
- Method `WA.closeCoWebSite` is deprecated. It has been renamed to `WA.nav.closeCoWebSite`.
|
||||
- Method `WA.openPopup` is deprecated. It has been renamed to `WA.ui.openPopup`.
|
||||
- Method `WA.onChatMessage` is deprecated. It has been renamed to `WA.chat.onChatMessage`.
|
||||
- Method `WA.onEnterZone` is deprecated. It has been renamed to `WA.room.onEnterZone`.
|
||||
- Method `WA.onLeaveZone` is deprecated. It has been renamed to `WA.room.onLeaveZone`.
|
||||
68
docs/maps/api-nav.md
Normal file
68
docs/maps/api-nav.md
Normal file
|
|
@ -0,0 +1,68 @@
|
|||
{.section-title.accent.text-primary}
|
||||
# API Navigation functions reference
|
||||
|
||||
### Opening a web page in a new tab
|
||||
|
||||
```
|
||||
WA.nav.openTab(url: string): void
|
||||
```
|
||||
|
||||
Opens the webpage at "url" in your browser, in a new tab.
|
||||
|
||||
Example:
|
||||
|
||||
```javascript
|
||||
WA.nav.openTab('https://www.wikipedia.org/');
|
||||
```
|
||||
|
||||
### Opening a web page in the current tab
|
||||
|
||||
```
|
||||
WA.nav.goToPage(url: string): void
|
||||
```
|
||||
|
||||
Opens the webpage at "url" in your browser in place of WorkAdventure. WorkAdventure will be completely unloaded.
|
||||
|
||||
Example:
|
||||
|
||||
```javascript
|
||||
WA.nav.goToPage('https://www.wikipedia.org/');
|
||||
```
|
||||
|
||||
### Going to a different map from the script
|
||||
|
||||
```
|
||||
|
||||
WA.nav.goToRoom(url: string): void
|
||||
```
|
||||
|
||||
Load the map at url without unloading workadventure
|
||||
|
||||
relative urls: "../subFolder/map.json[#start-layer-name]"
|
||||
global urls: "/_/global/domain/path/map.json[#start-layer-name]"
|
||||
|
||||
Example:
|
||||
|
||||
```javascript
|
||||
WA.nav.goToRoom("/@/tcm/workadventure/floor0") // workadventure urls
|
||||
WA.nav.goToRoom('../otherMap/map.json');
|
||||
WA.nav.goToRoom("/_/global/<path to global map>.json#start-layer-2")
|
||||
```
|
||||
|
||||
### Opening/closing a web page in an iFrame
|
||||
|
||||
```
|
||||
WA.nav.openCoWebSite(url: string): void
|
||||
WA.nav.closeCoWebSite(): void
|
||||
```
|
||||
|
||||
Opens the webpage at "url" in an iFrame (on the right side of the screen) or close that iFrame.
|
||||
|
||||
Example:
|
||||
|
||||
```javascript
|
||||
WA.nav.openCoWebSite('https://www.wikipedia.org/');
|
||||
// ...
|
||||
WA.nav.closeCoWebSite();
|
||||
```
|
||||
|
||||
|
|
@ -1,240 +1,14 @@
|
|||
{.section-title.accent.text-primary}
|
||||
# API Reference
|
||||
|
||||
### Sending a message in the chat
|
||||
- [Navigation functions](api-nav.md)
|
||||
- [Chat functions](api-chat.md)
|
||||
- [Room functions](api-room.md)
|
||||
- [UI functions](api-ui.md)
|
||||
- [Sound functions](api-sound.md)
|
||||
- [Controls functions](api-controls.md)
|
||||
|
||||
```
|
||||
sendChatMessage(message: string, author: string): void
|
||||
```
|
||||
|
||||
Sends a message in the chat. The message is only visible in the browser of the current user.
|
||||
|
||||
* **message**: the message to be displayed in the chat
|
||||
* **author**: the name displayed for the author of the message. It does not have to be a real user.
|
||||
|
||||
Example:
|
||||
|
||||
```javascript
|
||||
WA.sendChatMessage('Hello world', 'Mr Robot');
|
||||
```
|
||||
|
||||
### Listening to messages from the chat
|
||||
|
||||
```javascript
|
||||
onChatMessage(callback: (message: string) => void): void
|
||||
```
|
||||
|
||||
Listens to messages typed by the current user and calls the callback. Messages from other users in the chat cannot be listened to.
|
||||
|
||||
* **callback**: the function that will be called when a message is received. It contains the message typed by the user.
|
||||
|
||||
Example:
|
||||
|
||||
```javascript
|
||||
WA.onChatMessage((message => {
|
||||
console.log('The user typed a message', message);
|
||||
}));
|
||||
```
|
||||
|
||||
### Detecting when the user enters/leaves a zone
|
||||
|
||||
```
|
||||
onEnterZone(name: string, callback: () => void): void
|
||||
onLeaveZone(name: string, callback: () => void): void
|
||||
```
|
||||
|
||||
Listens to the position of the current user. The event is triggered when the user enters or leaves a given zone. The name of the zone is stored in the map, on a dedicated layer with the `zone` property.
|
||||
|
||||
<div>
|
||||
<figure class="figure">
|
||||
<img src="https://workadventu.re/img/docs/trigger_event.png" class="figure-img img-fluid rounded" alt="" />
|
||||
<figcaption class="figure-caption">The `zone` property, applied on a layer</figcaption>
|
||||
</figure>
|
||||
</div>
|
||||
|
||||
* **name**: the name of the zone, as defined in the `zone` property.
|
||||
* **callback**: the function that will be called when a user enters or leaves the zone.
|
||||
|
||||
Example:
|
||||
|
||||
```javascript
|
||||
WA.onEnterZone('myZone', () => {
|
||||
WA.sendChatMessage("Hello!", 'Mr Robot');
|
||||
})
|
||||
|
||||
WA.onLeaveZone('myZone', () => {
|
||||
WA.sendChatMessage("Goodbye!", 'Mr Robot');
|
||||
})
|
||||
```
|
||||
|
||||
### Opening a popup
|
||||
|
||||
In order to open a popup window, you must first define the position of the popup on your map.
|
||||
|
||||
You can position this popup by using a "rectangle" object in Tiled that you will place on an "object" layer.
|
||||
|
||||
<div class="row">
|
||||
<div class="col">
|
||||
<img src="https://workadventu.re/img/docs/screen_popup_tiled.png" class="figure-img img-fluid rounded" alt="" />
|
||||
</div>
|
||||
<div class="col">
|
||||
<img src="https://workadventu.re/img/docs/screen_popup_in_game.png" class="figure-img img-fluid rounded" alt="" />
|
||||
</div>
|
||||
</div>
|
||||
|
||||
```
|
||||
openPopup(targetObject: string, message: string, buttons: ButtonDescriptor[]): Popup
|
||||
```
|
||||
|
||||
* **targetObject**: the name of the rectangle object defined in Tiled.
|
||||
* **message**: the message to display in the popup.
|
||||
* **buttons**: an array of action buttons defined underneath the popup.
|
||||
|
||||
Action buttons are `ButtonDescriptor` objects containing these properties.
|
||||
|
||||
* **label (_string_)**: The label of the button.
|
||||
* **className (_string_)**: The visual type of the button. Can be one of "normal", "primary", "success", "warning", "error", "disabled".
|
||||
* **callback (_(popup: Popup)=>void_)**: Callback called when the button is pressed.
|
||||
|
||||
Please note that `openPopup` returns an object of the `Popup` class. Also, the callback called when a button is clicked is passed a `Popup` object.
|
||||
|
||||
The `Popup` class that represents an open popup contains a single method: `close()`. This will obviously close the popup when called.
|
||||
|
||||
```javascript
|
||||
class Popup {
|
||||
/**
|
||||
* Closes the popup
|
||||
*/
|
||||
close() {};
|
||||
}
|
||||
```
|
||||
|
||||
Example:
|
||||
|
||||
```javascript
|
||||
let helloWorldPopup;
|
||||
|
||||
// Open the popup when we enter a given zone
|
||||
helloWorldPopup = WA.onEnterZone('myZone', () => {
|
||||
WA.openPopup("popupRectangle", 'Hello world!', [{
|
||||
label: "Close",
|
||||
className: "primary",
|
||||
callback: (popup) => {
|
||||
// Close the popup when the "Close" button is pressed.
|
||||
popup.close();
|
||||
}
|
||||
});
|
||||
}]);
|
||||
|
||||
// Close the popup when we leave the zone.
|
||||
WA.onLeaveZone('myZone', () => {
|
||||
helloWorldPopup.close();
|
||||
});
|
||||
```
|
||||
|
||||
### Disabling / restoring controls
|
||||
|
||||
```
|
||||
disablePlayerControls(): void
|
||||
restorePlayerControls(): void
|
||||
```
|
||||
|
||||
These 2 methods can be used to completely disable player controls and to enable them again.
|
||||
|
||||
When controls are disabled, the user cannot move anymore using keyboard input. This can be useful in a "First Time User Experience" part, to display an important message to a user before letting him/her move again.
|
||||
|
||||
Example:
|
||||
|
||||
```javascript
|
||||
WA.onEnterZone('myZone', () => {
|
||||
WA.disablePlayerControls();
|
||||
WA.openPopup("popupRectangle", 'This is an imporant message!', [{
|
||||
label: "Got it!",
|
||||
className: "primary",
|
||||
callback: (popup) => {
|
||||
WA.restorePlayerControls();
|
||||
popup.close();
|
||||
}
|
||||
}]);
|
||||
});
|
||||
```
|
||||
|
||||
### Opening a web page in a new tab
|
||||
|
||||
```
|
||||
openTab(url: string): void
|
||||
```
|
||||
|
||||
Opens the webpage at "url" in your browser, in a new tab.
|
||||
|
||||
Example:
|
||||
|
||||
```javascript
|
||||
WA.openTab('https://www.wikipedia.org/');
|
||||
```
|
||||
|
||||
### Opening a web page in the current tab
|
||||
|
||||
```
|
||||
goToPage(url: string): void
|
||||
```
|
||||
|
||||
Opens the webpage at "url" in your browser in place of WorkAdventure. WorkAdventure will be completely unloaded.
|
||||
|
||||
Example:
|
||||
|
||||
```javascript
|
||||
WA.goToPage('https://www.wikipedia.org/');
|
||||
```
|
||||
|
||||
### Opening/closing a web page in an iFrame
|
||||
|
||||
```
|
||||
openCoWebSite(url: string): void
|
||||
closeCoWebSite(): void
|
||||
```
|
||||
|
||||
Opens the webpage at "url" in an iFrame (on the right side of the screen) or close that iFrame.
|
||||
|
||||
Example:
|
||||
|
||||
```javascript
|
||||
WA.openCoWebSite('https://www.wikipedia.org/');
|
||||
// ...
|
||||
WA.closeCoWebSite();
|
||||
```
|
||||
|
||||
### Load a sound from an url
|
||||
|
||||
```
|
||||
loadSound(url: string): Sound
|
||||
```
|
||||
|
||||
Load a sound from an url
|
||||
|
||||
Please note that `loadSound` returns an object of the `Sound` class
|
||||
|
||||
The `Sound` class that represents a loaded sound contains two methods: `play(soundConfig : SoundConfig|undefined)` and `stop()`
|
||||
|
||||
The parameter soundConfig is optional, if you call play without a Sound config the sound will be played with the basic configuration.
|
||||
|
||||
Example:
|
||||
|
||||
```javascript
|
||||
var mySound = WA.loadSound("Sound.ogg");
|
||||
var config = {
|
||||
volume : 0.5,
|
||||
loop : false,
|
||||
rate : 1,
|
||||
detune : 1,
|
||||
delay : 0,
|
||||
seek : 0,
|
||||
mute : false
|
||||
}
|
||||
mySound.play(config);
|
||||
// ...
|
||||
mySound.stop();
|
||||
```
|
||||
- [List of deprecated functions](api-deprecated.md)
|
||||
|
||||
### Show / Hide a layer
|
||||
```
|
||||
|
|
|
|||
33
docs/maps/api-room.md
Normal file
33
docs/maps/api-room.md
Normal file
|
|
@ -0,0 +1,33 @@
|
|||
{.section-title.accent.text-primary}
|
||||
# API Room functions Reference
|
||||
|
||||
### Detecting when the user enters/leaves a zone
|
||||
|
||||
```
|
||||
WA.room.onEnterZone(name: string, callback: () => void): void
|
||||
WA.room.onLeaveZone(name: string, callback: () => void): void
|
||||
```
|
||||
|
||||
Listens to the position of the current user. The event is triggered when the user enters or leaves a given zone. The name of the zone is stored in the map, on a dedicated layer with the `zone` property.
|
||||
|
||||
<div>
|
||||
<figure class="figure">
|
||||
<img src="https://workadventu.re/img/docs/trigger_event.png" class="figure-img img-fluid rounded" alt="" />
|
||||
<figcaption class="figure-caption">The `zone` property, applied on a layer</figcaption>
|
||||
</figure>
|
||||
</div>
|
||||
|
||||
* **name**: the name of the zone, as defined in the `zone` property.
|
||||
* **callback**: the function that will be called when a user enters or leaves the zone.
|
||||
|
||||
Example:
|
||||
|
||||
```javascript
|
||||
WA.room.onEnterZone('myZone', () => {
|
||||
WA.chat.sendChatMessage("Hello!", 'Mr Robot');
|
||||
})
|
||||
|
||||
WA.room.onLeaveZone('myZone', () => {
|
||||
WA.chat.sendChatMessage("Goodbye!", 'Mr Robot');
|
||||
})
|
||||
```
|
||||
34
docs/maps/api-sound.md
Normal file
34
docs/maps/api-sound.md
Normal file
|
|
@ -0,0 +1,34 @@
|
|||
{.section-title.accent.text-primary}
|
||||
# API Sound functions Reference
|
||||
|
||||
### Load a sound from an url
|
||||
|
||||
```
|
||||
WA.sound.loadSound(url: string): Sound
|
||||
```
|
||||
|
||||
Load a sound from an url
|
||||
|
||||
Please note that `loadSound` returns an object of the `Sound` class
|
||||
|
||||
The `Sound` class that represents a loaded sound contains two methods: `play(soundConfig : SoundConfig|undefined)` and `stop()`
|
||||
|
||||
The parameter soundConfig is optional, if you call play without a Sound config the sound will be played with the basic configuration.
|
||||
|
||||
Example:
|
||||
|
||||
```javascript
|
||||
var mySound = WA.sound.loadSound("Sound.ogg");
|
||||
var config = {
|
||||
volume : 0.5,
|
||||
loop : false,
|
||||
rate : 1,
|
||||
detune : 1,
|
||||
delay : 0,
|
||||
seek : 0,
|
||||
mute : false
|
||||
}
|
||||
mySound.play(config);
|
||||
// ...
|
||||
mySound.stop();
|
||||
```
|
||||
67
docs/maps/api-ui.md
Normal file
67
docs/maps/api-ui.md
Normal file
|
|
@ -0,0 +1,67 @@
|
|||
{.section-title.accent.text-primary}
|
||||
# API Room functions Reference
|
||||
|
||||
### Opening a popup
|
||||
|
||||
In order to open a popup window, you must first define the position of the popup on your map.
|
||||
|
||||
You can position this popup by using a "rectangle" object in Tiled that you will place on an "object" layer.
|
||||
|
||||
<div class="row">
|
||||
<div class="col">
|
||||
<img src="https://workadventu.re/img/docs/screen_popup_tiled.png" class="figure-img img-fluid rounded" alt="" />
|
||||
</div>
|
||||
<div class="col">
|
||||
<img src="https://workadventu.re/img/docs/screen_popup_in_game.png" class="figure-img img-fluid rounded" alt="" />
|
||||
</div>
|
||||
</div>
|
||||
|
||||
```
|
||||
WA.ui.openPopup(targetObject: string, message: string, buttons: ButtonDescriptor[]): Popup
|
||||
```
|
||||
|
||||
* **targetObject**: the name of the rectangle object defined in Tiled.
|
||||
* **message**: the message to display in the popup.
|
||||
* **buttons**: an array of action buttons defined underneath the popup.
|
||||
|
||||
Action buttons are `ButtonDescriptor` objects containing these properties.
|
||||
|
||||
* **label (_string_)**: The label of the button.
|
||||
* **className (_string_)**: The visual type of the button. Can be one of "normal", "primary", "success", "warning", "error", "disabled".
|
||||
* **callback (_(popup: Popup)=>void_)**: Callback called when the button is pressed.
|
||||
|
||||
Please note that `openPopup` returns an object of the `Popup` class. Also, the callback called when a button is clicked is passed a `Popup` object.
|
||||
|
||||
The `Popup` class that represents an open popup contains a single method: `close()`. This will obviously close the popup when called.
|
||||
|
||||
```javascript
|
||||
class Popup {
|
||||
/**
|
||||
* Closes the popup
|
||||
*/
|
||||
close() {};
|
||||
}
|
||||
```
|
||||
|
||||
Example:
|
||||
|
||||
```javascript
|
||||
let helloWorldPopup;
|
||||
|
||||
// Open the popup when we enter a given zone
|
||||
helloWorldPopup = WA.room.onEnterZone('myZone', () => {
|
||||
WA.ui.openPopup("popupRectangle", 'Hello world!', [{
|
||||
label: "Close",
|
||||
className: "primary",
|
||||
callback: (popup) => {
|
||||
// Close the popup when the "Close" button is pressed.
|
||||
popup.close();
|
||||
}
|
||||
});
|
||||
}]);
|
||||
|
||||
// Close the popup when we leave the zone.
|
||||
WA.room.onLeaveZone('myZone', () => {
|
||||
helloWorldPopup.close();
|
||||
});
|
||||
```
|
||||
Loading…
Add table
Add a link
Reference in a new issue