Monday, February 26, 2018

Idle Engine: Javascript for our Virtual Tabletops

We are happy to announce that Idle Engine, our Javascript engine, has been integrated for use in Mote.

It will take some more updates to translate all of the functions of the Motescript API in order for them to work in Javascript, but this shouldn't take too long.

A discussion thread was opened for this feature, where the rolling list of function conversions, can also be found.

Javascript (JS) brings with it faster script execution speeds. It also makes our VTTs more accessible to a large number of users that are versed with the Javascript language. JS is also (arguably) a much easier language to learn over Mote's inherent scripting system, which many say holds a lot of idiosyncrasies not found in "popular" scripting languages. 

Some may say that other languages are more suited for scripting within the JVM (Groovy, for example). But the choice for Javascript was based on its relevance to the heavy use of HTML forms and views (e.g. in character sheets, input forms etc, as well as JSON, which is the main data structure used within our applications.

Like our earlier blog post on HTML5, this post will change over time, as the Javascript feature matures. Do come by from time to time, to keep up with any updates we make :)

How to write and use Javascript macros:

  • Mote's Javascript feature is only available to subscribers of Sandstorm's Full-feature plan. Full-feature users are able to write macros using JS.
  • Clients connecting to sessions hosted by Full-feature subscribers, can run these macros, without needing to be subscribed to the Full-feature plan.
  • You create a JS macro in the usual ways Motescript macros are made; either by making a macro button, or by using script.
  • In order for Mote to know where to send the script, you have to make sure you set the macro content type to "Javascript".
  • This property can be accessed via the Macro Properties Panel, which is integrated into the Macro Editor. You can open this panel up by hitting F5, or by clicking the 1st button, top-left, on the editor's toolbar.
  • Before you start writing your script, do remember to set code completion, appropriately. You can do this by selecting Javascript on the dropdown menu on the editor toolbar. By default, it's set to Motescript.

Things to note:

  • Do not expect JS macros to behave exactly as those written in Motescript. Idle Engine has no relation to the Motescript scripting language and parser.
  • For long-time Motescript writers, JS does not employ any of the delay/deferment tricks of Motescript i.e. context.delay, etc.
  • Script events, like onCampaignLoad, have not yet been converted. Rest assured, this will be tackled soon.
  • JS is single-threaded. While it is possible to open up multi-threading, this will not be tackled anytime soon.
  • Invoking other macros, is not yet possible, because the relevant bits that enables this in Motescript, have yet to be converted. This will be tackled soon. 
  • This feature fully functionaly, but is not yet mature, and will need community input, in order to make it the best it can be. We'll also work as fast as the community is interested in this.

Version 1.15

Javascript is here :)

You can read more about it on our blog post, which will be updated, from time to time, to reflect advancements in this feature.

The entirety of the Motescript API will take a few updates to get converted for Javascript use, we appreciate any feedback from the community as to which functions or function groups, to prioritize.

You can join the discussion thread we created, just for this topic.

What's new:
  • Javascript!
  • Macro editor improvements, both for Motescript and Javascript code completion. 
  • Started tackling the monolithic Token data dissemination problem. One beneficiary of this change is that you will notice improvements in the creation of macro buttons, via script.
  • Error reporting presentation
  • Name conflict resolution during the creation of a new map
  • Macro editor dock tab referencing
  • Links that route to areas in the script that cause errors
  • Macro properties panel display using the Macro button context menu
  • Code refactoring
  • Several auto-reported issues

Thursday, February 15, 2018

Version 1.14

As stated on the previous release, HTML5 has been imported into Mote. Read more about it here.
We were supposed to release 1.13, which lays the foundation for Javascript and extended macro editor support, but due to reports that came in prior to its release, and the progress that then came in with regard to HTML5, Mote's version number has been bumped up to 1.14.

What's new:
  • HTML5 Forms and Views
  • The macro editor is better than ever, with enhancements for the other supported content (HTML, XML, Javascript, CSS)
  • Minor update to hotkey mapping for the macro editor
  • Foundation for Javascript, implemented.
  • File saving process
  • Macro editor template insertion behavior e.g. alt+h
  • Error reporting
  • Bugs submitted via auto-reports

HTML5 Views and Forms

HTML5 is now available in Mote :)

Given it's a new feature, and an imported one at that (from Sift), there will likely be some kinks to iron out. This post will change over time, so do come back to check for updates, from time to time.

Things to consider:

  • In order to display HTML5 forms and views, you have to be logged into Sandstorm, and the session host should be subscribed to the full-feature plan.
  • To differentiate HTML5 code from older HTML versions, you must declare the document type at the top i.e. <DOCTYPE html>, which keeps to actual standards for HTML5. 

    If this is not present during runtime, the HTML content will be evaluated using the old HTML standard (3.2)
  • There is no in-form expression evaluation.

    Third I is an independent component and we have no intentions or plans to mimic MT/Mote-style Frames and Dialogs, where script is interspersed within HTML. 

    Contemporary standards for HTML advocate a separation of concerns, and our HTML5 feature provides means to accomplish dynamism, without the need for such expression evaluation.
  • Due to security considerations, Javascript cannot be referenced (i.e. <script src>), either locally, in-app, or externally.

    We are creating a white list where users submit useful and safe "libraries" for evaluation. If they pass muster, users can then reference them for their HTML5 content.

    Scripts bound within the script tag (<script>code</script>), will be allowed evaluation, as well as scripts referenced from library tokens.

