Basic toolchain for Blender - Cal3d - Crystal Space

February 24th, 2017 by Diana Coman

Only 2 days ago I was cobbling together a basic Cal3d+Crystal Space viewer of sorts for people to be able to test their Cal3d exported work to see if it's of any use for Eulora. Well, 2 days around here turns out to be a very long time indeed, as meanwhile it seems that we got not one but even two Blender to cal3d exporters actually working as well as at least one new animated sprite that could well wiggle its way on Euloran soil. To help along any artists who think they could contribute but feel that they don't have any sort of tools to support them, here's a basic toolchain in its first iteration. You'll need (DO mind the versions and don't update/innovate on this topic):

  1. Blender 2.66 - you are best off downloading sources and compiling them on your own system. If you are not enough of an artist to do that, at least get your binaries from the official Blender site and CHECK their checksum.
  2. Exporter from Blender 2.66 to cal3d:
    1. I tested Julien Valentin's exporter and it worked fine on a XUbuntu 12.04 64bits. So I'm hosting here the part you really need, check the sources page.
    2. To install it: simply drop the folder from that archive into the addons folder of your Blender 2.66 installation (you should find it if you go to your Blender folder and then further into 2.66/scripts/addons). Start Blender and go to User Preferences/Addons: either search for it or look in the Import/Export category. Activate the addon, save the preferences, enjoy. If all went fine, you'll find it as an option from File->Export->Cal3d Model (.cfg)
    3. To use it: load your .blend file in Blender; go to Object mode; select both main Armature AND the mesh (you can do this in a view of the object if you use "a" for "select all" OR you can do it from the Outliner). Go to File->Export->Cal3d Model (.cfg) and choose where you want it to spit out everything. The exporter itself says that there should be a second step as it allows you to prune bones that are not needed - in my experience it rushes through it all in one go (admittedly my test model had only 4 bones so nothing to prune for sure), but here it is mentioned, just in case you experience this second step. Go and admire your multiple xml files with funny extensions (.xaf, .xrf, .xmf, .xsf)
    4. Alternatively, give a go to a different (if similar) exporter that was tested and found working on Debian 8.
  3. Crystal Space and Cal3d: download and install according to instructions on Eulorum. NB: do NOT use any other versions of Cal3d and/or Crystal Space or your work will probably be useless for Eulora if you do.
  4. Bash script to help you bridge the gap between what the exporter spits out and what cal3d+cs actually need. Note that it can help you best when it has in the same place a header.cal3d and a footer.cal3d files that it uses to assemble a working .cal3d file for your use with the cally3d viewer (see 5. below).
    1. To use it simply download it, make it executable and run it: ./ inputFolder [outputFolder] [pathToCal3D] . By default, the output folder is same as input folder and the path to cal3D is taken from environment variable CAL3DHOME (so just set that one if you don't want to use that last argument). Note that the path to cal3d IS NEEDED in order to actually run the converter between xml and binary cal3d formats. While you CAN run a similar converter that comes with your distribution, it will most likely NOT match the cal3d version that the exporter uses and it will miserably die on you.
    2. The script goes through all the .xsf, .xrf, .xmf and .xaf files in the inputFolder, calls the cal3d converter on them and stores the results in outputFolder/modelfiles. It also creates a file outputFolder/test.cal3d that includes all the exported skeletons, meshes and animations. NB: while this IS a valid file in general, you might want to check it and/or adjust values in there to match your needs!
  5. Viewer cally3d_args based on Cal3d+Crystal Space so that you can check your work. For sha512sum and more detailed instructions see the sources page.
    1. To use this, you'll need to compile it. A simple "make all" will do, provided you have already cal3d and Crystal Space installed.
    2. Once compiled, run as ./cally3d [file.cal3d] [animationName] The default values here are "test.cal3d" and "strut" respectively. To use your previously exported model you can:
      1. run the script at 4 above with the folder of this viewer as outputFolder OR
      2. manually copy the output from 4 to this folder
      3. give as argument to cally3d the full path to your .cal3d file. NB: in this case you WILL likely have to update manually the .cal3d file as well so that cally3d can find the skeleton/animation files.

When you finally run cally3d, you should be looking at your model performing whatever animation you asked it to perform. Note that the bash script gives animations their name based on the name of the .xaf file, so you might really want to follow the convention and name your animations in Blender as modelname_animationname rather than myAnimation sort of thing. If your animation is for instance wormOfDoom_knotting, then you'll be able to ask cally3d to show you the "knotting" animation of your worm of doom. Otherwise you can of course ask for anything you wish and get a load of errors.

As previously mentioned, this is a very basic toolchain cobbled together more as a prototype / starting point rather than a definitive reference. The most glaring current limitation (by no means the only one) is the lack of material support - whatever your worm of doom was wearing as its skin will be quite bluntly ignored by the viewer (though not by the exporter).

Enjoy! And if you complain, do it with concrete and precise descriptions of what hurts, where and what you did when it started. Unless you want it to hurt even more, that is.