PyPRP:Animations
Contents
Introduction
This document is not meant to explain how to create animations in Blender. There are plenty of other resources for that. This is not even really a tutorial. This will simply give you the information necessary to use animations in ages. This includes, what types of animations the plugin will recognize, how it will handle them, and how to control them. -Nadnerb
Default Animations
PyPRP will, by default, export all of the following IPO curves if they are present on any Objects: LocX, LocY, LocZ, RotX, RotY, RotZ, as well as the R, G, B curves if they are present on any Lamps. These default animations will be named after the object they were found on, and will be set to start automatically, and loop infinitely.
Unlike with layer animations, PyPRP can tell the difference between linear and bezier IPO curves on object animations, and will export them accordingly. To change a curve's mode, press T in the IPO curve editor window.
In order for an object to have it's location or rotation animated, it MUST be an Actor. (ie, it must have a CoordinateInterface) Be sure to press the Actor button in the object's logic panel. If an animation tries to run on a non-actor, it will crash the game.
Named Animations
You can name an animation, stop it from autostarting or looping, and control how much of the animation is played by adding a script like the one shown below. Animations is a list of named animations that should be created from a single IPO.
For instance, the first animation could be set to start automatically, loop, and run from 0 seconds to 1 second. This would repeatedly play the first second of the complete animation on link in. The second could be set to not loop or autostart, and run from 1 seconds to 8 seconds. This would be the rest of the animation, which could be started by some action during gameplay using an animation command message. It is not recommended that you set more than one animation to autostart on the same object.
<object>:
animations:
- name: <animation name>
autostart: <[0 | 1]>
loop: <[0 | 1]>
loopstart: <start time in seconds>
loopend: <end time in seconds>
- name: <animation name>
autostart: <[0 | 1]>
loop: <[0 | 1]>
loopstart: <start time in seconds>
loopend: <end time in seconds>
"time in seconds" assumes 30 frames per second.
Animation Messages
In order to start an animation that is not set to play automatically, you will need to send an AnimCmdMsg. Below is an example responder script to do this. This responder must be activated by a logic script, such as those used to make a clickable.
<object>:
logic:
actions:
- type: responder
name: <responder name>
responder:
states:
- cmds:
- type: animcmdmsg
params:
receivers:
- 006D:<name of animated object>
animname: <name of animation>
cmds:
- continue
waiton: -1
nextstate: 1
waittocmd: 0
curstate: 0
flags:
- detecttrigger
Play an Animation Backwards
It is possible to play animations backwards. So for a simple door you can use the same animation to open and close it. For a backwards animation you add the command "setbackwards" in the AnimCmdMsg.
- type: animcmdmsg
params:
receivers:
- 006D:<name of animated object>
animname: <name of animation>
cmds:
- setbackwards
- continue
For the forwards animation you must add the "setforewards" command. If you forget this the animation will remain stuck in reverse.
- type: animcmdmsg
params:
receivers:
- 006D:<name of animated object>
animname: <name of animation>
cmds:
- setforewards
- continue
Note: There is no spelling error in "setforewards". PyPRP conforms to Cyan's code here.
Animation and Parenting
PyPRP will correctly export objects that are parented to each other. Child objects will inherit their parent's transforms. Parenting can be used with animations, but animations do not entirely support Blender's method of scaling parented objects. If a parent or child object has scaling applied to it, and is animated, it is likely to behave incorrectly in game. Single animated objects with scaling should work correctly, however.
Global Animations
Global animations are used by Cyan for day/night cycle animations. A global animation has one parameter, a reference to an SDL variable. This variable stores the current time of day. The length of a day is stored in the age file, and can be set in the book text in Blender. The length is in hours. A global animation will be extended so that it's total length is equal to the day length, and the state of the animation will be controlled by the time of day SDL variable. You can make a global animation using a script like the one below.
<object>:
animations:
- type: ageglobalanim
name: <animation name>
globalvar: <SDL var name>
This will require that your SDL STATEDESC for the age include a line like this:
VAR AGETIMEOFDAY <SDL var name>[1]
Example Ages
For the purpose of demonstrating what is possible using the current animation support, I have provided an age and corresponding blend file as example files.