2 Ways to Display HTML5

  • Directly from a Macro Button - Starting in version 1.14, users can directly launch HTML frames and dialogs, without using scripts. This works for the current HTML feature, as well. You can do this by:
    1. Create a macro button
    2. Enter HTML content. Again, remember to have the document type stated at the very top (<DOCTYPE html>).
    3. Hit F5, or click the 1st button on the macro editor toolbar, to open the Macro Properties panel
    4. Change the Content Type to HTML
    5. This will enable a couple of controls specific to HTML content.
      • Associate CSS - a convenience functionality to associate a macro containing (usually monolithic) CSS, instead of doing it via the usual link tag. In order to be included in this dropdown list, macros containing CSS must gave its content type set to "Cascading Style Sheet"

        For HTML5, all CSS references are collated for use, this includes CSS associated via this control, and CSS content referenced through link tags.
      • HTML Properties - The items in here are self-explanatory, but let's go over them briefly:
        • Width and Height - these values are for the containing window for the HTML form/view, and not for the actual HTML content. You will still have to define such values, in either the HTML content, or any associated CSS.
        • Transparent - HTML5 only. This affects the actual HTML5 form/view. Used mainly for visual effect.
        • Modal - parlance for a "blocking" window. What it does is limit input to the dialog only, preventing interaction with other components of the app's UI.

          Unfortunately, we missed committing the toggle that tells the app whether or not this macro launches a frame or dialog (sorry, we'll get it in on the next release!).
      • User Data - HTML5 only. This is a convenience control to pass data into the HTML form/view.

        Acceptable types of data are strings, numbers, and JSON objects or arrays.

        You can reference this passed data via the reserved variable window.args. Depending on what you passed, you can access its contents just like you would with any other Javascript entity e.g. window.args[0] (JSON array), window.args.key (JSON object), or just (if what was passed was a "primitive" value i.e. number, string).
  • Window API: All the functionality present in macro buttons, are available via This includes passing user data and HTML window properties.

    Furthermore, macro.create (known as createMacro in MT) was also expanded to reflect these new additions. Please review code completion, to know more about the changes to these functions. We will update this post further, as this feature matures.

Special Referencing

The following are similar to existing "internal" referencing. Note, these do not pass through the MScript parser (i.e This is not  in-form expression evaluation.):

For script tags (<script src=source>

  • macro@lib:token
  • macro@this - references the token where the running macro is located. In place of this, you can just do macro without the "@this".

For image tags (<img src=source>)
  • this - this gets the image of the token this macro is located on.
  • token.imageId - same as above
  • asset:// protocol - an internal protocol that fetches from the host or image asset cache 
  • image tokens (i.e. tokens named with the prefix "image:" e.g. image:token) - fetches the image of the referenced token.
For link tags  referencing CSS (<link rel="stylesheet" href=source>)

  • <css_macro_id>@this queries the token where this macro is located for the css macro referred to.
  • <css_macro_id>@macro.location() - same as above
  • Directly referencing library tokens e.g. <css_macro_id>@lib:token

The Window Host object

The Host object is a child of the Window object that holds several functions that serve as intermediaries between the HTML5 view and the Mote's underlying Java code. Current functions usable in form Javascript are:
  • - triggers a page reload
  • - updates the view with the passed HTML.
  • - closes the parent window (frame or dialog)

Passing data to the HTML5 view

As mentioned above, data can be passed as window.args, to be used in the HTML view.

Passing data back to the executing macro

When you want to return data back to the executing macro (when modal dialogs are used), or just to Mote, where it exists as data bound to the originating window, you pass it back via The usual acceptable data types can be passed i.e. string, numbers, JSON.

In macros, you can then reference this data by using the function. You can find more information on its usage, by consulting code-completion.

Submitting Form Data

When you want to submit a form, using <input type="submit">, won't do anything. Instead, use <button> tag (or the older <input type="button">), and set its onclick event to process the form's data and return it to the macro execution context.

Every user-created HTML5 window has a Return object, which you is used to send data back, via its set member method. Supported data types are numbers, strings, and JSON arrays or objects.

Here's some pseudo code that encapsulates the idea:

<!DOCTYPE html>
function ret() {   //process data to be returned;}</script>

<button onclick="ret()">Submit</button></body></html>

Video Hangouts

Subscribers to Sandstorm's Full-feature plan can now host video hangouts in their sessions! When creating a server, just make sure you...