Bones

For games, exporting bone transforms is often more efficient than exporting animation curves.

Most animation data is modeled using Actions; however, data related to the current pose (for an Object using an Armature) is exposed via Object :

x = D.objects['armature']

bone = x.pose.bones['root']

bone.matrix # transform
bone.location # just the location.

(‘D’ is a shortcut for bpy.data).

Actions

In Blender 2.63, retrieve actions using:

anAction = D.actions[name]

Action.fcurves contains animation data per channel. The grouping of fcurves (in the blender UI) is cosmetic.

• FCurve.data_path refers the data being animated using a given animation curve. This could be something like ‘pose.bones["neck"].scale’. Several curves may use the same name (e.g. scale has 3 components so there may be 3 curves with the same data-path)
• FCurve.keyframe_points refers keyframes for a given curve. The main property of a Keyframe is co, which includes the time offset co.x (the frame) and property value co.y

References (Blender API docs)

• bpy.types.Object
• bpy.types.Pose
• bpy.types.PoseBone
• bpy.types.Action
• bpy.types.FCurve
• bpy.types.Keyframe

In Blender, Actions contain information about ‘reusable animations’ that can be combined to generate complex animated scenes. Actions can also be used to create catalogues of animations associated with game assets.

I might have suggested before that a 3D artist may prefer to keep several avatar models in the same blender file. Keeping models in separate files makes it (not impossible yet) more difficult to share geometry and materials between models. For the designer, ‘sharing’ may not be a very high level concept, more something like ‘copy, paste and modify’. Nice, fast and simple.

Blender actions are created while posing armatures. Unfortunately, there is not a clear way to retain the connection between an action and the armature first used to generate this action. Here’s a little experiment that illustrates this:

1. Create an armature A with a bone named ‘Bone’. Create an action X for this armature.
2. Create an armature B with a bone named ‘Bone’ (same name). Make action X current in B.
2. Observe the result.

Essentially, Blender Actions are lists of keyframes ‘per channel’; a channel is just a name; the name binds bone names. Any armature can use any action, and this will be ‘effective’ as long as the names match.
That may be powerful. Not great when we want to export per character keyframes for each action.

At this point, we may consider loading a config file listing actions for each actor, or design a little script letting us retain the original armature <> action binding when creating new actions (I think that can be done and integrated nicely with Blender). But I won’t illustrate any of the above this time. I just fallback to a naming convention for my actions, something like:

myActor.jump
myActor.nod

Since all actions are dumped in the same list, this also allows quickly locating per character actions in the Blender interface.

Let’s not learn all about Python Strings

Instead, try this:

z='funbot.jump'
p=z.split('.')
p[0] # prints 'funbot'
p[1] # prints 'jump'

Now we can match each action to a character ‘owning’ this action. You can learn more about actions and *stuff* in previous articles on this blog.

My current export script for character animation requires a naming convention for binding a character to it’s armature.  Also, the script only exports the currently selected mesh.

In this article, I illustrate how to examine a Blender scene to discover assets; I also show how to find the armature modifier associated with an animated character.

In outline, this is how to structure a script to export an asset library:

• Iterate all objects in the scene
• Retain only Mesh objects.
• For each mesh object, check whether this object uses an armature; if so, assume the object is a kind of actor or character.
• Export mesh objects as appropriate (You can learn how to do this from previous articles on this blog)

Interactive session

Let’s try the following:

s=Blender.Scene.GetCurrent()
s.objects
for x in s.objects:
	x.type

(After typing ‘x.type’ in the interactive console, press enter twice to effect the loop)

This will print the type of each object in the order they are stored in the scene. We only want to export Mesh objects. Pick any Mesh object using an armature. (in my case, index 1 in the object list).

object=s.objects[1]
for x in object.modifiers:
	if(x.type==Modifier.Types.ARMATURE):
		x

This will print something like:

[Modifier "Armature", Type "Armature"]

That’s all we need to identify actors and props in a Blender Scene.

In Blender, an Action is a sequence of key frames representing a character gesture (walking, jumping, slashing, falling, etc…). Actions are used as building blocks in Blender’s non linear animation (NLA) editor. We can use actions to create ‘animation catalogues’. An export script using actions might be used to batch export all animations for one or several characters, so we can update our game assets whenever we need, which simplifies and enhances flow.

Interactive Scripting Session

For this session, I have created a little robot – ‘funbot’ and an armature for it.
I then create two actions and detach them from the funbot. To take advantage of actions, we need to make each action current, i.e. for every action we attach the action to the armature and export all frames or key frames (either the armature frames/keyframes or the deformed mesh) before moving to the next action. Time for scripting:

#retrieve the action dictionary
actions=Blender.Armature.NLA.GetActions()

#get an action named 'nod' (as defined by your animator)
action=actions.get("nod")

#the following prints '[Action "nod"]'
armature=Object.Get("FunBotArmature")

#this makes the action current for the armature,
#so we can playback the action and record it.
action.setActive(armature)

#even if you call this, the window won't update, but the underlying
#model does, which is what we need for export.
scene=Blender.Scene.GetCurrent()
scene.update(1)

