Springrts Lua Unit Script (LUS) Export addon for Blender
This is a simple Blender addon that allows one to export animations created in Blender (provided they obey a long list of caveats and requirements) as SpringRTS Lua Unit Scripts in a fairly modular way.
1) Paste the io_anim_lus folder into your blender's scripts/addons directory
2) Enable the addon in blender
3) ???
4) PROFIT
1) Assemble a model suitable for import by Spring's Assimp. This means, in particular:
-
Each animatable piece of the model is a separate object
-
You will have to apply all scale and rotation transformations before exporting the model and starting your animation work. Whatever model you use ingame has to perfectly match to what you will be animating on.
-
Preferred export format for Spring import is .dae - others might work, but there's little guarantee.
2) Obsessively change each object's Rotation Mode in the hidden right pannel (or in object transform properties) to "Euler ZXY".
I haven't found any way to do this quickly for all objects in scene, so good luck doing this by hand.
If you skip this step, nobody will help you. Not even heaven, not even Allah.
3) Create your animation. Mind the limitations.
4) Hit the export button! There are several options available when doing so:
-
Anim name. This specifies whatever name your want for your animation in the keyframe table that will be generated by script.
-
Write pieces. This will cause the exporter to write a statement initializing the pieces the model has so they can be animated. Required for first export on this model only, then you'll probably want to disable this.
-
Write Animate() function. This will cause the generated script to include the function used to loop through the saved keyframes and actually play an animation. Hilariously, the function itself is called not Animate, but PlayAnimation(). Maybe i should fix this.
Like the former, only useful once -
Write Create() function. This will cause the exporter to write a stub of a Create call-in which will be executed on model creation. You will probably want to extend the stub later on.
This is required to initialize piece offsets so that translation animations can work properly.
Only needed once.
5) Plug and play the exported stuff into your greater script's logic. Sadly, exporter won't do all the work for you - it only allows you to separate artwork and programming.
-
You absolutely have to change every object in your scene into Euler ZXY rotation mode, or untold horrors will plague you.
-
Your object names have to be valid Lua variable names, because object names are not validated in any way. Generally, avoid anything containting spaces and punctuation marks.
-
You cannot have multiple animations per blender file. Blender's Actions system doesn't really accomodate for a horror soup of a dozen objects trying to dance in concert.
-
You can only use Linear interpolation between your keyframes, because there's no way to implement Bezier in Spring LUS... at least yet.
Workaround: Use a lot of keyframes if you want smooth motion. -
You have to apply scaling transforms before export, and you cannot use scaling in your animations. In fact, you're limited to using LocRot.
-
Local rotation transforms of each object in model's "bind pose" must be strictly 0,0,0.
-
You cannot use inverse kinematics, because you cannot use bones (at least, not without amount of effort making this approach self-defeating. This might be addressed in the future, but don't hold your breath).
-
The first keyframe will only be interpreted as a reference to calculate turn/move speeds for affected pieces. Not important if your model starts in same pose as your animation, but transitions between already adjusted poses to new animations will be "kinda smooth". This is a bug. You can probably get around by adding two keyframes at start (at frame 0, initial , and frame 1, snap!)
-
Any glaring horror i forgot to add to this readme. There are probably quite a few of those. Watch your step and report on sight.