Exporting from Blender

Blender is a magnificent free open-source 3D modelling software.

1. Export to glTF 2

Using glTF 2.0 is the advised way to transfer models from Blender to Castle Game Engine.

Castle Game Engine supports the glTF 2.0 format, and Blender has an exporter to glTF 2.0. Just export using the File -> Export -> glTF 2.0 menu item and open the resulting file (in .glb or .gltf formats) using any engine tool (like view3dscene).

See here for the details about our glTF support. In short: we support most features, including physical materials and skinned animation.

Advised glTF export settings:

• You usually want to check "Geometry -> Apply Modifiers" in the export dialog.
• "Remember Export Settings" is also usually useful.
• For typical games (where you distribute the game data with your application) we recommend exporting to "glTF Separate (.gltf + .bin + textures)" variant. This allows to share textures between various models and keeps importing fast. You can edit the "Textures" directory in the export dialog, to make the glTF file just point to your existing texture directory.

Blender documentation of the glTF exporter is useful. The exporter is developed by Khronos on GitHub.

Note that you usually want to Stash animations to have them exported, as is briefly mentioned by exporter docs. That is:

1. go to "Animation" view (or turn any Blender window into "Dope Sheet")
2. select Armature (e.g. by left-clicking in 3D view)
3. change "Dope Sheet" mode to "Action Editor"
4. select each animation (aka "action" in Blender) you want (repeat this for all animations you want to export)
5. click "Stash"

1.1. Custom properties

Blender can export Custom properties from various objects to glTF, and our engine reads them. You can access them by MetadataString and similar properties on X3D nodes. See our demo-models, subdirectories blender/custom_properties/ and blender/custom_properties_2/. See examples/short_api_samples/metadata/metadata_use.lpr for an example of how to get/set metadata from Pascal.

• Custom properties on Blender materials are imported as metadata on X3D material nodes, like TPhysicalMaterialNode.

  For example access them like:

  MyString := MyMaterial.MetadataString['material_property_name']

• Custom properties on Blender cameras are imported as metadata on X3D viewpoint nodes, like TViewpointNode.

• Custom properties on Blender meshes are imported as metadata on the immediate parent Group of each X3D Shape node. Note that many X3D shapes may be part of one Blender mesh.

  For example, if you have a TShapeNode instance, you can look at parent group by TX3DNode.ParentFieldsNode property. To read metadata from the corresponding Blender mesh do this:

  if MyShape.ParentFieldsCount = 1 then
    MyString := MyShape.ParentFieldsNode[0].MetadataString['mesh_property_name']
  else
    WritelnWarning('Shape not created by glTF importer');

• Custom properties on Blender objects are imported as metadata on the immediate parent Transform of each X3D Group representing Blender mesh. Note that one Blender mesh may be part of multiple Blender objects.

Moreover, we recognize a special property CastleCollision at Blender mesh. It sets X3DShapeNode.collision field in X3D (TAbstractShapeNode.Collision in Pascal API). It accepts the following values:

• none — non-collidable mesh.

• box — mesh collides as a simple axis-aligned box (auto-calculated from bounding box of the shape, unless Shape.Bbox is explicitly specified).

• default — mesh collides as a precise set of triangles.

2. Export to X3D

Blender includes exporter for X3D out-of-the-box.

Unfortunately, it doesn't support animations. And since Blender 2.8 it is even more limited, it doesn't support any textures either.

There are also bugs. Be sure to use the latest Blender versions (2.82 or later), and consider appplying these fixes yourself: fix applying modifiers, fix backface culling export.

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

To export any kind of animation from Blender, use the exporter to our Castle Animation Frames format. The .castle-anim-frames files can be read by our engine and will play animations.

Internally they are a set of X3D or glTF files.

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.

For Blender 2.82a: Apply this fix if you're going to use glTF combined with castle-anim-frames (see below).

3.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.

3.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.

4. 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).

5. Obsolete: Export to X3D from Blender 2.7

Blender versions earlier than 2.80 included a working X3D exporter out-of-the-box. So you can export your content from Blender to X3D open it with our engine.

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)"