Controllers and States
1. Introduction
Download the completed project.
In this tutorial we’re going to look at controllers and states, two concepts central to animating content within ZapWorks Studio.
Controllers take responsibility for setting the values of chosen object properties and can have many states. States define a fixed set of values for all of the properties in a controller.
You can see in this completed example, a plane transitioning between two states, left and right.
2. Starting a New Project
We’ll begin by starting a new project with a blank template.
First we’ll look at controllers, which are located in the controllers panel in the bottom left of the window.
You’ll notice that when starting a new blank project we have a couple of controllers already implemented, we'll discuss these later.
3. Creating a Controller
Let's get started by creating a new controller of our own.
To do this we click the plus button in the controllers panel and select ‘New Controller’. Giving it a name, and hitting enter or clicking 'OK' will create our new controller.
Our new controller will appear at the bottom of the controllers list.
4. Controller Properties
We need to have an object that our controller can alter the properties of, luckily we already have a plane in the scene which we can use.
You’ll notice that if you still have your controller selected and the plane highlighted, you cannot edit any of the properties. This is because we haven't added any properties to the controller yet, and only properties added to a controller can be edited by it.
Once a property of an object has been added to a controller it cannot be added to any other controller.
5. Creating a State
Before we can add properties to our controller we need at least one state within it.
By switching between states in a controller, the objects' properties are animated to the values defined by those states.
To add a state we right click on our controller and select ‘New State’ and give it a name. We’re going to define a state for the plane being on the left side of the screen so we’ll call our state ‘left’.
6. Adding a Property
Returning to our controller we can now start to add properties to it, for this example we will add the position property.
To do this we make sure our controller is highlighted in the controllers panel and select our plane in the Hierarchy and click the plus button at the right hand side of the position property.
The position of our plane will now only be accessible through the 'tutorialAnimation' controller and will be locked out if we try to change it from any other controllers, or the base entry.
The base is a special entry in the controller panel that returns the Studio to the default behaviour where properties that haven't been added to any controller, can be modified.
7. Defining State Values
Now that we have a state we can define the values we want for it. On our left state we want to have our object positioned on the left hand side of the screen, so with our left state selected we can move our plane within the scene.
This will assign the position value of the state to be that of the one we set in the scene view. You can also edit the values directly within the properties panel.
With this knowledge we can then create another state and name it ‘right’ and move our plane to the right hand side of the screen with that state selected.
Clicking between the two states within the controllers panel will now show you the object animating from one state to another.
8. Changing State Transition Settings
By default states use the ‘fast’ speed when transitioning, however you can change this by clicking on a state and selecting a different speed from the dropdown. There is also a 'Pin to start/Pin to end' dropdown, we will discuss this later.
For now let's change the speed of both of our states to ‘normal’.
9. Default States
You’ll notice that since its creation the ‘left’ state has had the word ‘default’ in brackets next to it. This denotes that it is the default state of the ‘tutorialAnimation’ controller.
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.
10. Activating a State
Now that we have a couple of states to animate between we need a way of activating them when the user views this experience on their device.
Once a state has been created in the Studio it can be activated from a Script node.
To do this we need to first add a script node, so let's add one with a pointerdown event handler to our plane, by right clicking it in the Hierarchy and selecting New > Script > pointerdown.
With ‘left’ being the default state we will want to drag in our ‘right’ state and tell it to activate from within the handler function.
We do this by selecting our script node and dragging our right state from the controllers panel into the function. From here we can select from a number of options - we’re going to choose activate.
The activate function causes the parent controller to transition to this state.
11. Preview
We can now preview our project and try it on a device. We can see the plane move to the right when we tap down on it.
12. Separating Controllers
It's best practice to keep logically distinct behaviors in separate controllers. This way, states in each controller can be activated at the same time avoiding any conflicts.
For example the included display controller is responsible for the visible, color, and enabled properties of the root node. This can be seen by clicking into either the shown or hidden state within the controller.
The orientation controller and its landscape and portrait states are tied to the accelerometer, but don’t have any properties assigned. This is a template for you to handle orientation changes and assign properties yourself.
The key takeaway here is that both of these controllers define separate behaviors and won't conflict if states from both are called at the same time.
13. Pin to Start/End
One final piece of functionality to mention when transitioning between states is the 'Pin to start/Pin to end' dropdown located next to the speed dropdown.
This hidden state within the display controller is a great example of how to use this option.
You'll notice that both enabled and visible are true / false properties, this means they cannot be transitioned over time but instead change instantaneously. As they are paired with color, a property that does transition over time, they can be set to change right at the beginning of the transition or right at the end.
In this case visible is set to false at the end using 'Pin to end', meaning the color transition will have finished, otherwise the object would be invisible before the transition could be seen. enabled on the other hand is set to false at the beginning so no interaction can occur once the hidden state has begun.
14. Next Steps
Download the completed project.
That wraps up our exploration into controllers and states and how you can use them to create simple animations.
We hope this tutorial was helpful and urge you to take a look at the Controllers and States article in the Getting Started section, as well as our reference materials.
For more complex animations, take a look at our video tutorial on Timelines.
Any issues please contact us at the following email address: support@zappar.com