User:Moguri/GSoC2011 BGE Animation Improvements

From BlenderWiki

Name

Mitchell Stokes

Email / IRC / WWW

I can be contacted via email at mogurijin@gmail.com, and I’m also registered on blenderartists.org as Moguri. Furthermore, on freenode I frequent the #blendercoders, #gameblender, #bgecoders, and #blender channels using the nick Moguri.

Synopsis

Making use of animations in the Blender Game Engine leaves a lot to be desired. First and foremost, the BGE lacks any means by which the user can control animations from scripts. Currently animations must be done with logic bricks, which can be cumbersome. Also, when Blender combined all animations into "actions" the BGE didn't keep pace. It still splits animations up into three logic bricks: IPO (now called FCurve to better match Blender 2.5), Action (armature actions only), and Shape Action (shape keys). This old method also only allows for one IPO/FCurve action per object; it makes use of the object's currently selected action and doesn't allow for changing it at runtime. The goal of this project is to make animations friendlier and nicer to use with two main focuses: a Python API and combining everything into one "action".

Benefits to Blender

The Blender Game Engine will benefit by becoming easier to use. Animations are very important for games, yet they can be painful to use in more complex games that use almost all scripting. Also, this will be a good time to examine some animation bugs in the BGE such as Material IPOs not working in the BGE (link).

Deliverables

• Combine F-Curves, Shape Action and Armature Action logic bricks into a single "Action" logic brick
• Automatic conversion of old logic bricks to the new brick
• Support Material fcurves in the BGE
• Provide an animation Python API
• Add support for animation layers and layer blending in the BGE

Project Details

To start with, each KX_GameObject will get an ActionManager, which will contain Actions. These Actions will be setup to work with object IPOs/FCurves, Armature Actions, and Shape Keys. Most of the actual animation code will probably be reused where possible from the logic bricks. The new Action logic brick will then make calls to a KX_GameObject's ActionManager rather than handling the action itself. KX_GameObject will have a playAction() member function which will delegate playing the action to it's ActionManger:

// Something like this
void KX_GameObject::playAction(STR_String &name, int start, int end, int layer, int priority, float blendin, int play_mode, int blend_mode)
{
   this->m_action_manager->playAction(name, start, end, layer, priority, blendin, play_mode, blend_mode);
}

The data types could possibly change (name to char*; start and end to unsigned int). The ActionManager will keep an array of size MAX_ACTION_SLOTS to store actions in. Each "slot" in the array will be an action layer. Slot 0 would be the base and actions in successive layers will be blended based on which play_mode option the user selects. Every frame, the KX_Scene will loop over its active objects and update their ActionManagers. When ActionMangers are updated, they will update all currently running Actions. The Action update code will be mostly borrowed from the various animation logic bricks' update functions.

The Python API exposed to the user will look a lot like the underlying C++ call:

KX_GameObject.playAction(name, start, end, layer=0, priority=0, blendin=0, play_mode=KX_ACTION_PLAY, blend_mode=KX_ACTION_ADD):

name -- the name of the action
start -- the start frame of the action
end -- the end frame of the action
layer -- the layer the action will play in (actions in different layers are added together)
priority -- only play this action if there isn't an action currently playing in this layer with a lower priority
blendin -- the amount of blending between this animation and the previous one on this channel
play_mode -- the play mode (KX_ACTION_PLAY, KX_ACTION_LOOP)
blend_mode -- how the animation layers are to be blended together (KX_ACTION_ADD, KX_ACTION_BLEND, KX_ACTION_REPLACE)

And here is an example where a base idle (IdleBase) is combined with an idle animation for the top part of the character (IdleTop). The IdleTop could be changed out but the base (mostly the legs) would still be going. This is especially useful for things like running and attacking.

#Example
import bge

ob = bge.logic.getCurrentController().owner
ob.playAction('IdleBase', 1, 200, layer=0, play_mode=bge.logic.KX_ACTION_LOOP)
ob.playAction('IdleTop', 1, 300, layer=1, play_mode=bge.logic.KX_ACTION_LOOP)

In this example, ob is an armature object, but playAction() will be available to all objects.

The new logic brick will expose most of these options. Also, proper updates to do_versions will ensure that users using the old logic bricks will be (hopefully) smoothly transitioned to the new single logic brick.

Project Schedule

The project will be split up roughly as follows:

• Implement the ActionManger and Action for armature actions, and get the Python API going -- 1 week (I already have some of this code laying around)
• Get FCurve and Shape Action actuator functionality into the new system -- 1 weeks (these are a little trickier)
• Add animation blending -- 1 week (maybe less)
• Create the new Action logic brick and handle do_versions -- 1 week
• Bug fixing (including fixing known animation bugs), cleaning and docs -- 1 - 3 weeks

Bug fixing could also include things such as trying to make all of the bone constraints work in the BGE.

This leaves an extra week, however, I do plan to be on vacation for 1 week with family. Also, the time line given is really rough and likely to change a bit as the project progresses.

If time permits, I'd like to look at Semi-Procedural Animation for Character Locomotion, but this is probably a project of it's own.

Bio

I am a 19 year old Computer Science student at Eastern Washington University in Washington state, USA. I have been active in the Blender community for a few years now and active as a developer for 1~2 years.

My main area of focus is the Blender Game Engine where I have contributed bug fixes to areas such as lighting, dynamic loading, and the Python API. One of my fist larger BGE dev projects was helping with the new BGE Python API for Blender 2.49. Last summer I also participated in GSoC for Blender on the proposal listed here. This project was determined to be a success. It hasn't been merged to trunk yet due to the feature freeze and couple of pending issues such as some possible memory leaks and a few more uniforms that need to be added to the API. Also, there will need to be more user testing before the project is "mergeworthy". More information about my BGE projects can be found at my blog.

As far as programming languages go, I know Python and C/C++ fairly well now. I wouldn't call myself a "guru" at either, but I know my way around both languages. I also know Java, but that won't be very useful for this project.