Controllers and States


Controllers and States

ZapWorks Studio provides a number of powerful tools for animating content. Central to these tools are the concepts of controllers, states and timelines.

Controllers take responsibility for setting the values of chosen object properties. Once a property of an object has been added to a controller it cannot be added to any other controller, and that property's value is determined at all times by its controller.
Controllers contain multiple states. States define a fixed set of values for all of the properties in the controller. By switching between the states in the controller, the objects' properties are set to the values defined by those states.
Timelines make it possible to build fully custom animations between states.

Getting Started


Creating a controller

Controllers, states and timelines are managed using the panel at the bottom left of ZapWorks Studio.

New controllers can be added using the + button and should be given a unique name.

With a controller selected it's not possible to modify the value of any properties that are not part of the controller.

To add a property to a controller click the + button to the right of the property value in the "Properties" panel.

The special "base" entry in the controller panel returns the Studio to the default behaviour where properties that haven't been added to any controller can be modified.


Creating states

States can be created from the right-click menu of a controller.

Modifying the properties of an object when a state is selected will change the state's value for that property. Whenever that state is activated the property will take that value.

The example on the right shows the creation of three states and the setting of a different position for an object in each.

State Properties

Setting states' properties

When a state is activated, the default behaviour is for the controller's properties to instantly change to the values set for that state.

Alternatively a speed can be set for state on a property-by-property basis. A "slow" property will take a few seconds to reach the final value when a state is activated.

In the example on the right, the speed of the "top-right" state's sole property is set to "normal". Activating "top-right" when either of the other states is selected shows the position value change over a few seconds.

Activating States

Activating states
Activating states shortcut

Once a state has been created in the Studio it can be activated from a script when the user is experiencing the zap.

States can be dragged into scripts like any other node - with 'Insert local variable' this provides a variable that can be used to manipulate the state.

Calling the activate() function on the variable will cause the state to activate. Alternatively you can just select 'activate' from the drop down when dragging your node in to do this automatically.

The example on the right shows a pointerdown event handler script being added to the plane and the top-right state activated in its function.

The example below it shows the activate() function being called on the state from the dropdown to save time and code.

The Default State

Every controller has a default state - it's the state that is already activated when the project starts.

The default state for a controller can be changed from the right-click menu of a state.

Use Cases and Best Practices

Intro Animation

Create a state for the arrangement of the user interface once it's fully animated into view. Create another state for an arrangement before the zap has started and set it as the default. Activate the final state in the "show" script under the "root" node.

Device Orientation Changes

Create states for the user interface in arrangements for landscape and portrait. Use an accelerometer node to activate the appropriate states when the device's orientation changes.

Best Practice

Aim to keep logically distinct behaviors like these in separate controllers. This way states in each controller can be activated at the same time, avoiding any conflicts if the user rotates the device while the intro animation is playing.

More Information

For more details about using controllers and states from script check out the following reference articles:

Next article: Timelines

Open in new window