The above script does nearly everything we need related to actions – giving access to all defined actions within a blender file, it retrieves an action by name, applies it to the correct armature and updates the scene; at this point we’re nearly ready to iterate action frames and export the model and/or armature to a file (see my interactive session on exporting meshes deformed using an armature)

Just one more thing we need is knowing the number of frames in the animation. We can actually get better than just the number of frames – instead, we can get the list of keyframes, in ascending order:

#get the list of keyframes
keys=action.getFrameNumbers()
#print all keyframe indices, like ' [1,11,24,36,] '
list(keys)
#print the length of the animation
keys[len(keys)-1]

Using this, we can choose to either export only keyframes (use less memory), or all frames in the animation (OK for really simple animations and models).

Before I forget… for some reason the Blender APIDoc doesn’t just turn up whenever I google it. Here it is.

Just a while back I published a weeny export script and matching C/Objective C code that can be used to export mesh data from blender to OpenGL vertex arrays.

To export animated characters, we need to do either of two things:

1. Export Armature key frames or frames, along with their attachment to target objects; then apply the deformation either in real time, or maybe just before we need to animate the model. The upside is that this is memory savvy. The downside is that if your game engine can’t handle your exported armatures (I don’t know how likely to happen this might be) or you don’t use a game engine, you’ll have to work out deformations yourself, starting from a fairly complex high level model.
2. Export ready mesh key-frames or frames, with the armature effect already applied. The downside is that this requires a lot more memory.

My hunch is that how much ‘a lot more’ matters really depends how large your models are and what kind of platform you’re running on. I plan running on the iPhone/iTouch with isometric views. This means that my 3D sprites will be small – hence require less polygons. For some animations, a little compression (e.g. retaining unchanged coordinates from a previous frame) can be considered if needed, never mind sharing geometry across models.

In this article I show how to force modifiers to be applied before exporting mesh data – one way to attach an armature in blender is via modifiers. This is a good opportunity to try interactive scripting with Blender, making learning scripting easy and fun :)

Effecting the modifier stack also means that you can export complex operations applied to your object, not just armature modifiers.

Give back to Caesar what belongs to  Chicken – I borrowed this technique from the Blender to Panda3D export script – Chicken exports to Panda3D’s *.egg format,

***Believe it or not, *.egg came first, then Chicken somehow assisted the birth of this tutorial.

An Interactive Scripting Session

First I make a triangle pointing up in the z x plane, ensuring x==0 for the middle vertex. I add an armature – just one bone – aligned on the z axis and pose it to drag the top vertex to the right, about 1 unit. Finally I add the armature as modifier. I think this is important, afaik this wouldn’t work if the armature parented
the mesh. Then I type the following in the scripting console:

scene=Blender.Scene.getCurrent()
obj =scene.objects[1]
mesh=obj.getData(mesh=1)

# next line prints coord without deformation
mesh.verts[2].co.x

# this is where the magic happens
# getFromObject implicitly applies all modifiers.
tmesh.getFromObject(obj,0,1)

#next line prints coord with deformation
tmesh.verts[2].co.x

OK, this shows that we can export the deformed mesh. Now we need to get each
frame. So I insert a keyframe for the rotation of the bone (pose mode),
go 10 frames further and pose with the tip of the bone pointing right.

First, let’s repeat the first experiment,
browsing to frame 11 (left/right arrow keys)

tmesh.getFromObject(obj,0,1)
tmesh.verts[2].co.x

This shows that the script is, by default,
querying the current frame.
I found a command to change the frame:

context = scene.getRenderingContext()
# set the current frame
context.currentFrame(3)
scene.update(1)
tmesh.getFromObject(obj,0,1)
tmesh.verts[2].co.x

If you repeat this operation using the frame value, you will see that the vertex coordinate moves at every frame.

Next time I’ll look into exporting several actions for a given character.

This article may be useful to both wannabe Blender animators and game developers wishing to export animations from Blender (better know what we’re trying to export). To follow, it would be nice if you know a little (a fair bit?) about how blender works and how to pose armatures. This is explained quite well in the Blender Noob to Pro wikibook.

I had to work out this stuff myself, not because nobody knows about it but because apparently it’s hard to explain (or according to some, not really worth it, although frankly, I doubt…).

So this could be interesting to other intermediate level Blender users that know enough about bones animation in blender that they’re puzzled, baffled and about to give up :)

I expect this article may be inaccurate in some places. But overall I tried to explain something that seems fairly confusing to me, and tried to make sure that if you’re confused as well, reading and trying things out patiently will get you out of the ditch.

And finally, before we start – although the Blender interface is somehow obscure when it comes to bones and other things, I think it’s worth learning, because it’s fast and productive, which is why I love Blender.

In a nutshell

