_Bastler/partey_workadventure
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

Updates room documentation for embeddedWebsite properties

Browse Source
This commit is contained in:
Benedicte Quimbert 2021-12-28 15:05:58 +01:00
parent a69f232a06
commit 99f9d56c5c
4 changed files with 78 additions and 86 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

140
docs/maps/api-room.md
View File

@ -1,8 +1,11 @@
{.section-title.accent.text-primary} {.section-title.accent.text-primary}
# API Room functions Reference # API Room functions Reference
### Working with group layers ### Working with group layers
If you use group layers in your map, to reference a layer in a group you will need to use a `/` to join layer names together.
If you use group layers in your map, to reference a layer in a group you will need to use a `/` to join layer names
together.
Example : Example :
<div class="row"> <div class="row">
@ -12,6 +15,7 @@ Example :
</div> </div>
The name of the layers of this map are : The name of the layers of this map are :
* `entries/start` * `entries/start`
* `bottom/ground/under` * `bottom/ground/under`
* `bottom/build/carpet` * `bottom/build/carpet`
@ -26,29 +30,32 @@ WA.room.onLeaveLayer(name: string): Subscription
Listens to the position of the current user. The event is triggered when the user enters or leaves a given layer. Listens to the position of the current user. The event is triggered when the user enters or leaves a given layer.
* **name**: the name of the layer who as defined in Tiled. * **name**: the name of the layer who as defined in Tiled.
Example: Example:
```javascript ```javascript
WA.room.onEnterLayer('myLayer').subscribe(() => { WA.room.onEnterLayer('myLayer').subscribe(() => {
WA.chat.sendChatMessage("Hello!", 'Mr Robot'); WA.chat.sendChatMessage("Hello!", 'Mr Robot');
}); });
WA.room.onLeaveLayer('myLayer').subscribe(() => { WA.room.onLeaveLayer('myLayer').subscribe(() => {
WA.chat.sendChatMessage("Goodbye!", 'Mr Robot'); WA.chat.sendChatMessage("Goodbye!", 'Mr Robot');
}); });
``` ```
### Show / Hide a layer ### Show / Hide a layer
``` ```
WA.room.showLayer(layerName : string): void WA.room.showLayer(layerName : string): void
WA.room.hideLayer(layerName : string) : void WA.room.hideLayer(layerName : string) : void
``` ```
These 2 methods can be used to show and hide a layer.
if `layerName` is the name of a group layer, show/hide all the layer in that group layer. These 2 methods can be used to show and hide a layer. if `layerName` is the name of a group layer, show/hide all the
layer in that group layer.
Example : Example :
```javascript ```javascript
WA.room.showLayer('bottom'); WA.room.showLayer('bottom');
//... //...
@ -61,12 +68,14 @@ WA.room.hideLayer('bottom');
WA.room.setProperty(layerName : string, propertyName : string, propertyValue : string | number | boolean | undefined) : void; WA.room.setProperty(layerName : string, propertyName : string, propertyValue : string | number | boolean | undefined) : void;
``` ```
Set the value of the `propertyName` property of the layer `layerName` at `propertyValue`. If the property doesn't exist, create the property `propertyName` and set the value of the property at `propertyValue`. Set the value of the `propertyName` property of the layer `layerName` at `propertyValue`. If the property doesn't exist,
create the property `propertyName` and set the value of the property at `propertyValue`.
Note : Note :
To unset a property from a layer, use `setProperty` with `propertyValue` set to `undefined`. To unset a property from a layer, use `setProperty` with `propertyValue` set to `undefined`.
Example : Example :
```javascript ```javascript
WA.room.setProperty('wikiLayer', 'openWebsite', 'https://www.wikipedia.org/'); WA.room.setProperty('wikiLayer', 'openWebsite', 'https://www.wikipedia.org/');
``` ```
@ -79,13 +88,12 @@ WA.room.id: string;
The ID of the current room is available from the `WA.room.id` property. The ID of the current room is available from the `WA.room.id` property.
{.alert.alert-info} {.alert.alert-info} You need to wait for the end of the initialization before accessing `WA.room.id`
You need to wait for the end of the initialization before accessing `WA.room.id`
```typescript ```typescript
WA.onInit().then(() => { WA.onInit().then(() => {
console.log('Room id: ', WA.room.id); console.log('Room id: ', WA.room.id);
// Will output something like: 'https://play.workadventu.re/@/myorg/myworld/myroom', or 'https://play.workadventu.re/_/global/mymap.org/map.json" // Will output something like: 'https://play.workadventu.re/@/myorg/myworld/myroom', or 'https://play.workadventu.re/_/global/mymap.org/map.json"
}) })
``` ```
@ -97,19 +105,17 @@ WA.room.mapURL: string;
The URL of the map is available from the `WA.room.mapURL` property. The URL of the map is available from the `WA.room.mapURL` property.
{.alert.alert-info} {.alert.alert-info} You need to wait for the end of the initialization before accessing `WA.room.mapURL`
You need to wait for the end of the initialization before accessing `WA.room.mapURL`
```typescript ```typescript
WA.onInit().then(() => { WA.onInit().then(() => {
console.log('Map URL: ', WA.room.mapURL); console.log('Map URL: ', WA.room.mapURL);
// Will output something like: 'https://mymap.org/map.json" // Will output something like: 'https://mymap.org/map.json"
}) })
``` ```
### Getting map data ### Getting map data
``` ```
WA.room.getTiledMap(): Promise<ITiledMap> WA.room.getTiledMap(): Promise<ITiledMap>
``` ```
@ -121,12 +127,16 @@ const map = await WA.room.getTiledMap();
console.log("Map generated with Tiled version ", map.tiledversion); console.log("Map generated with Tiled version ", map.tiledversion);
``` ```
Check the [Tiled documentation to learn more about the format of the JSON map](https://doc.mapeditor.org/en/stable/reference/json-map-format/). Check
the [Tiled documentation to learn more about the format of the JSON map](https://doc.mapeditor.org/en/stable/reference/json-map-format/)
.
### Changing tiles ### Changing tiles
``` ```
WA.room.setTiles(tiles: TileDescriptor[]): void WA.room.setTiles(tiles: TileDescriptor[]): void
``` ```
Replace the tile at the `x` and `y` coordinates in the layer named `layer` by the tile with the id `tile`. Replace the tile at the `x` and `y` coordinates in the layer named `layer` by the tile with the id `tile`.
If `tile` is a string, it's not the id of the tile but the value of the property `name`. If `tile` is a string, it's not the id of the tile but the value of the property `name`.
@ -137,43 +147,48 @@ If `tile` is a string, it's not the id of the tile but the value of the property
</div> </div>
`TileDescriptor` has the following attributes : `TileDescriptor` has the following attributes :
* **x (number) :** The coordinate x of the tile that you want to replace. * **x (number) :** The coordinate x of the tile that you want to replace.
* **y (number) :** The coordinate y of the tile that you want to replace. * **y (number) :** The coordinate y of the tile that you want to replace.
* **tile (number | string) :** The id of the tile that will be placed in the map. * **tile (number | string) :** The id of the tile that will be placed in the map.
* **layer (string) :** The name of the layer where the tile will be placed. * **layer (string) :** The name of the layer where the tile will be placed.
**Important !** : If you use `tile` as a number, be sure to add the `firstgid` of the tileset of the tile that you want to the id of the tile in Tiled Editor. **Important !** : If you use `tile` as a number, be sure to add the `firstgid` of the tileset of the tile that you want
to the id of the tile in Tiled Editor.
Note: If you want to unset a tile, use `setTiles` with `tile` set to `null`. Note: If you want to unset a tile, use `setTiles` with `tile` set to `null`.
Example : Example :
```javascript ```javascript
WA.room.setTiles([ WA.room.setTiles([
{x: 6, y: 4, tile: 'blue', layer: 'setTiles'}, { x: 6, y: 4, tile: 'blue', layer: 'setTiles' },
{x: 7, y: 4, tile: 109, layer: 'setTiles'}, { x: 7, y: 4, tile: 109, layer: 'setTiles' },
{x: 8, y: 4, tile: 109, layer: 'setTiles'}, { x: 8, y: 4, tile: 109, layer: 'setTiles' },
{x: 9, y: 4, tile: 'blue', layer: 'setTiles'} { x: 9, y: 4, tile: 'blue', layer: 'setTiles' }
]); ]);
``` ```
### Loading a tileset ### Loading a tileset
``` ```
WA.room.loadTileset(url: string): Promise<number> WA.room.loadTileset(url: string): Promise<number>
``` ```
Load a tileset in JSON format from an url and return the id of the first tile of the loaded tileset. Load a tileset in JSON format from an url and return the id of the first tile of the loaded tileset.
You can create a tileset file in Tile Editor. You can create a tileset file in Tile Editor.
```javascript ```javascript
WA.room.loadTileset("Assets/Tileset.json").then((firstId) => { WA.room.loadTileset("Assets/Tileset.json").then((firstId) => {
WA.room.setTiles([{x: 4, y: 4, tile: firstId, layer: 'bottom'}]); WA.room.setTiles([{ x: 4, y: 4, tile: firstId, layer: 'bottom' }]);
}) })
``` ```
## Embedding websites in a map ## Embedding websites in a map
You can use the scripting API to embed websites in a map, or to edit websites that are already embedded (using the ["website" objects](website-in-map.md)). You can use the scripting API to embed websites in a map, or to edit websites that are already embedded (using
the ["website" objects](website-in-map.md)).
### Getting an instance of a website already embedded in the map ### Getting an instance of a website already embedded in the map
@ -181,8 +196,8 @@ You can use the scripting API to embed websites in a map, or to edit websites th
WA.room.website.get(objectName: string): Promise<EmbeddedWebsite> WA.room.website.get(objectName: string): Promise<EmbeddedWebsite>
``` ```
You can get an instance of an embedded website by using the `WA.room.website.get()` method. You can get an instance of an embedded website by using the `WA.room.website.get()` method. It returns a promise of
It returns a promise of an `EmbeddedWebsite` instance. an `EmbeddedWebsite` instance.
```javascript ```javascript
// Get an existing website object where 'my_website' is the name of the object (on any layer object of the map) // Get an existing website object where 'my_website' is the name of the object (on any layer object of the map)
@ -191,7 +206,6 @@ website.url = 'https://example.com';
website.visible = true; website.visible = true;
``` ```
### Adding a new website in a map ### Adding a new website in a map
``` ```
@ -201,34 +215,38 @@ interface CreateEmbeddedWebsiteEvent {
name: string; // A unique name for this iframe name: string; // A unique name for this iframe
url: string; // The URL the iframe points to. url: string; // The URL the iframe points to.
position: { position: {
x: number, // In pixels, relative to the map coordinates x: number, // relative to the map or player coordinates, depending on origin
y: number, // In pixels, relative to the map coordinates y: number, // relative to the map or player coordinates, depending on origin
width: number, // In pixels, sensitive to zoom level width: number, // In pixels, sensitive to zoom level and scale
height: number, // In pixels, sensitive to zoom level height: number, // In pixels, sensitive to zoom level and scale
}, },
visible?: boolean, // Whether to display the iframe or not visible?: boolean, // Whether to display the iframe or not
allowApi?: boolean, // Whether the scripting API should be available to the iframe allowApi?: boolean, // Whether the scripting API should be available to the iframe
allow?: string, // The list of feature policies allowed allow?: string, // The list of feature policies allowed
origin: "player" | "map" // The origin used to place the x and y coordinates of the iframe's top-left corner
scale: number, // A ratio used to resize the iframe (will affect the iframe's width and height when it is rendered
} }
``` ```
You can create an instance of an embedded website by using the `WA.room.website.create()` method. You can create an instance of an embedded website by using the `WA.room.website.create()` method. It returns
It returns an `EmbeddedWebsite` instance. an `EmbeddedWebsite` instance.
```javascript ```javascript
// Create a new website object // Create a new website object
const website = WA.room.website.create({ const website = WA.room.website.create({
name: "my_website", name: "my_website",
url: "https://example.com", url: "https://example.com",
position: { position: {
x: 64, x: 64,
y: 128, y: 128,
width: 320, width: 320,
height: 240, height: 240,
}, },
visible: true, visible: true,
allowApi: true, allowApi: true,
allow: "fullscreen", allow: "fullscreen",
origin: "map",
scale: 1,
}); });
``` ```
@ -240,30 +258,28 @@ WA.room.website.delete(name: string): Promise<void>
Use `WA.room.website.delete` to completely remove an embedded website from your map. Use `WA.room.website.delete` to completely remove an embedded website from your map.
### The EmbeddedWebsite class ### The EmbeddedWebsite class
Instances of the `EmbeddedWebsite` class represent the website displayed on the map. Instances of the `EmbeddedWebsite` class represent the website displayed on the map.
```typescript ```typescript
class EmbeddedWebsite { class EmbeddedWebsite {
readonly name: string; readonly name: string;
url: string; url: string;
visible: boolean; visible: boolean;
allow: string; allow: string;
allowApi: boolean; allowApi: boolean;
x: number; // In pixels, relative to the map coordinates x: number; // In pixels, relative to the map or player coordinates, depending on origin
y: number; // In pixels, relative to the map coordinates y: number; // In pixels, relative to the map or player coordinates, depending on origin
width: number; // In pixels, sensitive to zoom level width: number; // In pixels, sensitive to zoom level and scale
height: number; // In pixels, sensitive to zoom level height: number; // In pixels, sensitive to zoom level and scale
origin: "player" | "map";
scale: number;
} }
``` ```
When you modify a property of an `EmbeddedWebsite` instance, the iframe is automatically modified in the map. When you modify a property of an `EmbeddedWebsite` instance, the iframe is automatically modified in the map.
{.alert.alert-warning} The websites you add/edit/delete via the scripting API are only shown locally. If you want them
{.alert.alert-warning} to be displayed for every player, you can use [variables](api-start.md) to share a common state between all users.
The websites you add/edit/delete via the scripting API are only shown locally. If you want them
to be displayed for every player, you can use [variables](api-start.md) to share a common state
between all users.

9
front/src/Api/Events/IframeEvent.ts
View File

@ -28,7 +28,6 @@ import type { MessageReferenceEvent } from "./ui/TriggerActionMessageEvent";
import { isMessageReferenceEvent, isTriggerActionMessageEvent } from "./ui/TriggerActionMessageEvent"; import { isMessageReferenceEvent, isTriggerActionMessageEvent } from "./ui/TriggerActionMessageEvent";
import type { MenuRegisterEvent, UnregisterMenuEvent } from "./ui/MenuRegisterEvent"; import type { MenuRegisterEvent, UnregisterMenuEvent } from "./ui/MenuRegisterEvent";
import type { ChangeLayerEvent } from "./ChangeLayerEvent"; import type { ChangeLayerEvent } from "./ChangeLayerEvent";
import { isPlayerPropertyEvent } from "./PlayerPropertyEvent";
import type { ChangeZoneEvent } from "./ChangeZoneEvent"; import type { ChangeZoneEvent } from "./ChangeZoneEvent";
import { isColorEvent } from "./ColorEvent"; import { isColorEvent } from "./ColorEvent";
import { isPlayerPosition } from "./PlayerPosition"; import { isPlayerPosition } from "./PlayerPosition";
@ -158,14 +157,6 @@ export const iframeQueryMapTypeGuards = {
query: isCreateEmbeddedWebsiteEvent, query: isCreateEmbeddedWebsiteEvent,
answer: tg.isUndefined, answer: tg.isUndefined,
}, },
getPlayerProperty: {
query: tg.isString,
answer: isPlayerPropertyEvent,
},
setPlayerProperty: {
query: isPlayerPropertyEvent,
answer: tg.isUndefined,
},
setPlayerOutline: { setPlayerOutline: {
query: isColorEvent, query: isColorEvent,
answer: tg.isUndefined, answer: tg.isUndefined,

1
front/src/Api/IframeListener.ts
View File

@ -32,7 +32,6 @@ import { ModifyEmbeddedWebsiteEvent, isEmbeddedWebsiteEvent } from "./Events/Emb
import { handleMenuRegistrationEvent, handleMenuUnregisterEvent } from "../Stores/MenuStore"; import { handleMenuRegistrationEvent, handleMenuUnregisterEvent } from "../Stores/MenuStore";
import type { ChangeLayerEvent } from "./Events/ChangeLayerEvent"; import type { ChangeLayerEvent } from "./Events/ChangeLayerEvent";
import type { WasCameraUpdatedEvent } from "./Events/WasCameraUpdatedEvent"; import type { WasCameraUpdatedEvent } from "./Events/WasCameraUpdatedEvent";
import type { HasCameraMovedEvent } from "./Events/HasCameraMovedEvent";
import type { ChangeZoneEvent } from "./Events/ChangeZoneEvent"; import type { ChangeZoneEvent } from "./Events/ChangeZoneEvent";
type AnswererCallback<T extends keyof IframeQueryMap> = ( type AnswererCallback<T extends keyof IframeQueryMap> = (

14
front/src/Api/iframe/player.ts
View File

@ -110,20 +110,6 @@ export class WorkadventurePlayerCommands extends IframeApiContribution<Workadven
data: undefined, data: undefined,
}); });
} }
getPlayerProperty(name: string): Promise<PlayerPropertyEvent> {
return queryWorkadventure({
type: "getPlayerProperty",
data: name,
});
}
setPlayerProperty(property: PlayerPropertyEvent) {
queryWorkadventure({
type: "setPlayerProperty",
data: property,
}).catch((e) => console.error(e));
}
} }
export type Position = { export type Position = {