Note: This PRAction documentation is out-dated and is for an older (pre-GMS v2.3) version of PRAction. For the most up-to-date docs on the latest version of PRAction, please refer to this page as well as the documentation included in the PRAction package.

Documentation Topics
Article

Creating Compound Actions

After creating a few simple actions, you are probably ready for something more. Compound actions are actions that are combined together to create more complex animations, and that's where things start getting really interesting!

PRAction has a few built-in compound actions to get you started quickly. Let's have a look at one:

var bounce = PRActionQBounce(40, 90, 0, PRActionEaseIdCubicOut, PRActionEaseIdCubicIn, 1);

The above code creates an action that, when played by an object, will bounce that object repeatedly up and down. So, why is this a compound action? Well, because it creates an upward movement action and a downward movement action, then it puts them together in sequence, and then repeats that sequence forever. This introduces two new concepts: Sequence actions and Repeater actions.

Sequence actions is a container type of action that allows you to string together multiple actions that will play one after the other in sequence. Creating one is simple. Let's begin creating a simple bounce action of our own. First, we will need the 2 movement actions:

var moveDown = PRActionMoveYBy(40, PRActionEaseIdCubicIn, 0.5);
var moveUp = PRActionMoveYBy(-40, PRActionEaseIdCubicOut, 0.5);

Now, we will want to play those 2 actions one after the other. To do this, we need a sequence action. Let’s do that now:

var sequence = PRActionSequence(moveDown, moveUp);

If you were to play this action against an object now, you will see the object first moves down and then, when that animation is done, it moves back up. Great! So we have one bounce, but now we need to repeat it forever so we can have a completed bouncing animation. For this, we need another container action, a repeater. We can create one that will repeat our sequence action an unlimited number of times, like this:

var bounceAnim = PRActionRepeatForever(sequence);

And there we have it! Our completed custom bouncing compound action. Let's play it:

PRActionPlay(self, bounceAnim);

You will now find your object happily bouncing up and down! Container actions are extremely useful, especially sequence actions. You can use them to create simple pre-scripted paths that an object travels, like the above bounce animation, or more complex ones like having a game character navigate a dangerous environment by running, jumping, rolling and climbing his way through it.

There is one more container type of action to you should know: group actions. A group action is similar to a sequence action except that instead of running the contained actions one at a time, the group action runs them all at the same time. Let’s look at another example. Let's say that we want to program a simple sentry that patrols in a rectangular pattern and rotates 90 degrees every second while patrolling. That's 2 actions grouped together: one for the patrol pattern, and one for rotating, running at the same time, but independently. So, let's create the patrol route first:

var patrolPath = PRActionSequence(
	PRActionMoveXBy(300, PRActionEaseIdSinusoidalInOut, 2),
	PRActionMoveYBy(300, PRActionEaseIdSinusoidalInOut, 2),
	PRActionMoveXBy(-300, PRActionEaseIdSinusoidalInOut, 2),
	PRActionMoveYBy(-300, PRActionEaseIdSinusoidalInOut, 2),
	);

Ok, we now have a sequence action that will move an object 300 pixels to the right, then 300 down, then 300 left, and finally 300 up. Each leg will take 2 seconds to perform. Now let's create an action that will perform a 90 degree rotation, and then wait 1 second:

var rotate = PRActionSequence(
	PRActionRotateBy(-90, PRActionEaseIdExponentialInOut, 0.5),
	PRActionWait(1)
	);

Now, let's create a group action that will play these actions simultaneously and repeatedly:

var group = PRActionGroup(
	PRActionRepeatForever(patrolPath),
	PRActionRepeatForever(rotate),
	);

And finally, make our sentry object play the action:

PRActionPlay(simpleSentry, group);

You'll notice that the sentry will move along the rectangular path, and rotate 90 degrees every second. What's important here is that each action in the group will begin simultaneously when the group action is played, but they are independent of each other when playing. In other words, one action does not wait for the other to finish before repeating it's own action. In this grouped action, the patrol path action takes 8 seconds to complete each cycle while the rotate action only takes 1.5 seconds, including the 1 second wait. If these two actions, for example, did not repeat, the total duration of the group animation would be 8 seconds and the group action would end once the longest animation playing has stopped.

One final important note about container actions is this: they can be nested together. So you can create a sequence action that consists of multiple other sequence, group and repeater actions which they themselves can contain other groups, sequences and repeaters, and so on. This means that a single action can contain an entire tree structure of scripted actions that can play some very long and complex animations indeed.