Spawn Scripting

Gravit Home / Documentation Index

Overview

As of version 0.4.0, Gravit has scriptable spawning locations. This allows you to specify how a simulation begins, by choosing where each particle goes, what velocities they have and their mass. The syntax of the scripting language is called Lua, if you want to learn the basics check out some of these tutorials:

For comprehensive information you can view the Lua book "Programming in Lua" and the Lua reference manual:

Functions and Variables

As well as the standard Lua functions, Gravit adds a few functions and variables to spawn scripts. There are many functions available in functions.lua in your spawn directory. Below I'll list the most important ones:

spawnparticles

spawnparticles is a variable in the form of an integer that tells you how many particles are being spawned.

particle

particle is a function that accepts 4 variables -- id, position, velocity and mass. id is a number from '0' to 'spawnparticles-1'. position and velocity are a v() type (see below). mass is a floating point number that can be negative if you want. For example the following will spawn particle 0 at position (5,5,5) with a velocity of (1,0,0) and a mass of 100:

particle(0, v(5,5,5), v(1,0,0), 100)

log

log is a function that prints to the Gravit console. It is used for the describe function and for debugging. For example:

log("Hello, World!")

v

v is a type of function that represents a 3D vector. You can do things like add, subtract and access individual elements. For example:

vector1 = v(0, 0, 0)
vector2 = v(10, 0, 0)
vector3 = vector1 + vector2
vector3.z = 20

In this example, vector3 ends up being (10, 0, 20). You can see many examples of this in the existing spawn scripts.

Functions required in .gravitspawn files

There are two functions you need to declare in every gravitspawn file.

describe

This function is called as soon as this simulation is selected to spawn. All it should do is print a short description of what the simulation does.

spawn

This function is called right after describe to spawn each particle. Make sure each particle is spawned in a unique position.

A simple example