![]() |
![]() |
![]() |
Blender is a magnificent free open-source 3D modelling software.
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:
Blender documentation of the glTF exporter is useful. The exporter is developed by Khronos on GitHub.
![]() |
![]() |
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.
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.
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:
scripts/addons/
directory.
For Blender 2.82a: Apply this fix if you're going to use glTF combined with castle-anim-frames (see below).
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:
Thanks to the simplicity of the .castle-anim-frames
format,
this format exports every kind of Blender animation to our engine:
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:
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.
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).
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:
castle_engine_x3d.zip
file you downloaded, and confirm by clicking "Install from file..." near the top-right corner.
"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.
Copyright Michalis Kamburelis and other Castle Game Engine developers. We use cookies
for analytics.
Like every other frickin' website on the Internet.
See our privacy policy.
Thank you to Paweł Wojciechowicz from Cat-astrophe Games for various graphics.
This documentation is also open-source and you can even redistribute it on open-source terms.