Page 1 of 2

Lugaru Animation Import / Export scripts for Blender

Posted: Sun Apr 18, 2010 7:16 am
by rudel_ic
I just finished reverse-engineering the Lugaru animation format and writing tools for altering them with Blender.

You can get the scripts in a ZIP archive right here: viewtopic.php?f=7&t=5620&p=232622#p232622
(Used to be -- not anymore though)

Edit: Also attached it to this post. Seems like my ISP just went belly-up or something. If you also need the skeleton stuff because my site is borked, post and I'll attach it.

Get Blender here:
(get Blender 2.49, the scripts don't work with the 2.5 alphas!)

Make sure you've got Python installed; hints on this: ... thon/Setup

You need the skeleton modding tools from my site as well, the animations are always based upon imported skeletons.

Documentation follows.

General notes

You can access the tools from the main menu, they're in the Import / Export submenus.
The orientation of stuff follows OpenGL standard, even inside Blender. So you might perceive things as being upside-down. To change that, press CTRL-NUM7 to adjust your viewpoint.
LMB means "Left Mouse Button"; RMB means "Right Mouse Button", MMB means "Middle Mouse Button".
Blender's shortkeys are focus-sensitive.
The 3D viewport doesn't immediately update upon import; just scroll with your mousewheel for zooming a step or two.
You can restrict a lot of 3D operations to axes and snap stuff to grids, there's a difference between local and global space operations etc. For more on that and a lot of nifty features that are beyond the scope of this post, please check out the documentation at and the material in the Blender help menu.

If you have any questions at all, post in this thread here, PM me, e-mail me or friend me on Facebook. Details are on the bottom of the site mentioned above. Just be patient waiting for responses, I'm not hovering over the internet 24/7.

What we'll look at

Importing an animation into Blender
Changing, adding, deleting keyframes of the animation
Working with the Weapon Orientation Mesh
Exporting an animation

Re: Lugaru Animation Import / Export scripts for Blender

Posted: Sun Apr 18, 2010 7:17 am
by rudel_ic
Importing an animation into Blender

You need a skeleton in your scene. The animation you import is applied to that skeleton. So the first thing to do is to import a Lugaru skeleton, "Data/Skeletons/Basic Figure" is a good choice.
After importing the skeleton, delete the ragdoll because it's not needed:
- RMB the ragdoll mesh to select it
- Press X to delete it
Then, select the skeleton mesh with RMB.

We are ready for animation import

Then import an animation, for example "Data/Animations/StaffGroundSmash".

After import

Note that animation import is destructive. That means that the mesh changes. Therefore, I recommend always operating on duplicates. You can duplicate a selected Object with SHIFT-D.

Also note that importing multiple animations onto the same mesh messes stuff up. Just always import onto a freshly imported skeleton (or a duplicate). I just keep a freshly imported skeleton on the side, then I duplicate it, move it to (0,0,0) and import onto that duplicate.

The small dot left of the skeleton there is the weapon orientation mesh - also animated. Some animations have one, some don't. It is a separate mesh.

This imported animation unfortunately is a RELATIVE Shape animation; that's not the type we want though. I found no way to change this via Python, so you'll have to do this yourself.
- Select the skeleton
- Deactivate "Relative" in the Editing Panel
- Select the weapon orientation mesh (if there is one)
- Deactivate "Relative" in the Editing Panel

This is how it's supposed to be

Now that we've set this straight, it's time to look how this thing animates inside of Blender.

First, let's set the number of frames to be played to 19. The animation isn't that long after all.

Note: The way it's imported currently, an animation keyframe is shown every 2 frames, starting with frame 1. This animation has 10 keyframes, for example.

Keyframe | Key Name | Displayed at frame
1.............| Base..........| 1
2.............| Key 1.........| 3
3.............| Key 2.........| 5
4.............| Key 3.........| 7
5.............| Key 4.........| 9
6.............| Key 5.........| 11
7.............| Key 6.........| 13
8.............| Key 7.........| 15
9.............| Key 8.........| 17
10...........| Key 9.........| 19

Set the animation end to 19

Now press Alt-A to have the mesh animated in realtime inside the 3D Window.

As it plays back, you can also rotate the viewport around the mesh. Just pan the viewport by holding SHIFT-MMB and moving the mouse until the mesh is in the center of the viewport. Press and hold MMB and move the mouse to rotate around the mesh. Press CTRL-NUM7 to revert the viewport rotations.

Re: Lugaru Animation Import / Export scripts for Blender

Posted: Sun Apr 18, 2010 7:17 am
by rudel_ic
Changing, adding, deleting keyframes of the animation

Changing a keyframe

To edit a keyframe, select it in the Shapes tab while you're in Object Mode.

We''re going to edit Key 6

Then, switch to Edit Mode by pressing TAB in the 3D viewport.

Ready to move skeleton vertices for Key 6

Generally speaking, animation keyframes are altered by rotating limbs in Edit Mode, then leaving Edit Mode with TAB.

To rotate stuff properly, you have to rotate around a pivot. By default, Blender rotates things around the center of everything that's selected. We need to change that. We want to rotate around the 3D cursor, since that's the easiest and fastest method.

In Edit Mode, set the Rotation/Scaling Pivot to "3D cursor".

We want it like this

Now, whenever we want to rotate something, say, the right arm around the right shoulder vertex, we do this:
- Select the vertex to rotate around with RMB
- Press SHIFT-S, choose "Cursor -> Selection" — the 3D Cursor jumps to the selected vertex
- Select all vertices that are to be rotated around that location
-- -- (Hint: B for Box Select, Shift-RMB for adding vertices to a selection)
- Press R, rotate by moving the mouse, LMB to confirm
-- -- (Hint: Press X, Y or Z to restrict to axes (once for global axis, twice for local axis))

Image Image
Cursor set.............................These are to be rotated

When you're done with the keyframe, just exit Edit Mode by pressing TAB. Choose another keyframe, repeat ad nauseum.

Adding a keyframe

Note: Don't forget to set the Animation Playback End to something other than the 19 from the example above — you want to see keyframes displayed after all if you have more than 10 and press ALT-A. Default is 250.

To add a keyframe, just press "Add Shape Key" in the Shapes tab. Edit the keyframe then as described above. It won't be displayed when you press ALT-A for reasons we'll discuss later on, but it exists, can be edited and will also be exported.

Note though that the sequence of keys matters. That means that the order in which the keys appear when you cycle through them with the arrows in the Shapes tab is the order in which they are exported.

When you press "Add Shape Key", the new keyframe is added at whichever existing Shape Key is supposed to be displayed at the current playback frame.

Obviously, this gets really convoluted with more and more keyframes. To keep things in order, you need to operate on the Shape Keys in the IPO Curve Editor.

Make sure you're in Object Mode. Make sure your mesh is selected. Change the Window Type to "IPO Curve Editor" (the button for choosing the Window Type is on the lower left of the viewport).

Change the IPO Type to "Shape" (the IPO Type is set in the selection box that says "Object" by default).

The IPO Editor showing Shape Keys

As you can see, on the right of the graph, all keyframes are listed by name. To change the order of them, LMB a name, then press G to grab the related line, then move the line to the right vertical position.

The lower a keyframe line is, the higher it ends up in the list on the right. I recommend making sure the list on the right is in an order that reflects an alphabetical sorting of the keyframe names. So if you have 67 keyframes, The string "Key 66" (the last keyframe's name) should be at the bottom of the list. Consequently, its line should be the highest in the graph.

There are quirks to this though. This editor has its share of issues.

For one, if you have, say, 10 keyframes and move key 5's line to the top, key 5 advances just by one position in the list.
To move it further, just press G and then immediately LMB to advance the list step by step. This is annoying, but necessary. The order is important.

Another issue is that some keys might have an IPO curve associated with them (particularly those that came from the import operation). When you LMB the name, this curve might be selected as well; you don't want to move it though. If that happens, press A. You really just want the horizontal to light up, not the ones that are diagonal.

Down the line, I'll write some tools to work around the issues because they're confusing, but for now, you'll have to deal with it.

Deleting a keyframe

To delete a keyframe, just press the X in the Shapes tab in the Editing Panel of the Buttons Window. This "just works", but there are some issues as well if you're an advanced user.

For one, speeds and sounds associated with the frame (discussed later) are still there. That results in a reordering of sorts.
For example, if you have 4 keyframes and delete keyframe 2, then keyframe 1 keeps its speed and sound, but keyframe 2 (previously was keyframe 3) gets ex-keyframe 2's speed and sound, and keyframe 3 (previously was keyframe 4) gets ex-keyframe 3's speed and sound.

You'll just have to live with this for now. Don't forget to correct this when you export.

Another problem is that the animation displayed in Blender basically is completely broken when you start to delete keyframes in the middle. This is of course to be expected, but may confuse somewhat.

Final thoughts on skeleton animation editing

I couldn't go into detail with a lot of aspects of the workflow. You'll have to familiarize yourself with Absolute Shape Keys in Blender and Speed IPO Curves if you want to get the most out of it. Check out the Blender Wiki.

You'll have to work around some weird issues as well. However, this is no surprise to anyone in the field since keyframe animation traditionally is something you have to invest a lot into to get reasonable results.

Sometimes it makes sense to export an animation to then import it again (onto a fresh skeleton, of course). For example, if you change the order of keyframes, the speed IPO curve doesn't make sense anymore, so you want a new one, and a new one is generated upon import.

It is important that if you have a Weapon Orientation Mesh, then it should have the same amount of keyframes as the related animation skeleton.

Generally speaking, it doesn't make much sense to make an animation from scratch. Always start with an existing animation to take one giant shortcut right at the start. Ideally, you start with the animation you want to replace since the setup just makes sense then (same weapon setup, reasonable speeds and sounds). The next best option is to start with an animation that has an amount of keyframes that's similar to the one you want.

Re: Lugaru Animation Import / Export scripts for Blender

Posted: Sun Apr 18, 2010 7:17 am
by rudel_ic
Working with the Weapon Orientation Mesh

WOM = Weapon Orientation Mesh

The WOM has exactly one dot. This dot is where the weapon points to, going from the hand that holds it.

The WOM is also animated; it's animated in exactly the same way as the animation skeleton. So the information regarding editing animation skeletons applies.

Ergo, all you have to do to change weapon orientations is:
- Select the WOM in Object Mode with RMB
- Choose a keyframe in the Shapes tab (the arrows)
- Switch to Edit Mode with TAB
- Select the vertex
- Press G to move it around, move the mouse, LMB to confirm
- TAB to exit Edit Mode, done

Make sure the number of WOM keyframes matches the number of skeleton animation keyframes.

Not every animation has WOM data. This is completely normal. Those animations are just not available while you have a weapon, or the weapon just doesn't move at all relative to where it is attached to. Whether or not you can add WOM data for the latter type I don't know yet, I haven't played around with it.

Re: Lugaru Animation Import / Export scripts for Blender

Posted: Sun Apr 18, 2010 7:17 am
by rudel_ic
Exporting the animation

The exporter frontend

To export an animation, select the skeleton animation object, then choose "File->Export->Lugaru animations..." from the main menu.
If you've selected multiple Objects, the thing takes the first, whatever it is. Make sure you just have the selected the skeleton animation. Don't select the weapon orientation mesh.

The frontend is self-explanatory, I will however describe each function from top to bottom.

Weapon-related GUI elements

Affects Weaponry: When true, reveals Weapon Prefix and Orientation Mesh

Weapon Prefix: Unsure what it does

Orientation Mesh: Choose the mesh that describes weapon orientation. Make sure the mesh is animated and that it has the same number of keyframes as the skeleton animation.

Export: Exports the selected Object. Navigate to the target folder, provide a filename, click "Export Animation". If there's errors, please tell me what errors they are so that I can help you.
Errors are shown on the console. On Mac OS X, you might have to explicitly start Blender from a terminal to make errors show up because there, the console doesn't start along with Blender if you just doubleclick the application.

Refresh: If you've changed your selection, you might want to refresh what's being displayed.

Frame, Sound, Frame Speed Matrix: Vertically, you have the frames. Horizontally, you have what sound to play when the frame is active in-game (0-9) and how fast the frame is played back.
Which sound is which number is unknown, it's certain though that they're dynamic. Footstep-on-grass is something else than Footstep-on-stone, yet both get the number 1 in the Run animation. I haven't bothered figuring them all out. Experiment with that.
How fast the frame plays back is something you'll have to experiment with as well. You have to start Lugaru and trigger your animation. 0.1 is really slow, 30.0 is really fast. Run has values around 10.0 for all frames. Just look at a few animations and get a feel for it.

If you have more than 15 keyframes, a pagination appears at the bottom of the matrix. This is a wrap-around pagination (if you're at page 1 and press the "<" button, you'll end up at the last page). It's 15 keyframes per page.

Re: Lugaru Animation Import / Export scripts for Blender

Posted: Sun Apr 18, 2010 9:38 am
by rudel_ic
The maximum number of keyframes for an animation is 99. This is a restriction that results from the event system behind the Frame-Sound-FrameSpeed-matrix. I don't know if that's enough keyframes for you, but it's certainly enough keyframes for the usual motion capture animation in a game. You won't be able to put hour-long love scenes into Lugaru (unless you loop stuff or adjust the speed, I guess).

Don't abuse the system and be a bit forgiving. Report bugs as you encounter them. Please send me .blend files of stuff that doesn't export or breaks in-game.

And ALWAYS back your shit up before doing anything.

Re: Lugaru Animation Import / Export scripts for Blender

Posted: Sun Apr 18, 2010 1:48 pm
by WingedWolf93
Woah, wait a second, so now we can make our own animations, too? Awesome!
Can't wait to see new mods! :D

P.S. Is there any chance to see some independent Map-Editing tools any time soon?

Re: Lugaru Animation Import / Export scripts for Blender

Posted: Sun Apr 18, 2010 2:37 pm
by rudel_ic
WingedWolf93 wrote:Woah, wait a second, so now we can make our own animations, too? Awesome!
Can't wait to see new mods! :D

P.S. Is there any chance to see some independent Map-Editing tools any time soon?
There is a chance, yes.

Re: Lugaru Animation Import / Export scripts for Blender

Posted: Sun Apr 18, 2010 3:19 pm
by Lotus Wolf
Awesome! thanks rudel. I'll check back once I've used them for a while.

Re: Lugaru Animation Import / Export scripts for Blender

Posted: Mon Apr 19, 2010 3:42 pm
by GreenFlame
Great, yay, wow!Please guys, make something new for Lugaru! Ah, i feel a lot of happiness inside, waiting for some interesting updates here =D
Good luck everyone =D

Re: Lugaru Animation Import / Export scripts for Blender

Posted: Tue Apr 20, 2010 12:49 am
by Blorx
I've been neglecting saying anything, because I wanted to be informative in what I said, but rudel, I'm impressed. This is downright awesome.

Re: Lugaru Animation Import / Export scripts for Blender

Posted: Wed Apr 21, 2010 1:31 pm
by Renegade_Turner
Wow, this looks pretty wow. I'm afraid I'm not intelligent enough to contribute any more.

Re: Lugaru Animation Import / Export scripts for Blender

Posted: Tue Jul 05, 2011 12:06 am
by cooldude
Is there a video tutorial for this?

and can you do it on blender 2.58?

Re: Lugaru Animation Import / Export scripts for Blender

Posted: Tue Jul 05, 2011 8:35 am
by rudel_ic
There is no video tutorial. This doesn't work in 2.58, only in 2.49.

I recommend you take some animation (like the running animation, for example) and play around with that. Follow the above tutorial step by step. I'm sure you'll get the hang of it once you've successfully exported an animation and brought it into the game. It's a lot to go through, but the individual steps are quite trivial.

I'll gladly answer specific questions. If you want to, you can e-mail me as well. My e-mail address is at the bottom of the site where you get the converter.

Re: Lugaru Animation Import / Export scripts for Blender

Posted: Tue Jul 05, 2011 7:33 pm
by cooldude
I made these, please tell me what you think