Basic concepts

Basic concepts

A simulation is composed of physical objects, grouped into worlds.

The language allows users to define worlds, composed of objects. Worlds can include other worlds at a given position.

Defining objects

A physical object has many properties to be set, the properties important for the motion are located at the beginning of the definition, whereas other properties (such as color or how collisions are handled) are regrouped in the styles section further down.

The forces applied and the styles of the object can be inherited from abstract parent objects. If no parent object is specified for an object or an abstract object, its parent will be set to BaseObject by default.

Object properties

Name	Description	Mandatory	Expected type	Example
Mass	Mass of the object	true	mass scalar	[50 kg]
Position	Initial position of the object in the current world	true	length vector	cartesian(x = 0, y = 0, z = 0)
Velocity	Initial velocity of the object	false	speed vector	spherical(r=3 mps, tetha=pi * 1 rad, phi = 0)
Rotation	Initial rotation of the object	false	rotation	euler angles rotation
Rotation speed	Initial angular velocity	false	angular speed vector	cartesian coordinates(x = [3 rad*s^-1], y = 0, z = [3 deg] / [1 h])

Object styles / properties

Name	Description	Possible values	Default value (BaseObject)
pause-on-collision	Whether the simulation is paused upon collision	true, false	false
emit-light	Whether the object emit light	true, false	false
collision-reaction	Reaction of the object when colliding with another object	merge, elastic reaction, ignore, dissapear	elastic reaction
texture	Texture applied during rendering	Color, Picture	color texture(fill=white, stroke=black)
shape	Shape of the object	box, sphere	sphere
box-size-[xyz]	Size of a side of a box (applied if shape = box	Length	Side of a cube with volume mass * 1 m³/kg
sphere-radius	Radius of a sphere (applied if shape = sphere)	Length	Radius of a sphere with volume mass * 1 m³/kg
trace	Trail following the object trajectory	Enabled, Disabled	Disabled

Defining forces

There is many possibilities to add a force to an object or an abstract object :

• static force : linear force with optional application point, computed once and applied constantly
• dynamic force : linear force with optional application point, computed at each iteration
• moment force : rotational force, expressed in N.m, computed at each iteration
• conditional force : wraps a force that is applied only if the condition is met
• abstract force : call a defined abstract force, providing arguments

For most forces you can define components to be relative, it would have a different meaning depending on the expression that will be relative :

• application point : the provided point is relative to the object position and rotation
• linear force and moment : this provided vector is relative to the object rotation

How to reuse forces

You can define separate abstract forces, which is using the same possibilities listed above, but can use some custom arguments. Then you may insert the abstract forces you defined using their name.

Another good practice if many of your object have the same forces applied to them (with same arguments), is to define an abstract object containing those forces. Then you may apply these forces to every object in your simulation.

Running a simulation

In order to simulate the behavior of a given world, you need to define a Simulation.

Simulation have many properties you can specify :

Name	Description	Mandatory	Example
World	The world to simulate	true	SampleWorld
Simulation speed	Duration of a real time second in the simulation (for huge simulations the time may go slower than the provided rate)	false	[1 min]
Simulation scale	Rendering scale of the simulation, does not impact the size viewed from the camera, this option is to use when the objects and distances are really small or really big and only impact the precision of the rendering (it is recommended to have a scale that fits your smallest object in case of issues)	false	none
Camera position	Position of the camera	false	current world.myObject.position + [30m, 0, 0]
Camera focus	Focus of the camera	false	current.myObjectToSee
Override rules	Replacements for specific values in the simulation	false	current world.myObject.mass = 67 kg
Metrics	Metrics to display during runtime, for expressions with units the unit is displayed automatically		Distance with origin = current world.myObject.distance with([0,0,0])
Alternative views	Alternative views of the simulation that will be displayed next to the original one, you may define override rules or specific metrics for your alternative view		alternative view { override rules [ current world.myObject.texture = color(red, none) ] }

Setting the camera properly

Setting the camera at a right position might be tricky. This section explain some techniques to set it right.

Camera focus

Usually a good start is to set the focus on the object you want to see. You may refer to your objects by accessing the world by typing current world, then access sub-worlds or objects with a ..

Another interesting property is the world mass center property. For objects that are close to each other, using the center of mass of your world might be better than focusing on one single object.

Examples:

• current world.mass center
• current world.myObject (or current world.myObject.position, which you can combine with other vectors)
• current world.myNestedWorld.mass center

Camera position

The second step is to set the camera position. For starters, you may set it close to your camera focus, using relative coordinates : current world.myObject.position + cartesian(x = [30 m], y = 0, z = 0), pick a distance that is in the same scale as your object size. If your object has a radius of 500 m, 1500 m may be a good distance.

You may also use individual part of your object coordinates to follow its track on only some axis : cartesian(x = current world.myObject.position.x, y = [20 m], z = 0).

Note: Setting the camera position as the position of an object will probably result in rendering issues if the texture is set (at time of writing there is no way to disable the rendering) as the camera would be inside your object.