Custom Systems

This page describes the Lua API for defining custom star systems. If you're getting started you should look at the existing definitions in the data/systems folder of your Pioneer installation.

CustomSystem

Represents a custom star system. Can be just the star definition, in which case the planets will be randomly generated, or can have CustomSystemBody objects added for complete control over the system construction.

Constructor

s = CustomSystem:new(name, star_types)

• name (string): system name.
• type (table): up to four star types. Limited to BodyType STAR_* types, see Lua constants for a list.
• returns: a new CustomSystem object.

Example:

sol = CustomSystem:new('Sol', { 'STAR_G' })

Methods

seed

s:seed(value)

Sets the system seed. This is used to initialise the random number generator that is used to select planet types and other system attributes. If not specified, defaults to 0.

• value (integer): seed value
• returns: the CustomSystem object (for call chaining)

Example:

sol:seed(42)

govtype

s:govtype(type)

Sets the system government type. It not specified, defaults to Polit.GovType.NONE

• type: government type. Limited to PolitGovType types, see Lua constants for a list.
• returns: the CustomSystem object (for call chaining)

Example:

sol:govtype('EARTHDEMOC')

short_desc

s:short_desc(description)`

Sets the short description of the system. This is shown in star map. If not specified a description is generated based on the population and resources of the system.

• description (string): short description
• returns: the CustomSystem object (for call chaining)

Example:

sol:short_desc('The historical birthplace of humankind')

long_desc

s:long_desc(description)

Sets the long description of the system. This is show in the system info view. If not specified no description is displayed.

• description (string): long description. This may span multiple lines.

Example:

lave:long_desc('Lave is most famous for its vast rain forests and the Lavian tree grub.)

bodies

s:bodies(primary_star, { bodies... })

Adds custom bodies to the system. If no bodies are added then planets and starports will be randomly generated based on the system seed value.

Note that after this call that bodies passed to it have been "committed". Further changes to the CustomSystemBody objects from Lua will be ignored.

• primary_star (CustomSystemBody): a body for the primary star. It must have the same type as the first star passed to CustomSystem:new.
• bodies (table): A table containing zero or more CustomSystemBody objects, or further tables of CustomSystemBody objects. If a table is passed as one of the elements, then its contents will be added as children of the last CustomSystemBody passed.
• returns: nothing

Example:

lave = CustomSystem:new("Lave", { 'STAR_G' })

lave_star    = CustomSystemBody:new("Lave", 'STAR_G')
lave_planet  = CustomSystemBody:new("Planet Lave", 'PLANET_TERRESTRIAL')
lave_station = CustomSystemBody:new("Lave Station", 'STARPORT_ORBITAL')

lave:bodies(
    lave_star, {
        lave_planet, {
            lave_station,
        },
    },
)

add_to_sector

s:add_to_sector(x, y, v)

Adds the system to the universe.

Note that after this call the system has been "committed". Further changes to the system or its bodies will be ignored.

• x (integer): The x coordinate of the sector to add the system to.
• y (integer): The y coordinate of the sector to add the system to.
• z (integer): The z coordinate of the sector to add the system to.
• v (vector): The precise (x,y,z) location of the system within the sector.

Example:

s = CustomSystem:new("Van Maanen's Star", { 'WHITE_DWARF' })
s:add_to_sector(2, 0, 0, v(0.279,0.482,-0.330))

CustomSystemBody

Represents a single body within a star system. These can include stars, planets, surface starports and orbital spaceports.

Constructor

b = CustomSystemBody:new(name, type)

• name (string): body name.
• type (integer): body type. Limited to BodyType constants, see Lua constants for a list.
• returns: a new CustomSystem object.

Example:

earth = CustomSystem:new('Earth', { 'PLANET_TERRESTRIAL' })

Methods

seed

b:seed(value)

Sets the body seed. This is used to initialise the random number generator that is used to drive the terrain generator, set body names and other planetary attributes. If not specified it will be generated from the system seed.

• value (integer): seed value
• returns: the CustomSystemBody object (for call chaining)

Example:

b:seed(42)

radius

b:radius(r)

Sets the body radius.

• r (fixed): radius. For stars, 1.0 is the radius of Sol. For planets, 1.0 is the radius of Earth.
• returns: the CustomSystemBody object (for call chaining)

Example:

mars:radius(f(533,1000))

mass

b:mass(m)

Sets the body mass.

• m (fixed): mass. For stars, 1.0 is the mass of Sol. For planets, 1.0 is the mass of Earth.
• returns: the CustomSystemBody object (for call chaining)

Example:

mars:mass(f(107,1000))

temp

b:temp(k)

Sets the body temperature.

• k (integer): average surface temperature in kelvin.
• returns: the CustomSystemBody object (for call chaining)

Example:

mars:temp(274)

semi_major_axis

b:semi_major_axis(a)

Sets the semi-major axis of the body's orbit.

This value is ignored for non-orbital bodies.

• a (fixed): semi-major axis in AUs
• returns: the CustomSystemBody object (for call chaining)

Example:

mars:semi_major_axis(f(152,100))

eccentricity

b:eccentricity(e)

Sets the eccentricity of the body's orbit.

This value is ignored for non-orbital bodies.

• e (fixed): eccentricity
• returns: the CustomSystemBody object (for call chaining)

Example:

mars:eccentricity(f(933,10000))

inclination

b:inclination(i)

Sets the inclination of the body's orbit.

This value is ignored for non-orbital bodies.

• i (number): inclination in radians
• returns: the CustomSystemBody object (for call chaining)

Example:

mars:inclination(math.deg2rad(1.85))

latitude

b:latitude(l)

Sets the latitude of the body's position on its planet.

This value is ignored for orbital bodies.

• l (number): latitude in radians
• returns: the CustomSystemBody object (for call chaining)

Example:

shanghai:latitude(math.deg2rad(31))

longitude

b:longitude(l)

Sets the longitude of the body's position on its planet.

This value is ignored for orbital bodies.

• l (number): longitude in radians
• returns: the CustomSystemBody object (for call chaining)

Example:

shanghai:longitude(math.deg2rad(-121))

rotation_period

b:rotation_period(p)

Sets the body's rotation period.

This value is ignored for non-orbital bodies.

• p (fixed): rotation period in days
• returns: the CustomSystemBody object (for call chaining)

Example:

mars:rotation_period(f(1027,1000))

axial_tilt

b:axial_tilt(t)

Set's the body's axial tilt.

This value is ignored for non-orbital bodies.

• t (fixed): axial tilt in radians
• returns: the CustomSystemBody object (for call chaining)

Example:

mars:axial_tilt(math.fixed.deg2rad(f(2519,100)))

height_map

b:height_map(file)

Specifies a planet heightmap file to use for the planetary terrain. The planet terrain will be generated based on its composition attributes if this is not specified.

• file (string): filename relative to the Pioneer data folder.
• returns: the CustomSystemBody object (for call chaining)

Example:

earth:height_map('earth.hmap')

metallicity

b:metallicity(m)

Sets the metallicity of the planet's crust.

• m (fixed): metallicity from 0.0 to 1.0, where 0.0 indicates light metals (eg aluminium, silicon dioxide) and 1.0 indicates heavy metals (eg iron).
• returns: the CustomSystemBody object (for call chaining)

Example:

earth:metallicity(f(1,2))

volcanicity

b:volcanicity(v)

Sets the volcanicity of the planet's surface.

• v (fixed): volcanicity from 0.0 to 1.0, where 0.0 indicates no volcanic activity and 1.0 indicates constant volcanic activity over the entire surface.
• returns: the CustomSystemBody object (for call chaining)

Example:

venus.volcanicity(f(8,10))

atmos_density

b:atmos_density(d)

Sets the atmospheric density of the planet.

• d (fixed): atmospheric density, where 0.0 is no atmosphere and 1.0 is Earth atmospheric density
• returns: the CustomSystemBody object (for call chaining)

Example: venus:atmos_density(f(93,1))

atmos_oxidizing

b:atmos_oxidizing(o)

Sets the amount of oxidizing gases in the planet's atmosphere.

• o (fixed): amount of oxidizing gases, where 0.0 is all reducing gases (hydrogen, ammonia, etc) and 1.0 is all oxidizing gases (oxygen, carbon dioxide, etc)
• returns: the CustomSystemBody object (for call chaining)

Example:

venus:atmos_oxidizing(f(8,10))

ocean_cover

b:ocean_cover(p)

Sets the percentage of the planet's surface that is covered by water.

• p (fixed): water coverage, where 0.0 is no water and 1.0 is all water
• returns: the CustomSystemBody object (for call chaining)

Example:

earth:ocean_cover(f(7,10))

ice_cover

b:ice_cover(p)

Sets the percentage of the planet's surface that is covered by ice.

• p (fixed): ice coverage, where 0.0 is no ice and 1.0 is all ice
• returns: the CustomSystemBody object (for call chaining)

Example:

earth:ice_cover(f(3,100))

life

b:life(p)

Sets the amount of life on the planet.

• p (fixed): amount/complexity of life, where 0.0 is no life and 1.0 is everything from single-celled things right up to advanced animals/humans.
• returns: the CustomSystemBody object (for call chaining)

Example:

earth:life(f(9,10))