• Blender actions are sequences of poses typically associated with an armature. A walk cycle can be an action, a kick or a punch can be an action. Bowing can be an action.
• Actions are reusable. You can use the same action several times in your animation.
• An armature is a bunch of bones. Bones are like magnets used to move the geometry that makes up a model.
• A pose is a way to arrange the bones that make up an armature – a pose is a kind of ‘key frame’.
• NLA (non linear animation) is a process that consists in blending actions together. For example you can combine a waving action with a walking action. That’s obviously easier if we key frame leg bones and arm bones separately (armatures, however, are not limited to human shape).
• Blender has an integrated NLA editor. this is a bit like Final Cut Pro, but for continuous animation, e.g a character doing varied things like walking, kicking, jumping…
• A strip, is just a name for an action added to the NLA editor. A strip is attached to an armature and an action, and has a starting point in time. So the strip ‘makes the armature move’, and along with it a 3D model also attached to the armature. So several strips can refer the same action and several strips can be used to animate a character over time by picking previously created actions.

Outline for Character animation using bones.

As far as I have understood and tested, bone animation in blender works in two steps – creating actions, and using actions in your animation. Bone animation is somehow confusing, because the system does not let you create actions ‘on a separate timeline’. Actions can be stored on a separate timeline, but all the editing done happens on the main timeline. Another way to say this is that you can’t edit a library item as such. Blender definitely has a kind of library for assets, but we rarely get to see it, if ever.

If you hate theory, you might want to skip the next sections (not recommended though) and just ‘work it out’ using the test setup (see below)

Creating an action the first time(!).

1. You create an armature. An armature is ‘just bones sticking together’. It is not rendered on the screen.
2. You attach a model to this armature. The model becomes a child of the armature.
3. You start creating poses for the first action that you wish to define. When you create the first pose, two important, easy to miss things happen:
   1. An action is created. An action is a sequence of poses.
   2. The created action is attached to the armature.
4. You name the action that you have created.
5. You detach the action from the armature. You typically do this because you want to create a ‘library’ of actions that you can reuse throughout your animation (or export to a game if it’s what you’re after. At this point, as far as I know, there is not a single window in the blender interface that can tell you that this action exists.

Using an action

1. You add a strip to your armature. Adding a strip is a way to tell blender that we want the armature (and beyond, the model(s) attached to it) to perform an action at a given time. Maybe unfortunately, whenever you create a strip this causes the underlying action to be re-attached to the armature.

Creating an action the second time.

The second time you want to create an action for the same armature, assuming you are already using a strip referring an action you previously created, you may find that you can create key frames (poses) but when browsing the animation your key frames are ignored.

In this case, what works:

1. Create the action explicitly.
2. Generate a strip for this action
3. Create poses for this action
4. When you are done, you can both delete the strip and detach the action.

As far as I could work out, what happens is:

• When you have no strip defined, you can create as many actions as you want and everything renders to the main time line.
• As soon as you have defined at least one strip, actions are never rendered unless they are attached to strips.

Test Setup

By default, blender only shows three ‘editors’ (each in a separate frame). To see what’s going on, you need to create several more frames and toggle them to varied editors. Each frame has a button in the bottom left corner (or sometimes top left) that lets you choose a different editor. To work things out, you need 5 editors open, which is OK on say, a small widescreen monitor:

• Outliner – this shows you the structure of your scene as a tree.
• 3D view (showing on startup by default)
• The NLA editor – this is the Final Cut Pro – like thingy that lets you do the overall layout of your animation.
• The buttons window (showing by default)
• The action view – this lets you create new actions and select an action to edit it. A tricky bit is that sometimes it lets you try to edit something that won’t show on the screen – when you are using strips, you can only edit an action that’s currently attached to a strip.

Then you can try things like:

• Creating an armature. press [space] > add > armature in the 3D view
• Posing an armature. Look at the bottom of the 3D view and click the button that says [object mode]. You can change that to pose mode. You can also click the smiley icon in the outliner, next to the name of your armature.
• Inserting key frames while posing using the [i] key and [arrow-left], [arrow-right] to browse the timeline (move back and forth in time).
• Observing that when you insert the first key frame while posing, a new action is created, and the keyframes show in the action editor as well as in the NLA editor. The action itself also appears as a child of the armature in the outliner. Also, a default name for this action appears in the action editor and you can edit the name. At this point, even though no strip is defined in the NLA, your action can play back on the main timeline.
• Observing that pressing the [x] key in the action editor hides the current action (it doesn’t delete it, it just ‘detaches it’ from your scene, keeping it somewhere in memory).
• Observing that, in the NLA editor, you can choose strip > add action strip, and that will let you select the action that you previously detached to combine it with the new strip. Also the action will become current in the action editor. You can detach the action again (press [x] in the action editor) and the strip will still cause the action to playback.
• Observing that, if you already have a strip in the NLA editor, just detaching the current action, if any, and trying to set new key-frames for posing will be ineffective.
• Observing that actions can be created from the action editor. If you have an armature selected and no current action there’s an ‘up arrow down arrow’ button that gives this option once clicked. It also lets you make any existing action (including actions incompatible with the current armature) current for your current armature at any time – sometimes allowing you to make an action current and apparently editable, but without any effect on your animation (not until you attach to the armature a strip using that action.

OK, next time, I’ll be back on my turf, and look into ways that can be used to export animations from Blender and getting them into a game :)