Scribd
Upload
24 views1 page

WorkAdventure Map Scripting Guide

The document provides an overview of the WorkAdventure APIs, focusing on the Map Scripting API which allows users to add scripts to enhance map functionality. It covers how to create scripts, including using JavaScript or TypeScript, and how to communicate with the WorkAdventure environment through iFrames. Additionally, it highlights the importance of CORS settings for script execution and outlines various features available in the client API.

Uploaded by

raziq.brown
Copyright
© All Rights Reserved
We take content rights seriously. If you suspect this is your content, claim it here.
Available Formats
Download as PDF, TXT or read online on Scribd
24 views1 page

WorkAdventure Map Scripting Guide

The document provides an overview of the WorkAdventure APIs, focusing on the Map Scripting API which allows users to add scripts to enhance map functionality. It covers how to create scripts, including using JavaScript or TypeScript, and how to communicate with the WorkAdventure environment through iFrames. Additionally, it highlights the importance of CORS settings for script execution and outlines various features available in the client API.

Uploaded by

raziq.brown
Copyright
© All Rights Reserved
We take content rights seriously. If you suspect this is your content, claim it here.
Available Formats
Download as PDF, TXT or read online on Scribd

Map Building Admin User Developer Tutorials Login Get Started Search ctrl K

WorkAdventure APIs Map Scripting API


Scripting language
Inbound API
Adding a script in the map
Map Scripting API Map Scripting API Adding a script in an iFrame

Variables Using Typescript

Do you want to add a bit of intelligence to your map? Scripts allow you to create maps with special features. Available features in the client API
Events

Api Reference You can for instance:

Camera
Create FTUE (First Time User Experience) scenarios where a first-time user will be displayed a notification popup.
Chat Create NPC (non playing characters) and interact with those characters using the chat.
Controls Organize interactions between an iframe and your map (for instance, walking on a special zone might add a product in the cart of
an eCommerce website...)
Event
etc...
Map Editor API

Metadata Please note that scripting in WorkAdventure is at an early stage of development and that more features might be added in the future.
You can actually voice your opinion about useful features by adding an issue on GitHub.
Navigation

Player
CAUTION
Players Beware: Scripts are executed in the browser of the current user only. Generally speaking, scripts cannot be used to trigger a
Room change that will be displayed on other users screen.

Sound

Start
Scripting language
State

UI Client-side scripting is done in Javascript (or any language that transpile to Javascript like Typescript).

Deprecated Functions There are 2 ways you can use the scripting language:
Extended utility functions
In the map: By directly referring a Javascript file inside your map, in the script property of your map.
Scripting Internals
In an iFrame: By placing your Javascript script into an iFrame, your script can communicate with the WorkAdventure game
Using Typescript

Map Storage API


Adding a script in the map
Room API
Create a script property in your map.

In Tiled, in order to access your map properties, you can click on "Map > Map properties".

Create a script property (a "string"), and put the URL of your script.

You can put relative URLs. If your script file is next to your map, you can simply write the name of the script file here.

Start by testing this with a simple message sent to the chat.

[Link]

[Link]('Hello world', 'Mr Robot');

The WA objects contains a number of useful methods enabling you to interact with the WorkAdventure game. For instance,
[Link] opens the chat and adds a message in it.

The message should be displayed in the chat history as soon as you enter the room.

CAUTION

Internally, scripts are running inside a sandboxed iframe. Furthermore, the script itself is loaded as module with <script src=""
type="module"> . Scripts loaded as module must enforce CORS. But the iframe itself does not have any origin, because it is
sandboxed. As a result, for the script to be loaded correctly, you will need to allow ALL origins using this header:

Access-Control-Allow-Origin: *

or alternatively:

Access-Control-Allow-Origin: null

Because the script is sandboxed, a number of restrictions apply. If you want a discussion on how to overcome them, check out the
"scripting internals" documentation.

Adding a script in an iFrame


In WorkAdventure, you can easily open an iFrame using the openWebsite property on a layer. However, by default, the iFrame is not
allowed to communicate with WorkAdventure.

This is done to improve security. In order to be able to execute a script that communicates with WorkAdventure inside an iFrame, you
have to explicitly allow the iFrame to use the "iFrame API".

In order to allow communication with WorkAdventure, you need to add an additional property: openWebsiteAllowApi . This property
must be boolean and you must set it to "true".

In your iFrame HTML page, you now need to import the WorkAdventure client API Javascript library. This library contains the WA object
that you can use to communicate with WorkAdventure.

The library is available at [Link] .

Note: if you are using a self-hosted version of WorkAdventure, use [Link]

[Link]

<!doctype html>
<html lang="en">
<head>
<script src="[Link]
</head>
<body>
</body>
</html>

You can now start by testing this with a simple message sent to the chat.

[Link]

...
<script>
[Link]('Hello world', 'Mr Robot');
</script>
...

Let's now review the complete list of methods available in this WA object.

Using Typescript
View the dedicated page about using Typescript with the scripting API.

