Gravitator User Guide
Table of contents
Gravitator is an interactive gravity simulator with editor of the world. It's focus is on simulation of large quantities of objects.
This is possible because the objects fall into 2 categories: light and heavy. Heavy objects atract every other object, light objects
don't attract any other object. Usually there are mostly tens of heavy and thousands of light objects. This enables simulation of space
objects like galaxies and asteroid rings. To help you create such complex objects, Gravitator has an editor of the world capable of
generating them for you. The editor is also capable of manipulating the objects and calculating stable orbit for them.
The Editor in Gravitator enables you to create and manipulate objects in the world. By world I mean the objects which can be simulated.
Besides that there are light and heavy objects, the editor uses the terms of "object" and "metaobject". Object is just a simple object.
Metaobject is a group of objects with something similar, e.g. it's a galaxy, an asteroid ring, a group of objects forming a sphere
etc.. The editor enables you to manipulate the objects and metaobjects.
Of course the editor allows you to perform basic operations as saving, loading a world and exiting.
- Creating a new world - to create a new world, click on the file entry in the menubar and select New
- Loading an existing world - to load an exiting world, click on the Load button in the toolbar or click on the
file entry in the menubar and select Open , then select the file with the saved world
- Saving an existing world - to save the world, click on the Save button in the toolbar or click on the
file entry in the menubar and select Save , then select a file to which you want to save the world
- Exiting the application - to exit the application, click on the file entry in the menubar and select Exit or
close the application window
- Setting preferences of Gravitator - you can set the Gravitator preferences after clicking on the Properties entry in the
Settings menu, in the Preferences window you can set if you want to restore your previous session after starting Gravitator
(this will load the previously edited world and set the same position in it), you can set the default speed division (which
determines the time step, the higher speed division, the slower the time step and higher accuracy of the simulation) and default
frame delay (which determines the delay between loading frames while playing a script). If your session will be restored, so will
be restored you last used speed division and frame delay, they won't be set to the default values. Also in the preferences window you
can set keys for moving in the world.
- Showing the About dialog - to show the about dialog, click on the About entry in the Help menu
Viewing and manipulating the world
The editor has four views on the world. The upper left is from the front, the upper right is the the right side, the lower left is
from above and the lower right is a 3D view. The first 3 views are used for manipulating the world, the last one is for viewing the
world from any direction.
The world is big 1000 units in each direction from the origin. The axis orientation as if looked from the front view is as follows: the
x axis is horizontal, positive in the right direction, y axis is vertical, positive in the up direction and the z axis is the depth,
it's positive in the direction to you.
Viewing the world
The upper left, right and lower left views are orthogonal, that means the view isn't perspectively correct. You can change your
position in them by using the scrollbars. If you click in the arrows on the scrollbars, you move very slowly, that's for fine
positioning. You can zoom in and zoom out in these view by clicking the Zoom in and Zoom out buttons next to
them. If you want to return to the default position, then click the Center button. In these views you can see grid lines. The
brightest 2 of them are the axis lines, which show the x, y, and z axis. The darker ones are drawn every 100 units. If you're zoomed in
close enough, you'll see the darkest lines, which are drawn every 10 units.
To move and look around in the 3D view, you must use your keyboard. To be able to move in the 3D view, you must place the mouse
cursor in it. Look in the preferences window to see the keys used for it. If you click the Center button, you return to the
default position. Notice that the x, y and z axis are drawn, and the horizontal plane is also drawn.
Manipulating the world
Selecting and manipulating objects in this editor is quite classical as in every editor of some objects. You can click a object to
select it, if you click where no object is then you deselect your previously selected object. You can drag a rectangle with your mouse
to select all objects in the rectangle. If you hold Ctrl key pressed, then you add your current selection to the previous one. To move
the selected object, just click on one of them and drag it to the new position.
You can also select and move metaobjects. To select a metaobject, click on its name in the list of metaobjects in the lower right
corner of the window. You can select multiple metaobjects this way. In the metaobject list you can also set if the metaobject is
visible by clicking on the checkbutton next to the metaobject's name. Invisible objects are of course invisible, and you also cannot
select them, which is handy if you have too many objects in the world or you don't want to select objects in the metaobject.
To create a new object, select the desired metaobject type in the list of new objects in the upper right side of the window and click
on the Create button. Then you will see a window with the objects properties a and you can position the object. Click in one of
the orthogonal views to place it, then you can also move it like an ordinary object. You can set the objects properties in the object's
window. In the upper part of the window you can see it's position. When you're happy with the object's properties and position, then
click on the Ok button. If you don't want to create it, then click the Cancel button or close the object's window.
-this is just a simple object, in it's window you must set if it's a light or heavy object, set it's velocity, color (notice: the color
values are in interval from 0 to 1), mass, size (diameter) and name
-this is a homogenous ball of objects, that means this are objects evenly placed to a shape of a ball. You must set if the objects will
be light or heavy, their velocity, color, mass and size. You must also set the name of the new metaobject, the diameter of the ball and
the number of objects in the ball.
-this is a homogenous cylinder of objects, that means this are objects evenly placed to a shape of a cylinder. You must set if the
objects will be light or heavy, their velocity, color, mass and size. You must also set the name of the new metaobject, the diameter of
the cylinder, the height of the cylinder and the number of objects in the cylinder.
Hollow Homogenous Cylinder
-this is a hollow homogenous cylinder of objects, that means this are objects evenly placed to a shape of a cylinder with a hollow in
it's midle. You must set if the objects will be light or heavy, their velocity, color, mass and size. You must also set the name of the
new metaobject, the diameter of the cylinder, the inner diameter of the cylinder, the height of the cylinder and the number of objects
in the cylinder. This metaobject is especially usefull for creating rings of asteroids.
-this is an ellipsoid of objects, that means this are objects evenly placed to a shape of an ellipsoid. You must set if the objects
will be light or heavy, their velocity, color, mass and size. You must also set the name of the new metaobject, the diameter of the
ellipsoid in all 3 directions and the number of objects in the ellipsoid.
-this creates a spiral galaxy, that is a galaxy with stars in it's spirals and in it's centre. You must specify the velocity of the
galaxy, the color of it's objects, the size (diameter) of it's objects and mass of it's central object. You must also specify the
galaxy's name, if the objects will rotate clockwise or counterclockwise (as if looked from above), the diameter of the galaxy
centre and number of objects in the centre. You must also specify the properties of the spirals of the galaxy, that is the
total number of objects in all spirals, number of spirals, length of spirals, number of spiral's segments (the spirals aren't perfectly
round, they are made of cylinders with decreasing diameter, these cylinders are the segments, the more segments you enter, the more
round will the spiral be, but usually you don't need too much of them) and angle between segments(this specifies how much will the
-this creates a disk galaxy, which is a galaxy with objects in it's centre and in a disk around it. You must specify the velocity of
the galaxy, the color of it's objects, the size (diameter) of it's objects and mass of it's central object. You must also specify the
galaxy's name, direction of rotation of it's objects (clockwise or counterclockwise). You must also specify height of the centre,
diameter of the centre, number of objects in the centre, height of the disk, diameter of the disk and number of objects in the disk.
-this creates an elliptic galaxy, which is a galaxy in the shape of an ellipsoid. You must specify the velocity
of the galaxy, the color of it's objects, the size (diameter) of it's objects and mass of it's central object. You must also specify
the galaxy's name, direction of rotation of it's objects (clockwise or counterclockwise). You must also specify height of the galaxy,
diameter of the galaxy and number of objects in the galaxy.
-this creates an ellipsoid void, which means that every object inside this void will be deleted. You must specify it's diameter in all
-this creates a sphere void, which means that every object inside this void will be deleted. You must specify it's
-this creates a cylinder void, which means that every object inside this void will be deleted. You must specify it's diameter
In the midle of the toolbar there are several icons for editing objects, you can rotate them, edit them, delete them and calculate a
-to rotate objects click on the Rotate button on the toolbar. First you must place the rotation axis in one of the orthogonal
views. For example if you place it in the front view, you will be rotating the object in the front view around the z axis. When
you've placed the axis, click on the Ok button. Then you can rotate the objects in the view where you placed the rotation axis by
dragging the mouse. Notice that you can also rotate the selected metaobjects in the same way.
-to edit an object or metaobject click on the Edit button on the toolbar. In the appeared window you can set the new properties
of the object or metaobject. You can edit only one object at a time, if you want to edit more then edit their metaobject. This is
because you probably don't want to have half of an asteroid ring red a the other half blue...But if enough users will write me that
they want to be able to edit more objects, then I will add that feature.
-clicking on the Delete button deletes the currently selected objects/metaobjects.
Calculate stable orbit
-to calculate a stable orbit for the selected objects/metaobjects, click on the Orbit button. Then select the object around
which you want them to orbit and click Ok. Then rotate the orbit axis in the front and right view and choose whether should it rotate
clockwise or counterclockwise. Notice that you cannot turn the rotate axis all the way around, you can mostly make it horizontal. It's
because you don't need it, the same behaviour can be achieved by selecting the direction of orbit.
To start the simulation click on the Start button in the toolbar. A window will appear where you can set the simulation
properties. There are 3 view modes: Free look, Look at and Constant position. If you select the Free Look, you can freely move and turn
in the world during the simulation. If you select the Look At mode, then the view points to the selected metaobject. You can also set a
minimal and maximal distance to the metaobject on which you're looking. In the constant position mode the position and rotation in the
world remains stable relatively to the selected object. You can also select the speed division in this window. Higher speed division
means higher acurracy, but slower simulation. These settings can be changed also during the simulation. To start the simulation, press
the Ok button.
In the simulation window you can see the simulated world and move in it. You move in it in the same way as in the 3D view (you must
have the mouse cursor above it).The starting position and rotation is the same as the actual position and rotation in the 3D view.By
clicking the Save button you can save the current state of the simulated world to a file. By clicking on the Restart
button you can restart the simulation, the Pause button pauses the simulation and Start button starts a paused
simulation. You can also change the speed division in the upper right part of the window. If you click on the Preferences tab in
the top part of the window, you can change the view mode. Notice that you must press the ENTER key to confirm a new minimal or
maximal distance. If you click on the Preferences tab then the simulation pauses.
Play a script
With using the gravitator_daemon program, you can save the simulation in a file, which is then called a script file. The advantage is
that you can save only every n-th frame, so you can set a high speed division and stil see the simulation go fast. To play a script,
click the Play script button in the toolbar. In the appeared window choose the file with the saved script. You can also set the
frame delay, which specifies how often will the application load another frame. The time is in milliseconds. Notice that when
you have too many objects in the script file, then the loading of the file takes some time, and you also need to leave some time for
the GUI to be responsive, so with many objects the frames are displayed mostly few times per second. To start playing the script push
the Ok button. The window playing the script is almost the same as the window showing the simulation.