SpaceSim - Scripting

Scripted objects

SpaceSim allows you to create custom objects using the Lua language.

Example:

You can try adding a scripted object by copying the script below, or by downloading it.

require("math")

-- Name of this object. This will be the label of the button added to 'Custom objects'.
objectName = "Color cloud";

-- Table of object parameters that will be shown in the UI.
parameters = {}

parameters.radius = Constants.R_Earth;
parameters.density = 10000;
parameters.spinRate = 0.0004;
parameters.particleScale = 0.01;

-- Returns the total volume of the object. This function is used to determine 
-- how many particles are assigned to the object.
function getVolume()
    return 0.02 * math.pi * math.pow(parameters.radius, 3);
end

-- Returns the total mass of the object.
function getTotalMass()
    return getVolume() * parameters.density;
end

math.randomseed(os.time())

-- Main entry point of the script. The function will create a table containing 
-- all particle data of the object.
function generate(n)
    state = {}
    state.position = {};
    state.velocity = {};
    state.mass = {};
    state.density = {};
    state.radius = {};
    state.color = {};

    phi = 2 * math.pi / n;
    for i=1,n
    do
        r = math.pow(math.random(), 0.66) * parameters.radius;
        v = r * parameters.spinRate;
        state.position[i] = { r * math.cos(phi * i),
                              r * math.sin(phi * i),
                              0.01 * parameters.radius * (math.random(-1, 1)) };
        state.velocity[i] = { v * math.sin(phi * i),
                              -v * math.cos(phi * i),
                              0 };
        state.radius[i] = parameters.particleScale * Constants.R_Earth;
        state.density[i] = parameters.density;
        state.mass[i] = parameters.density * 4.0/3.0 * math.pi * math.pow(state.radius[i], 3);
        state.color[i] = { state.position[i][1] / r,
                           0.5,
                           state.position[i][2] / r };
    end
    
    return state;
end

Script functions

The script must define the following mandatory functions.

generate(N)	Function creating particles. Takes the number of particles as an input parameter.
getTotalMass	Returns the total mass of the object.
getVolume	Return the total volume of the object.

Quantities

Script function generate has to return a table containing the particle quantities. All quantities are assumed to be in SI units (meters, kilograms, Joules, etc.). The following quantities are mandatory and have to be returned by the function for the object to work:

position	Positions of all particles
velocity	Velocities of all particles
mass	Particle masses
radius	Particle radii

Optionally, the script can also return additional quantities, namely:

density	Particle densities
color	Diffuse color of particles
temperature	Temperatures, used to calculate the glow color
energy	Initial specific internal energy, used by the SPH solver
normal	Initial surface normal of particles
uv	Texturing coordinates, a table containing two values in the interval [0, 1].

If the density specified, the object enables the hydrodynamic solver and handles particle collisions, otherwise a pure gravity solver solver is used for the simulation.

Variables

Optionally, the script can define a global table named parameters, containing key-value pairs. If used, the values will appear in the object panel and can be modified along other object properties, such as position or rotation. Currently, only number parameters are supported. Values of different types are ignored.
The script can also define the following variables:

objectName

Name of the object in the "Add object" panel

Constants

The script can use a few useful constants, defined in the global table Constants.

R_Earth	Earth radius
R_Sun	Solar radius
au	Astronomical unit
M_Earth	Earth mass
M_Sun	Solar mass