Guild of Writers

Revision as of 11:25, 28 June 2016

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.

Note there is one additional step you need to go into the sav directory of your Uru installation and delete the .save file for your age (you only need to delete the one you are making changes on). I spent three days on this and the answer was just so simple. -J'Kla.

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 names are not local to the object and should therefore be unique. If two objects have one private animation each and those are both named "go", they may not be exported as separate animations.

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.

AnimCmdMsg List

This is the full list of all known Animation Messages. You can play with these and see what they do. The names are mostly self-explanatory.

- continue
- stop
- setlooping
- unsetlooping
- setbegin
- setend
- setloopend
- setloopbegin
- setspeed
- gototime
- setbackwards
- setforewards
- togglestate
- addcallbacks
- removecallbacks
- gotobegin
- gotoend
- gotoloopbegin
- gotoloopend
- incrementforward
- incrementbackward
- runforward
- runbackward
- playtotime
- playtopercentage
- fastforward
- gotopercent
- numcmds

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]

Remember that for SDL to work, you MUST have an age python file, and enable the agesdlhook in the Book.

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.

AnimatedDoor.age

AnimatedDoor.blend