How to add new functions in the scripting API#

This documentation is intended at contributors who want to participate in the development of WorkAdventure itself.
Before reading this, please be sure you are familiar with the scripting API.

The scripting API allows map developers to add dynamic features in their maps.

Why extend the scripting API?#

The philosophy behind WorkAdventure is to build a platform that is as open as possible. Part of this strategy is to
offer map developers the ability to turn a WorkAdventures map into something unexpected, using the API. For instance,
you could use it to develop games (we have seen a PacMan and a mine-sweeper on WorkAdventure!)

We started working on the WorkAdventure scripting API with this in mind, but at some point, maybe you will find that
a feature is missing in the API. This article is here to explain to you how to add this feature.

How to extend the scripting API?#

Extending the scripting API means modifying the core of WorkAdventure. You can of course run these
modifications on your self-hosted instance.
But if you want to share it with the wider community, I strongly encourage you to start by opening an issue
on GitHub before starting the development. Check with the core maintainers that they are willing to merge your idea
before starting developing it. Once a new function makes it into the scripting API, it is very difficult to make it
evolve (or to deprecate), so the design of the function you add needs to be carefully considered.

How does it work?#

Scripts are executed in the browser, inside an iframe.

The iframe allows WorkAdventure to isolate the script in a sandbox. Because the iframe is sandbox (or on a different
domain than the WorkAdventure server), scripts cannot directly manipulate the DOM of WorkAdventure. They also cannot
directly access Phaser objects (Phaser is the game engine used in WorkAdventure). This is by-design. Since anyone
can contribute a map, we cannot allow anyone to run any code in the scope of the WorkAdventure server (that would be
a huge XSS security flaw).

Instead, the only way the script can interact with WorkAdventure is by sending messages using the
postMessage API.

We want to make life easy for map developers. So instead of asking them to directly send messages using the postMessage
API, we provide a nice library that does this work for them. This library is what we call the "Scripting API" (we sometimes
refer to it as the "Client API").

The scripting API provides the global WA object.

A simple example#

So let's take an example with a sample script:

WA.chat.sendChatMessage('Hello world!', 'John Doe');

When this script is called, the scripting API is dispatching a JSON message to WorkAdventure.

In our case, the sendChatMessage function looks like this:

src/Api/Iframe/chat.ts

    sendChatMessage(message: string, author: string) {
        sendToWorkadventure({
            type: "chat",
            data: {
                message: message,
                author: author,
            },
        });
    }

The sendToWorkadventure function is a utility function that dispatches the message to the main frame.

In WorkAdventure, the message is received in the IframeListener listener class.
This class is in charge of analyzing the JSON messages received and dispatching them to the right place in the WorkAdventure application.

The message callback implemented in IframeListener is a giant (and disgusting) if statement branching to the correct
part of the code depending on the type property.

src/Api/IframeListener.ts

