Exporting from Blender

1. Export to X3D

Blender is a magnificent free open-source 3D modelling software. Latest Blender versions include a working X3D exporter, so you can export your content from Blender out-of-the-box and open it with our engine. We advice testing the X3D models by opening them with view3dscene.

We have our own X3D exporter version, which is based on the Blender X3D exporter and adds some fixes and also support for CommonSurfaceShader exporting.

A short installation instruction: just install it like any other Blender add-on ("Install from file..." on "Add-ons" tab).

A very detailed installation instruction:

1. In Blender, click the "File -> User Preferences" menu item.
2. Go to the "Add-ons" tab.
3. Click the button "Install from file..." at the bottom of the window that appears.
4. Select the castle_engine_x3d.zip file you downloaded, and confirm by clicking "Install from file..." near the top-right corner.
5. Find the script box e.g. by searching for "castle" in the search box. You should see a script named "Web3D X3D/VRML2 format (Castle Game Engine Importer/Exporter)". Activate this script by ticking the checkbox right near it's name.
6. Optionally, you can click now "Save User Settings" at the bottom to have this script automatically enabled next time you open Blender.
7. Make sure it works: look into the "File -> Export" submenu, it should have now a new option "X3D Extensible 3D (.x3d) (Castle Game Engine Exporter)"

In time, we want to submit all our modifications to the official Blender code, and have them available out-of-the-box in Blender. (If you want to help with that, please let us know, or just do it — the only issue is that someone needs to find a time to write a proper issue request to Blender devs:).

2. Export to Castle Animation Frames (castle-anim-frames)

The Blender X3D exporter cannot handle animations for now. To solve this, use the exporter below to export animations to a Castle Animation Frames format. The .castle-anim-frames files can be read by our engine and will play animations.

Install it like every other Blender addon:

1. Use the comfortable File -> User Preferences (opens new window) -> Addons (tab) -> Install Addon... (button at the bottom). Or just copy the file directly to the scripts/addons/ directory.
2. Enable it, by clicking the checkbox at "Import-Export: Export Castle Animation Frames" in the Addons window.

2.1. Actions and Frames

Actions are Blender containers for animations. Each Blender object may have many actions, like walk, run, die... A new action is automatically created on an object (if needed) when you insert a keyframe.

In Blender, it matters to which object you attach an action. Action describes the complete animation of a given Blender object. If you try to reuse the same action on two different objects, you will find that they animate (move, rotate...) the same way. If you want every object to animate in a different way, you will usually use an action only on a single object. I explain this, to make it clear that Blender actions do not span multiple objects, which is a little different than what we need (we want to export a series of animations, and each animation should just apply to the whole scene).

When exporting the animation, you can select an object to export all the actions of this object. If your scene includes an armature with some actions, we automatically select it as the object from which to take actions (you can deselect it, if desired). The range of exported frames is determined by the minimum and maximum keyframe set in this action (that's how Blender calculates action.frame_range in Python).

When you don't select any such object then we export the whole animation (from Start to End frames that you set on the Timeline). The resulting animation will be called just "animation" in this case (this is useful if you run animations from code, using the PlayAnimation method). This is perfectly reasonable in many situations:

• if you don't have actions in your scene (if your animation is ruled only by physics),
• or if you just want to export the current actions of all the objects,
• or if you configured the animation using Blender's NLA editor.

2.2. Exporting Various Animations Types to castle-anim-frames

Thanks to the simplicity of the .castle-anim-frames format, this format exports every kind of Blender animation to our engine:

• You can transform whole objects,
• You can animate using an armature (skeleton) attached to a skinned mesh or disjoint objects,
• You can deform the mesh in any way (shape keys, hooks),
• You can use fluid simulation,
• You can use physics (rigid body, soft body, cloth; make sure to play the complete animation in Blender right before exporting, to make it cached),
• You can animate material properties (e.g. color or transparency),
• You can even animate particles (select the "Make Duplicates Real (Export Particles)" checkbox)!

The castle-anim-frames animations render smoothly when the models are "structurally equal", which means that you should only animate things that can be interpolated. You should not change a topology (e.g. create, destroy faces or whole objects) from one frame to another, at least you should not change it too often. In particular:

• You may want to avoid using Blender "fluid simulation", as it always instantiates a different mesh topology every frame.
• Avoid having "Triangulate" or "Decimate" modifiers on a stack after an animating modifier (like an "Armature"), as they will change the mesh topology differently every frame. Using these modifiers earlier on the stack is better.
• If you export particles, make sure that all the particles exist in every animation frame. It's easiest to achieve this by selecting to Render both the "Unborn" and "Dead" particles.

Ignoring these advices will make the animation "jump" at certain frames, since the engine will not be able to interpolate between the frames you provided. Sometimes this is OK (e.g. when you really change one object to something completely different), but sometimes this is a bad artifact. Use the view3dscene with --debug-log command-line option, and watch for warnings about the model not being "structurally equal", if you want to eliminate such issues.

The castle-anim-frames exporter uses the X3D exporter (the original one, provided with Blender, or our custom one if installed) to export the static data. So if something doesn't look like you want after exporting, consult the advices above about using the X3D exporter. You can always export, as a test, a single frame of your animation to X3D, to check does it look OK.

TODO: Right now the interpolation is not done using the proper X3D interpolators at runtime, like PositionInterpolator. Instead we interpolate (create intermediate frames) at the load time, then put the resulting frames inside a Switch node, animated using the IntegerSequencer. The nodes inside all Switch nodes are shared smartly, but still the memory usage is much higher than it could be.

For the sake of the collision detection, each animation is treated as it's bounding box. Calculating detailed collision trees for every animation frame would be too time-consuming. TODO: We can improve it one day to collide as a different bounding box, corresponding to the current animation frame, not to the whole animation.

3. Rendering Skyboxes and Static Cube Environment Maps

You can render a set of six images that can be used as a skybox (Background in X3D, see documentation of the Environmental effects component) or a cube map texture (ComposedCubeMapTexture in X3D, see documentation of the Cube map environmental texturing component). We have a small Python script for Blender that renders the images to the appropriate names following the X3D conventions (front, back, top,....), and a simple X3D test scenes that allow to test that the resulting images indeed work as a skybox or a cubemap texture (e.g. you can open them in view3dscene).