Expose scene elements, like children transformations as TCastleScene children

Table of Contents

1. Introduction
2. Examples
3. (TODO) Bi-directional synchronization
4. Why make features this way

1. Introduction

Warning

Part of this feature is still in development. This documentation is written in advance, to show the planned feature. Pay attention to "TODO" notes below. Want to speed it up? Talk to us and support us.

When you design a 3D model in an external application, like Blender, you sometimes need to access some elements of this model. We think here about access both from code and from editor — to manipulate, to observe or just to add more children (that will be animated along with the observed transformation).

To do this, use TCastleSceneCore.ExposeTransforms. It can be set comfortably from CGE editor using a dialog box that shows the available transformations in the loaded model.

2. Examples

There’s a number of practical use-cases for this feature:

You can expose a transformation (translation, rotation, scale) of a child of the model. This means that we expose some transformation of your model, loaded in TCastleScene, from e.g. glTF or X3D. By exposing, we create a child TCastleTransform under a parent TCastleScene that corresponds to given transformation (maybe joint, bone) of your model. In turn this allows to:
- Attach children to this transformation. For example you can attach a weapon to a hand of a character model. If the hand is animated, it will move the weapon together with it. See examples/animations/expose_transformations_to_animate_children for a demo.
- You can observe the animation of some joint from code, e.g. to react to it ("when the hand moves high, play a sound").
- (TODO) You can manipulate the transformation from code, e.g. to move the hand of a character model to a specific position. This allows to do animations, including skinned mesh animations, using code, and potentially even do "inverse kinematics" in a manual way. The animated mesh stays part of the parent TCastleScene, but you can manipulate the joints from code.
- (TODO) You can attach physics rigid bodies to the exposed transformations, and thus make parts of the model affected by physics.
(TODO) You can expose a light from the model. This allows to design the light sources in Blender, and later tweak them in the application.

It is more powerful and more obvious than alternative TCastleScene.CastGlobalLights (which also allows scene lights to shine on other objects, but in that case lights stay hidden inside the scene, they are only accessible as X3D nodes).
(TODO) You can expose a camera from the model. This allows to design the camera in Blender, and later use it in the application, e.g. as a starting point for player movement.

3. (TODO) Bi-directional synchronization

The exposed elements synchronize in a bi-directional way.

Their initial state (transformation, light information like color, intensity etc.) is dictated by the state in the model. Moreover, if the model animates given state (e.g. transformation is animated by some animation designed in Blender and started using TCastleSceneCore.PlayAnimation), it will affect the exposed transformation.
(TODO) But the synchronization also goes in the other direction, from exposed TCastleTransform children → back to the original model. If you change a given state from code (and it is not animated in the model), it will affect the model in the scene. This allows to manipulate the transformation from code, e.g. to perform animations (including skinned mesh) using code. This also allows to attach physics rigid bodies to the exposed transformations, and thus make parts of the model affected by physics.

4. Why make features this way

Exposing model features this way is powerful. Aside from all the features mentioned above, the components (like lights, TCastleCamera, TCastleTransform) stay also independent components, so you can design cameras, lights, transformations group also in CGE editor (without using external tools like Blender). So you get the most flexibility.

To improve this documentation just edit this page and create a pull request to cge-www repository.