Scripts

• Articles
• Introduction
• Scripting
• Studio

ZapWorks Studio makes it possible to build more complex interactivity and complex state into experiences using script nodes.

As well as letting you write your own Scripts from scratch, you can attach handler functions to node events that can be triggered as a result of:

• The user's finger movements and tapping
• Changes in device orientation (e.g. moving from landscape to portrait etc)
• A symbol (or project) being shown or hidden

Scripts are coded in a special form of JavaScript called TypeScript. It shouldn't take long to get up to speed with the language, especially with previous JavaScript or ActionScript experience. In any case, it's possible to create interesting interactive experiences using only a minimal amount of scripting.

The TypeScript Language Primer article in this documentation serves to introduce the language and is a great place to start for anyone scripting zaps for the first time.

Adding a Script Node

Scripts can be added under nodes by right-clicking on a node in the Hierarchy and selecting New > Script. You can either create a blank Script or select an event handler to be created for you.

Different nodes types can trigger different events and as such you'll get different options depending on the node.

In this example a pointerdown event handler is selected and added to a plane object. This event will be triggered when the user taps on the plane.

It's important to note that when working with multiple objects those further down the hierarchy may appear on top, but this might not be the case positionally. If you plan on adding event handlers to objects such as pointerdown, you will need to make sure they are positionally in front of other objects for it to work as expected. A simple way to do this is to change the position of the object you want to interact with, in front to have a higher Z value than the one behind it.

Script Node Basics

Clicking on a script node in the Hierarchy view will reveal its code in the central area of ZapWorks Studio.

If you created a blank Script then this will be empty ready for you to type your own code. If however you decided to choose one of the event handlers when creating the Script then you will have a function created for you attached to an event.

The code inside the function is executed when the event is triggered (or called elsewhere) - in this case when the user touches down on the plane.

ZapWorks Studio does not support pointer events on 3D objects. The workaround for this can be found in our Common 3D Issues article.

Launching a Website

All scripts have access to a special variable, Z. It is used to access the various nodes and elements of the project, in addition to the functions and features of the user's device.

For example the following code will take the user to the website that's passed in to the function:

Z.device.launchUrl("http://www.zappar.com");

Changing the Properties of a Node

It's possible to change the properties of nodes in the Hierarchy from within scripts.

Dragging a node from the Hierarchy into the Script and selecting 'Insert local variable' creates a variable that can be used to access and modify the node.

In this example the color of a plane node is changed. The color function is called, passing in an array [1, 0, 0, 1]. Colors are expressed as an array of four values for red, green, blue and opacity, each ranging from 0 to 1. This command is therefore setting the plane color to an opaque red.

Additionally you can drag a node into the Script and select 'Add an event handler' and choose from the list of events that the node in question can fire. This will create a similar event handler function to that of one added by right clicking on a node only the node it's referring to will be the name of the node you dragged in.

You may also see options to automatically call common functions on a node dragged in, again this depends on the node.

Next Steps

The scripting language is powerful and expressive and, while it's possible to create interactive experiences with only a basic understanding, the following pages give a more complete grasp of the toolset.

• The General Principles page is a more in-depth introduction to the scripting capabilities of ZapWorks Studio.
• The Scripting Reference hosts the reference documentation for the Z variable and its constituent functions and classes.