Open topic with navigation

Vizard 7 » Reference » Flow control » Actions » Action basics

7.6

Actions Basics

Actions are an easy way to animate 3D geometry nodes and views. They're also handy in setting up a variety of events (timing, input, etc.). Actions can do things that would otherwise have to be done frame by frame in a callback function.  There are many built-in Vizard actions.  Some examples:

vizact.moveTo( [xyz], speed ) : animates a node moving from its current position to the given point at the given speed.

vizact.call( function, arguments ) : calls the given function and immediately finishes.

Each node and view object has a queue of actions.  For an action to operate on a node, you must add it to the node's action queue.  When one action is finished, the next one in the queue starts.

The vizact library contains many commonly used actions.  Actions can be animations (translating, rotating, scaling, fading, morphing …), synchronizations (waiting for key press, elapsed time, signal …), or simply a single command (playing sound, applying texture, changing appearance, etc.).  You can find a list of actions in the vizact module here.

Adding Actions

Here is a very simple example of creating an action to spin a node forever:

The variable spinForever contains the ActionData object that has the kind of spin we want the node to perform. This action can now be added to any object, any number of times. When you add an action to an object it will be placed at the end of the objects queue or waiting list. Once the object is finished performing an action it will begin the next action in the list. The action controller handles all the details of updating an action, checking when it is finished, and moving on to the next action.  The following code makes the node spin to the given orientation, then moves the node after the spinning is complete.  

The ActionData object returned by vizact functions, such as <vizact>.moveTo(), contains instructions that modify any 3D object.  When an ActionData object is added to a node, the node places an instance/copy, of the ActionData in its own queue/pool.   Thus, ActionData objects are reusable and can be applied to many nodes.  

Managing Currently Executing Actions

You can tell a node to stop its current action, clear its queue of actions, or both. The following command will force an object to stop performing any actions and move on to the next action in the list:

<node3d>.endAction( pool = 0 ) : Kills the current action and executes next action in queue.

<node3d>.clearActionList( pool = 0 ) : Removes all actions in the queue.  Current action is unaffected.

<node3d>.clearActions( pool = 0 ) : Kills the current action and removes all actions in the queue

Parallel Actions

What if you wanted to perform two actions simultaneously? Let's say you wanted an object to spin while it was moving. If you add the spin action then the move action, the object will move only after it has finished spinning.

To perform actions at the same time, each node has multiple queue/waiting lists.  Vizard calls these pools and each pool executes its actions independently of the others.  The following code makes an object do the move and spin simultaneously.

The above code sample adds the spin action to pool 0 and the move action to pool 1. If you do not specify a pool when adding actions, it will default to pool 0.  The action controller has an infinite number of action pools.  

You can also use the vizact.parallel( [action1, action2, ...] ) action to have multiple actions execute at once in a single action pool.  

Action Interpolators

Many of the animation-based actions in the vizact module support non-linear interpolations. For example, the vizact.easeInOut interpolator can be used to slowly ease in and out of the animation.

The following table describes all the available interpolators in the vizact module:

Vizard comes with a script that allows you to easily view the effect of the various easing interpolators included with vizact. The script is located at \examples\actions\ActionInterpolatorViewer.py.

Turning function calls into animated actions

Many Vizard functions can be turned into animated actions using vizact.mix in combination with one of the following commands:

vizact.call

vizact.method.[name]

viztask.waitCall

This is best illustrated with an example. The viz.clearcolor function accepts a single RGB value and uses that to set the background color. Calling this function every frame with gradual changes to the RGB value would result in a background that fades from one color to another. With just a few lines of code we can implement this action using vizact.mix.

First, a mix object is created. A start value (viz.BLACK), end value (viz.WHITE), duration (5 seconds), and interpolation method are defined:

Next, the viz.clearcolor function is called every frame from viztask.waitCall until the mix conditions are complete. The resulting animation is a background fade from black to white:

Creating your own actions

You can create your own actions with Python code. Vizard's built-in actions are all coded in the vizact.py Python file which you can use as a starting point for your own actions.  This page describes how to create your own actions.  

See also

In this section:

Action synchronization and management

Sequences

Dynamic parameters

Node commands as actions

Creating your own actions

Actions command table

Other sections:

Tutorial: Using actions

Task basics

Director basics

Timer basics

Animation path basics

Event Basics

Event Reference

Example scripts:

Actions

Event callbacks