Browser Interaction

javascript_001

3DVIA Studio is a real-time 3D authoring solution for developing playable, online interactive experiences (e.g., training simulations, games, etc.).

This article deals with the process of establishing communication between a 3DVIA Studio experience and its embedded Web page (on 3DVIA.com, a blog or wherever). Read on to learn both sides of communication: the experience to the Web page and vice versa. Some baseline knowledge of 3DVIA Studio is recommended; we encourage you to read through the scripts as they are introduced and to study their working mechanisms.

Prerequisites

Make sure you download the project file supporting this tutorial on 3DVIA here.

  • 3DVIA Studio User Interface

You should be familiar with the key 3DVIA Studio interface elements, such as the views (property view, project view, editors).

  • Scripting Basics

We assume that you already have a grasp of basic scripting principles.

  • Proper 3DVIA Account

The JavaScript feature needs to be activated in your account settings (contact your 3DVIA Studio sales rep).

From the experience to the Web page…

This is the first direction of the communication process where you must execute a simple JS function, or a JS function the Web page can access. Since this JS function is available from the Web page embedding the player, you can call it from the experience. In this direction (from experience to Web page), we will use the Web Manager (vkWebManager*), which can be seen as a set of functions or a toolkit. The Web Manager deals with the integration of a 3DVIA Studio experience in a Web environment.

To see an example of how to implement this functionality, click here.

Execute a JavaScript Item in Schematic

The building block ExecuteScript allows you to call the JavaScript engine of the browser embedding the experience.

By using this building block, JavaScript functions can be called that are available from the Web page or even executed directly in the experience. To achieve this, you must use the BB in a schematic function or a schematic task. You may also use it in a function or task. The function can be triggered by an event of your choosing (vkClickablexxxEvent, vkxxxZoneEvent, etc.), or called in your code once the task is defined with the conditional situation of when you want to get through the BB. Basically, the function executes the content of the first BB input Command, a vkString corresponding to a JS command, in the Web page. The second BB input Language corresponds to the language of the executed script, and in our case, should be set to JavaScript (NOTE: case sensitivity).

javascript_experience_to_web_Schematic

Execute a JavaScript Item in VSL

As for the schematic, you will use vkWebManager::ExecuteScript() to call a JavaScript function, executed in your Web page or to execute a longer script, which you will describe in the experience.

The following piece of code is an example of what you may write:

// Definition of the function JS_VSLLauncher
void JS_VSL::JS_VSLLauncher()
{
// Call a JS function from the experience, in the web page, using VSL
vkWebManager* wman = vkWebManager::InstancePtr();
vkString strCommand("alert(‘You clicked on the VSL Button’)");
wman.ExecuteScript(strCommand, "JavaScript");
}

…and from the Web page to the experience

A 3DVIA Studio experience embedded in a Web page can easily be controlled from this page. If we deal with the Web manager, it’s fully transparent and the mechanism is slightly different …

The 3DVIA Studio plugin is a JavaScript object in the Web page and, for this reason, a JS command can be executed toward this target. This JS event contains a 3DVIA Studio event, which is transferred by the player to the 3DVIA Studio events system. It can then trigger a function or be caught by any proper item (WaitEvent building block, VSL task…).

Create a new proper event type

As mentioned before, the main idea is to use the events system of 3DVIA Studio. The first step is to create a specific type of the event the player will transfer to the infrastructure side. You could send an already existing event through the JS event, like a vkClickableClickEvent event, but by creating your own type of event, you’ll be able to add specific parameters and control exactly what’s coming from the Web. In the behavior dealing with the JavaScript (e.g. create a JavaScript manager in your project, or a behavior connected to the actor affected by the Web page), you need to create a new subtype. This new type will derive from the class vkUserEvent (see screenshot). It will then be listed as a new trigger in the function section of the behaviors. You can add any members you need in this event type by editing in the Behavior Workset.

javascript_user_event_type

Set a mechanism to catch the event

Once this type exists, a mechanism is needed to catch the event when it’s transferred by the player to the experience. The mechanism may be:

  • a function trigger
  • a WaitEvent BB in a task

javascript_06javascript_04

Send Info from the Web Page to Experience

We’ve seen the experience-side part of the topic, let’s investigate the Web page side. The plugin (seen as a JavaScript object here) receives a command, containing the information readable by the experience itself. In order to achieve the “info transfer,” you need to match the following syntax for the JS command sent to the plugin:

SendEvent('JSBehavior::vkJSEvent','Stage:Actor#Component',values_of_event_type_members)

Where:

  • JSBehavior is the name of the behavior in which the event type you’ve just created above is defined
  • vkJSEvent is the name of the event type
  • Stage:Actor:Component fully describes the path to the behavior/component which will receive the event (for example, DefaultStage:MyActor:JavaScriptManager)

Here is a simple example of what the HTML code should be/could be:

<html>
<head><title>JavaScript to Studio</title></head>
<body>
  <a href="#" onclick = "launcher();" >JavaScript: Web to Experience</a>
  <script type="text/javascript" language="JavaScript" src="http://player.studio.3dvia.com/embed.js"></script>
  <script type="text/javascript" language="JavaScript">
    player3dvia.embedHere('600', '300', 'experience_id');
  </script>
  <script type="text/javascript" language="JavaScript">
    function Get3dviaPlayer() {
      return document.getElementById('3dvia-player');
    }
    function launcher() {
      var commandstring = "SendEvent('JavaScriptManager::vkJavaScriptEvent',
             'DefaultStage:GameManager#JavaScriptManager','playerName')";
      Get3dviaPlayer().ExecuteCommand(commandstring);
    }
  </script>
</body>
</html>

In this example, the experience is loaded in the 3DVIA Player browser plugin thanks to the player3dvia.embedHere JavaScript method (see Web Deployment for details and alternatives). This method sets the DOM id of the player by default to ‘3dvia-player’, enabling the possibility to find it and send it a vkJavaScriptEvent.

On the experience side, the developer created this new type of event named vkJavaScriptEvent and defined in the behavior JavaScriptManager. The event will be received in the component of this JavaScriptManager type component present in the ring of the actor GameManager in the DefaultStage. Finally, the event type contains a single vkString member, set to playerName in the event sent to the experience.

“JavaScript and 3DVIA Studio” Example

This example is illustrates JavaScript’s use in 3DVIA Studio experiences. You’ll see two simple ways to send and receive commands and events to and from the Web page in the corresponding archive.

Remember this project corresponds to the current Web page, which contains the input field and the ‘sender’ link. You’ll need to use the same items in your setup to retrieve the same behaviors.

First, launch the experience, then enter the name you wish to display in the experience by entering it in the text field and clicking the link below.

Click here to send the event