Scripting in Simulations

You can control various simulation specific attributes by using scripts. This helps to control the behavior of objects acting under influence of force fields.

There are several ways to use scripting in simulations. Firstly, you can attach a script directly to an object. You can also create a special constraint scripting object and add it to a hierarchy level in order to control all objects in the same hierarchy level. A constraint object allows you to link objects anywhere in the object hierarchy with each other and control them using scripts.

Attaching a script to an object

You can attach scripts to objects through the property window's Script tab. For example, to control the color of an object using its translation attribute:

1. Create a sphere, set the Command Language in the property window's Script tab to JavaScript and enter the following script:

    translate = Self.GetTotalTranslate();
    Self.SetColor(translate);

The script reads the translation attribute of the object and assigns it to the color attribute.

2. Key frame the sphere by moving it in the 'x' direction. Play the animation to see how the color changes when the sphere moves.

Constraining positions

Let's assume you want to keep a sphere falling in a gravity field above the ground plane. Attaching the following script to the sphere does this:

1. Select the sphere and set the Command Language in the property window's Script tab to JavaScript. Enter the following script:

   center = Self.GetCenter();
   if(center.y < 0) {
        center.y = 0;
        self.SetCenter(center);
   }

Airplane

The following tutorial example shows how to use a constraint object in a fluid dynamics simulation. We build a little airplane which hopefully manages to take off the ground. This is not an easy task, because designing airplanes is demanding work!

Tutorial level: Advanced

Example project: 'Tutorprojects/Simulation/Plane'

1. Model a simple miniature airplane (about 10 cm long) as shown in the image. It consists of four components: a body, two wings and a tail. Our sample plane consists of two elliptic spheres (body and tail) and two SDS cubes, which have been edited to a wing-like shape.

A simple airplane

2. Select the plane level object. Open the property window, go to the Sim tab and define Gravity = Affected, Fluid Dynamics = Affected.

We will set up a simulation where things happen slower than in a real world. This makes it easier to track the plane when it flies.

3. Select the body and two wings of the plane. Go to the Phys tab of the property window and set their mass to '0.01' (10 grams).

Select the tail and set its mass to '0.002'. The large but light tail will stabilize the plane.

4. Select the body of the plane. Make sure that the Handles/Rotate is set in the view window's popup. Now look at the three move handle lines; the red is object's x-axis, green denotes the y-axis and the blue line is the z-axis. Enter three values to the Fluid Friction field of the Phys tab. The first value is friction in the x-axis direction. If the red line points along the body of the plane, x-friction is very small, 0.01, because the object is most aerodynamic in this direction. If the red axis is not the most aerodynamic axis (but the one between wings or the vertical axis), x friction is slightly larger, 0.03. The other two friction factors are defined the same way. In our sample plane the red axis is the length axis, so the suitable Fluid Friction values are '0.01 0.03 0.03'.

5.Select the wings and define the Fluid Friction the same way as you did for the body. A wing has small fluid friction in two directions, and high friction against the flat wing plane. The orientation of the wings may be different from the body, so check again the red-green-blue orientation of the wing's rotate handle when defining the three fluid friction factors. In the sample plane, the green axis is the vertical axis. Hence the suitable friction factors are '0.01 0.1 0.01'.

6. Select the tail and define Fluid Friction for it ('0.01 0.01 0.1' for the sample plane).

7. Next we define symmetry of airflow around the wings. Asymmetric airflow will create a lifting force. Fluid Symmetry field controls the desired property. A factor '0 0 0' means that air flows around the object in a perfectly symmetric way. In our sample plane, the green object axis is the vertical axis i.e. the direction in which the wings lift the plane. Therefore, we define a Fluid Symmetry value '0 0.7 0' for both wings.

8. Select the complete plane object. Go to the Simulation tab of the toolbar, activate the Velocity tool and draw a short horizontal velocity line for the plane.

9. Activate the Distant Gravity tool and draw a vertical line pointing downwards. This adds gravity to our simulation. The plane has to fight against the gravity to take off the ground. Since our animation happens slowly and in small scale, go to the Spec tab and decrease the Strength field to '0.02'. Now objects fall slowly, and the plane does not have to travel 500 km/h to take off.

10. Activate the Fan tool and draw a fan object in the view window. The fan adds fluid friction to the simulation. To make the simulation interesting, let's use turbulent wind: go to the Spec tab of the property window and set Turbulence of the fan to the full level of 1.0. The direction of wind now changes randomly in space. Go to the Phys tab and decrease Fluid Velocity to 0.2 m/s. Slow enough turbulent wind gives our plane a change to stay in the air for a while. Increase the Density value to 10. Thick air helps to stabilize the plane.

At this point, the plane already tries to take off the ground thanks to its initial velocity. However, it will fall down quickly, because air resists its motion and it has no engine pushing it forward. We will use scripting to add a suitable force, which pushes the plane forward.

11. Activate the Distant Gravity tool again and add another gravity field to the scene. Rename the force object as 'push'.

12. Go to the Spec tab of he property window and adjust the strength of the new gravity object to 0.2 (0.2 N means that the engine is very weak, but the plane weighs only some tens of grams and the actual gravity is also small).

Now the problem is that the new force has a fixed direction. It should always push to the direction of the plane.

13. The push object selected, go to the Script tab of the property window. Set Command Language to JavaScript. Type the following script (remember to hit Enter after the last line):

    body = Self.FINDBYNAME("body");
    center = body.GetCenter();
    to = body.GetA();
    to.fadd(center);

    Self.SetPosition(center);
    Self.SetDirection(to);

[Note] Note
The JavaScript language and the attribute names are case sensitive.

The script above reads the position of the elliptic sphere and writes it to the end point of the push force direction line. Then it sums the 'A' axis of the sphere to the center and assigns to sum to the start point of the force. Note that the orientation of the plane body may be different in your scene: if a green translation handle points the length axis of plane body, then use 'B' instead of 'A' (and 'C' if blue axis shows the right direction). The force orientation may also become opposite to the plane direction, but this can be fixed e.g. by rotating the 'body' ellipsoid 180 degrees (or by changing 'F+' to 'F-' in the script above).

You can also use other attributes of the plane for defining the force direction. The important idea is that the script copies a suitable direction from the plane to the 'push' force. You can see the list of available attributes e.g. by using the 'Input' tab of the choreography window (see the animation documentation for further details).

The scene is now ready. Set the frame count to 200-300 frames and play the animation. With some luck, the plane manages to take off and make a beautiful flight. If not, you can decrease gravity and turbidity, increase the size of the tail, balance the plane better, etc. Since the plane has no pilot, it is doomed to crash sooner or later.

The plane simulation scene finished