Available features in the client API


The list of available functions and features is available in the API Reference page, with examples.

Edit this page

Previous Next
« Inbound API Variables »

Docs Need help ? Follow us

Map Building Book a demo Linkedin

Admin Discord Twitter


Developer GitHub Facebook

Copyright © 2024 [Link] - All Rights Reserved

Common questions

Powered by AI

To overcome the scripting restrictions of sandboxing in an iFrame within WorkAdventure, a developer must configure appropriate headers such as Access-Control-Allow-Origin to permit resource sharing and interaction . Additionally, the developer should enable communication across WorkAdventure's API by setting the openWebsiteAllowApi property to 'true' and ensure that the necessary client API library is imported into the iFrame . These steps create a bridge enabling functionality while preserving security, allowing for interaction with WorkAdventure's ecosystem through methods provided by the WA object.

The WA.chat.sendChatMessage function allows developers to programmatically send messages to the chat in WorkAdventure. To use this function, scripts must be executed within an environment that has access to the WorkAdventure API—such as in an iFrame that has been set to allow API interactions . Developers need to manage the sandboxing and CORS restrictions by setting appropriate headers and ensuring communication between the iFrame and main application is established . Consequently, the function provides a way to enhance user communication and engagement by dynamically sending messages as part of event handling or interactions within the virtual environment.

Scripts in WorkAdventure can be implemented in two main ways: inside the map or in an iFrame. When implementing a script inside a map, the script is directly referenced by including a JavaScript file within the map's properties, which can use relative URLs if the script file is close to the map . On the other hand, implementing a script in an iFrame involves adding a script in a separate HTML page that allows importing the WorkAdventure client API library, enabling interactions facilitated by the library . The key difference is that map-based scripts are confined to the specific map context, whereas iFrame scripts can expand functionality through additional web interfaces.

The iFrame in WorkAdventure is sandboxed primarily for security reasons; it prevents potentially malicious scripts from affecting users outside the intended scope. This sandboxing means that scripts within the iFrame have restrictions on their execution environment, including a lack of origin, which prevents them from initiating actions that affect other users directly . Consequently, operations such as altering the global state or accessing external resources must explicitly relax these restrictions through headers like Access-Control-Allow-Origin . While this ensures safety and integrity, it also limits the ease with which different parts of the application can interact.

Scripts in WorkAdventure run only in the browser of the current user, meaning they cannot trigger changes that affect multiple users' screens at the same time . This limitation implies that shared experiences or synchronized actions across users must be managed differently, often requiring server-side orchestration or API-based communication to achieve uniformity. As a result, developers may face challenges in creating consistent multi-user experiences using only client-side scripting, possibly affecting user experience by causing discrepancies in behavior and interaction across different client sessions.

The Map Scripting API in WorkAdventure supports the creation of First Time User Experiences (FTUE) by allowing developers to script initial interactions that introduce new users to the environment through guided actions. This involves setting up scripts that trigger welcoming pop-ups or tutorial steps when a user enters the map for the first time. Such scripts can present crucial information or navigation tips, ensuring users engage effectively from the onset, reducing confusion and improving user retention . By using specific map properties and scripting intelligence, developers can craft personalized introductory flows that adapt to user actions.

To enable communication between an iFrame and WorkAdventure for sending a message to a chat using TypeScript, the developer must first set the openWebsiteAllowApi property to 'true' in the iFrame. This allows the iFrame to interact with WorkAdventure's API. The developer then needs to import the WorkAdventure client API JavaScript library from 'https://play.workadventu.re/iframe_api.js' into the iFrame . With these settings, the developer can now use the WA.chat.sendChatMessage method to send a message to the chat .

By allowing TypeScript in its scripting API, WorkAdventure enhances the development process by providing strong typing, which improves code quality and reduces runtime errors through compile-time checks. TypeScript also offers better tooling support, enabling features like autocompletion, refactoring, and clearer documentation for developers using the WorkAdventure scripting environment . This feature is particularly beneficial in complex projects, as it facilitates maintainability and scalability of code bases.

Special zones in map scripting with WorkAdventure are defined areas within a map that trigger specific interactions when users interact with them. These zones can enhance user interaction by providing interactive elements such as pop-up notifications, user engagements with non-playing characters (NPCs), or linking actions that influence other features like eCommerce transactions when users step into these areas . By using map properties and scripting, developers can create enriched scenarios offering dynamic content delivery and real-time engagement tailored to user behaviors.

Including non-playing characters (NPCs) through scripting in WorkAdventure can significantly enhance user engagement by providing interactive and dynamic content within the map environment. NPCs can serve as guides, narrators, or quest providers, offering users a sense of purpose and direction in exploring the environment . This feature can lead to more immersive and personalized experiences, encouraging prolonged participation and repeat visits. Moreover, NPCs can be scripted to interact contextually with users, responding to their actions or choices, thereby fostering an environment of exploration and discovery that captivates users and deepens their interaction with the virtual world.

You might also like