// ...
    } else if (payload.type === "setProperty" && isSetPropertyEvent(payload.data)) {
        this._setPropertyStream.next(payload.data);
    } else if (payload.type === "chat" && isChatEvent(payload.data)) {
        scriptUtils.sendAnonymousChat(payload.data);
    } else if (payload.type === "openPopup" && isOpenPopupEvent(payload.data)) {
        this._openPopupStream.next(payload.data);
    } else if (payload.type === "closePopup" && isClosePopupEvent(payload.data)) {
// ...

In this particular case, we call scriptUtils.sendAnonymousChat that is doing the work of displaying the chat message.

Scripting API entry point#

The WA object originates from the scripting API. This script is hosted on the front server, at https://[front_WA_server]/iframe_api.js..

The entry point for this script is the file front/src/iframe_api.ts.
All the other files dedicated to the iframe API are located in the src/Api/iframe directory.

Utility functions to exchange messages#

In the example above, we already saw you can easily send a message from the iframe to WorkAdventure using the
sendToWorkadventure utility function.

Of course, messaging can go the other way around and WorkAdventure can also send messages to the iframes.
We use the IFrameListener.postMessage function for this.

Finally, there is a last type of utility function (a quite powerful one). It is quite common to need to call a function
from the iframe in WorkAdventure, and to expect a response. For those use cases, the iframe API comes with a
queryWorkadventure utility function.

Types#

The JSON messages sent over the postMessage API are strictly defined using Typescript types.
Those types are not defined using classical Typescript interfaces.

Indeed, Typescript interfaces only exist at compilation time but cannot be enforced on runtime. The postMessage API
is an entry point to WorkAdventure, and as with any entry point, data must be checked (otherwise, a hacker could
send specially crafted JSON packages to try to hack WA).

In WorkAdventure, we use the zod package. This package
allows us to create interfaces AND custom type guards in one go.

Let's go back at our example. Let's have a look at the JSON message sent when we want to send a chat message from the API:

sendToWorkadventure({
    type: "chat",
    data: {
        message: message,
        author: author,
    },
});

The "data" part of the message is defined in front/src/Api/Events/ChatEvent.ts:

import { z } from "zod";

export const isChatEvent = z.object({
    message: z.string(),
    author: z.string(),
});

/**
 * A message sent from the iFrame to the game to add a message in the chat.
 */
export type ChatEvent = z.infer<typeof isChatEvent>;

Using the zod library, we start by writing a type guard function (isChatEvent).
From this type guard, the library can automatically generate the ChatEvent type that we can refer in our code.

The advantage of this technique is that, at runtime, WorkAdventure can verify that the JSON message received
over the postMessage API is indeed correctly formatted.

If you are not familiar with Typescript type guards, you can read an introduction to type guards in the Typescript documentation.

Typing one way messages#

For "one-way" messages (from the iframe to WorkAdventure), the sendToWorkadventure method expects the passed
object to be of type IframeEvent<keyof IframeEventMap>.

Note: I'd like here to thank @... for helping set up this type system. It rocks ;)

The IFrameEvent type is defined in front/src/Api/Events/IframeEvent.ts:

export type IframeEventMap = {
    loadPage: LoadPageEvent;
    chat: ChatEvent;
    openPopup: OpenPopupEvent;
    closePopup: ClosePopupEvent;
    openTab: OpenTabEvent;
    // ...
    // All the possible messages go here
    // The key goes into the "type" JSON property
    // ...
};
export interface IframeEvent<T extends keyof IframeEventMap> {
    type: T;
    data: IframeEventMap[T];
}

Similarly, if you want to type messages from WorkAdventure to the iframe, there is a very similar IframeResponseEvent.

export interface IframeResponseEventMap {
    userInputChat: UserInputChatEvent;
    enterEvent: EnterLeaveEvent;
    leaveEvent: EnterLeaveEvent;
    // ...
    // All the possible messages go here
    // The key goes into the "type" JSON property
    // ...
}
export interface IframeResponseEvent<T extends keyof IframeResponseEventMap> {
    type: T;
    data: IframeResponseEventMap[T];
}

Typing queries (messages with answers)#

If you want to add a new "query" (if you are using the queryWorkadventure utility function), you will need to
define the type of the query and the type of the response.

The signature of queryWorkadventure is:

function queryWorkadventure<T extends keyof IframeQueryMap>(
    content: IframeQuery<T>
): Promise<IframeQueryMap[T]["answer"]>

Yes, that's a bit cryptic. Hopefully, all you need to know is that to add a new query, you need to edit the iframeQueryMapTypeGuards
array in front/src/Api/Events/IframeEvent.ts:

export const iframeQueryMapTypeGuards = {
    openCoWebsite: {
        query: isOpenCoWebsiteEvent,
        answer: isCoWebsite,
    },
    getCoWebsites: {
        query: tg.isUndefined,
        answer: tg.isArray(isCoWebsite),
    },
    // ...
    // the `query` key points to the type guard of the query
    // the `answer` key points to the type guard of the response
};

Responding to a query on the WorkAdventure side#

In the WorkAdventure code, each possible query should be handled by what we call an "answerer".

Registering an answerer happens using the iframeListener.registerAnswerer() method.

Here is a sample:

iframeListener.registerAnswerer("openCoWebsite", (openCoWebsiteEvent, source) => {
    // ...

    return /*...*/;
});

The registerAnswerer callback is passed the event, and should return a response (or a promise to the response) in the expected format
(the one you defined in the answer key of iframeQueryMapTypeGuards).

Important:

• there can be only one answerer registered for a given query type.
• if the answerer is not valid any more, you need to unregister the answerer using iframeListener.unregisterAnswerer.

sendToWorkadventure VS queryWorkadventure#

• sendToWorkadventure is used to send messages one way from the iframe to WorkAdventure. No response is expected. In particular
  if an error happens in WorkAdventure, the iframe will not be notified.
• queryWorkadventure is used to send queries that expect an answer. If an error happens in WorkAdventure (i.e. if an
  exception is raised), the exception will be propagated to the iframe.

Because queryWorkadventure handles exceptions properly, it can be interesting to use queryWorkadventure instead
of sendToWorkadventure, even for "one-way" messages. The return message type is simply undefined in this case.