Custom Systems

From PioneerWiki
Revision as of 10:28, 2 October 2019 by Impaktor (talk | contribs) (Add general design tips for inclusion in main game)
Jump to: navigation, search

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.

Design philosophy

A designed system can always be shared with the community (mainly SpaceSimCentral), but of course it is much more rewarding to see your custom designed system included in the game, and this is one of the easiest contributions you can make, and also easy for maintaners to test and merge. Ideally, at some point all the core systems are custom made.

Please see current custom systems as guide for the style we want for inclusion in master branch, but in short:

  • Do not infringe on trademarks: no Star Wars, Star Trek, Elite/Frontier, Nintendo, references
  • No aliens please. There can be alien life forms, like fauna, animals, but in general, we do not want "grays", or "E.T.". However, there can be tasteful hints to mysteries in system description, e.g. think of the writings of Arthur C. Clarke.
  • If you include some history of the system in the description, then make sure it fits with the lore/time line of Pioneer_Universe.
  • No "non-physical" systems: meaning, all systems should be "sane", from an astronomical stand point.
  • If your system is an existing star, model it as closely as possible to real astronomical data, e.g. star size, temperature, color, does it have known exo-plantes? Does it have multiple names, e.g. propper name, and star catalouge name? If so, use other_names() property to overload it (e.g. see source for wolf_359-system for code example)

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. Origin is the bottom and lower left corner of the sector. The coordinates are between 0.000 and 1.000 and must have three decimal places (the system will not be selectable if this is incorrect.)

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)

Our system uses a fixed-point number system to avoid differences in represenation on various platforms... basically PC/Mac/Linux/ARM/x86 or whatever all produce slightly different results of floating point operations, fixed point maths avoids that.

So you need to convert the values to fixed so 0.5330717313 -> (533, 1000) which is the same as 533 / 1000 = 0.533 If you wanted more precision to include the `07` for example, then (53307, 100000) = 53307 / 100000 = 0.53307 (In the example, the radius of Mars is given)

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))

Retrieved from "https://wiki.pioneerspacesim.net/index.php?title=Custom_Systems&oldid=3890"