|
|
| Line 1: |
Line 1: |
| | | | |
| − | 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 <tt>data/systems</tt> folder of your Pioneer installation.
| + | Pioneer defines systems in JSON format (as of 2024, definitions in Lua are deprecated), edited using the editor provided with the game. Youtube-demonstration [https://www.youtube.com/watch?v=ZvwtlQa93zk here]. The goal of the editor is to make contributing custom systems as easy as possible, so Pioneer can have more custom systems. Ideally, all core systems should be custom made. |
| | | | |
| | == Design philosophy == | | == 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. | + | A designed system can always be shared with the community (e.g. [http://spacesimcentral.com/community/pioneer/ SpaceSimCentral]) for feedback, 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. |
| | | | |
| − | Please see current custom systems as guide for the style we want for inclusion in master branch, but in short: | + | Please load 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 | | * 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. | | * 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. |
| Line 13: |
Line 13: |
| | * 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 <tt>other_names()</tt> property to overload it (e.g. see source for wolf_359-system for code example) | | * 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 <tt>other_names()</tt> property to overload it (e.g. see source for wolf_359-system for code example) |
| | | | |
| − | == CustomSystem == | + | == Running the Editor == |
| | + | Launch the editor from where the editory binary is located with: |
| | + | editor --system |
| | | | |
| − | Represents a custom star system. Can be just the star definition, in which case the planets will be randomly generated, or can have <tt>CustomSystemBody</tt> objects added for complete control over the system construction.
| + | Note (2024-02): If Microsoft Windows flags the binary as malicious software, it's not. Really. Trust us, bro. If not: you can [https://github.com/pioneerspacesim/pioneer/tree/master/src/editor inspect the source] and compile your own. |
| − | | |
| − | === Constructor ===
| |
| − | <blockquote>s = CustomSystem:new(name, star_types)</blockquote>
| |
| − | *'''name''' (string): system name.
| |
| − | *'''type''' (table): up to four star types. Limited to <tt>BodyType</tt> <tt>STAR_*</tt> types, see [https://codedoc.pioneerspacesim.net/#File:src/lua/LuaConstants.cpp:Constants.BodyType Lua constants] for a list.
| |
| − | *'''returns''': a new <tt>CustomSystem</tt> object.
| |
| − | | |
| − | Example:
| |
| − | | |
| − | <tt>sol = CustomSystem:new('Sol', { 'STAR_G' })</tt>
| |
| − | | |
| − | === Methods ===
| |
| − | | |
| − | '''seed'''
| |
| − | <blockquote>s:seed(value)</blockquote>
| |
| − | 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 <tt>CustomSystem</tt> object (for call chaining)
| |
| − | | |
| − | Example:
| |
| − | | |
| − | <tt>sol:seed(42)</tt>
| |
| − | | |
| − | '''govtype'''
| |
| − | <blockquote>s:govtype(type)</blockquote>
| |
| − | Sets the system government type. It not specified, defaults to Polit.GovType.NONE
| |
| − | | |
| − | *'''type''': government type. Limited to <tt>PolitGovType</tt> types, see [https://codedoc.pioneerspacesim.net/#File:src/lua/LuaConstants.cpp:Constants.PolitGovType Lua constants] for a list.
| |
| − | *'''returns''': the <tt>CustomSystem</tt> object (for call chaining)
| |
| − | | |
| − | Example:
| |
| − | | |
| − | <tt>sol:govtype('EARTHDEMOC')</tt>
| |
| − | | |
| − | '''short_desc'''
| |
| − | <blockquote>s:short_desc(description)`</blockquote>
| |
| − | 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 <tt>CustomSystem</tt> object (for call chaining)
| |
| − | | |
| − | Example:
| |
| − | | |
| − | <tt>sol:short_desc('The historical birthplace of humankind')</tt>
| |
| − | | |
| − | '''long_desc'''
| |
| − | <blockquote>s:long_desc(description)</blockquote>
| |
| − | 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:
| |
| − | | |
| − | <tt>lave:long_desc('[[Lave_is_most_famous_for_its_vast_rain_forests_and_the_Lavian_tree_grub.|Lave is most famous for its vast rain forests and the Lavian tree grub.]])</tt>
| |
| − | | |
| − | '''bodies'''
| |
| − | <blockquote>s:bodies(primary_star, { bodies... })</blockquote>
| |
| − | 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 <tt>CustomSystemBody</tt> 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 <tt>CustomSystem:new</tt>.
| |
| − | *'''bodies''' (table): A table containing zero or more <tt>CustomSystemBody</tt> objects, or further tables of <tt>CustomSystemBody</tt> objects. If a table is passed as one of the elements, then its contents will be added as children of the last <tt>CustomSystemBody</tt> passed.
| |
| − | *'''returns''': nothing
| |
| − | | |
| − | Example:
| |
| − | <pre>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,
| |
| − | },
| |
| − | },
| |
| − | )
| |
| − | </pre>
| |
| − | | |
| − | '''add_to_sector'''
| |
| − | <blockquote>s:add_to_sector(x, y, v)</blockquote>
| |
| − | 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:
| |
| − | <pre>s = CustomSystem:new("Van Maanen's Star", { 'WHITE_DWARF' })
| |
| − | s:add_to_sector(2, 0, 0, v(0.279,0.482,-0.330))
| |
| − | </pre>
| |
| − | | |
| − | == CustomSystemBody ==
| |
| − | | |
| − | Represents a single body within a star system. These can include stars, planets, surface starports and orbital spaceports.
| |
| − | | |
| − | === Constructor ===
| |
| − | <blockquote>b = CustomSystemBody:new(name, type)</blockquote>
| |
| − | *'''name''' (string): body name.
| |
| − | *'''type''' (integer): body type. Limited to <tt>BodyType</tt> constants, see [https://codedoc.pioneerspacesim.net/#File:src/lua/LuaConstants.cpp#Constants.BodyType Lua constants] for a list.
| |
| − | *'''returns''': a new <tt>CustomSystem</tt> object.
| |
| − | | |
| − | Example:
| |
| − | | |
| − | <tt>earth = CustomSystem:new('Earth', { 'PLANET_TERRESTRIAL' })</tt>
| |
| − | | |
| − | === Methods ===
| |
| − | | |
| − | '''seed'''
| |
| − | <blockquote>b:seed(value)</blockquote>
| |
| − | 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 <tt>CustomSystemBody</tt> object (for call chaining)
| |
| − | | |
| − | Example:
| |
| − | | |
| − | <tt>b:seed(42)</tt>
| |
| − | | |
| − | '''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'''
| |
| − | <blockquote>b:radius(r)</blockquote>
| |
| − | 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 <tt>CustomSystemBody</tt> object (for call chaining)
| |
| − | | |
| − | Example:
| |
| − | | |
| − | <tt>mars:radius(f(533,1000))</tt>
| |
| − | | |
| − | '''mass'''
| |
| − | <blockquote>b:mass(m)</blockquote>
| |
| − | 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 <tt>CustomSystemBody</tt> object (for call chaining)
| |
| − | | |
| − | Example:
| |
| − | | |
| − | <tt>mars:mass(f(107,1000))</tt>
| |
| − | | |
| − | '''temp'''
| |
| − | <blockquote>b:temp(k)</blockquote>
| |
| − | Sets the body temperature.
| |
| − | | |
| − | *'''k''' (integer): average surface temperature in kelvin.
| |
| − | *'''returns''': the <tt>CustomSystemBody</tt> object (for call chaining)
| |
| − | | |
| − | Example:
| |
| − | | |
| − | <tt>mars:temp(274)</tt>
| |
| − | | |
| − | '''semi_major_axis'''
| |
| − | <blockquote>b:semi_major_axis(a)</blockquote>
| |
| − | Sets the [http://en.wikipedia.org/wiki/Semi-major_axis 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 <tt>CustomSystemBody</tt> object (for call chaining)
| |
| − | | |
| − | Example:
| |
| − | | |
| − | <tt>mars:semi_major_axis(f(152,100))</tt>
| |
| − | | |
| − | '''eccentricity'''
| |
| − | <blockquote>b:eccentricity(e)</blockquote>
| |
| − | Sets the [http://en.wikipedia.org/wiki/Orbital_eccentricity eccentricity] of the body's orbit.
| |
| − | | |
| − | This value is ignored for non-orbital bodies.
| |
| − | | |
| − | *'''e''' (fixed): eccentricity
| |
| − | *'''returns''': the <tt>CustomSystemBody</tt> object (for call chaining)
| |
| − | | |
| − | Example:
| |
| − | | |
| − | <tt>mars:eccentricity(f(933,10000))</tt>
| |
| − | | |
| − | '''inclination'''
| |
| − | <blockquote>b:inclination(i)</blockquote>
| |
| − | Sets the [http://en.wikipedia.org/wiki/Inclination inclination] of the body's orbit.
| |
| − | | |
| − | This value is ignored for non-orbital bodies.
| |
| − | | |
| − | *'''i''' (number): inclination in radians
| |
| − | *'''returns''': the <tt>CustomSystemBody</tt> object (for call chaining)
| |
| − | | |
| − | Example:
| |
| − | | |
| − | <tt>mars:inclination(math.deg2rad(1.85))</tt>
| |
| − | | |
| − | '''latitude'''
| |
| − | <blockquote>b:latitude(l)</blockquote>
| |
| − | 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 <tt>CustomSystemBody</tt> object (for call chaining)
| |
| − | | |
| − | Example:
| |
| − | | |
| − | <tt>shanghai:latitude(math.deg2rad(31))</tt>
| |
| − | | |
| − | '''longitude'''
| |
| − | <blockquote>b:longitude(l)</blockquote>
| |
| − | 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 <tt>CustomSystemBody</tt> object (for call chaining)
| |
| − | | |
| − | Example:
| |
| − | | |
| − | <tt>shanghai:longitude(math.deg2rad(-121))</tt>
| |
| − | | |
| − | '''rotation_period'''
| |
| − | <blockquote>b:rotation_period(p)</blockquote>
| |
| − | Sets the body's [http://en.wikipedia.org/wiki/Rotation_period rotation period].
| |
| − | | |
| − | This value is ignored for non-orbital bodies.
| |
| − | | |
| − | *'''p''' (fixed): rotation period in days
| |
| − | *'''returns''': the <tt>CustomSystemBody</tt> object (for call chaining)
| |
| − | | |
| − | Example:
| |
| − | | |
| − | <tt>mars:rotation_period(f(1027,1000))</tt>
| |
| − | | |
| − | '''axial_tilt'''
| |
| − | <blockquote>b:axial_tilt(t)</blockquote>
| |
| − | Set's the body's [http://en.wikipedia.org/wiki/Axial_tilt axial tilt].
| |
| − | | |
| − | This value is ignored for non-orbital bodies.
| |
| − | | |
| − | *'''t''' (fixed): axial tilt in radians
| |
| − | *'''returns''': the <tt>CustomSystemBody</tt> object (for call chaining)
| |
| − | | |
| − | Example:
| |
| − | | |
| − | <tt>mars:axial_tilt(math.fixed.deg2rad(f(2519,100)))</tt>
| |
| − | | |
| − | '''height_map'''
| |
| − | <blockquote>b:height_map(file)</blockquote>
| |
| − | Specifies a [[Planet_Heightmaps|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 <tt>data</tt> folder.
| |
| − | *'''returns''': the <tt>CustomSystemBody</tt> object (for call chaining)
| |
| − | | |
| − | Example:
| |
| − | | |
| − | <tt>earth:height_map('earth.hmap')</tt>
| |
| − | | |
| − | '''metallicity'''
| |
| − | <blockquote>b:metallicity(m)</blockquote>
| |
| − | 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 <tt>CustomSystemBody</tt> object (for call chaining)
| |
| − | | |
| − | Example:
| |
| − | | |
| − | <tt>earth:metallicity(f(1,2))</tt>
| |
| − | | |
| − | '''volcanicity'''
| |
| − | <blockquote>b:volcanicity(v)</blockquote>
| |
| − | 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 <tt>CustomSystemBody</tt> object (for call chaining)
| |
| − | | |
| − | Example:
| |
| − | | |
| − | <tt>venus.volcanicity(f(8,10))</tt>
| |
| − | | |
| − | '''atmos_density'''
| |
| − | <blockquote>b:atmos_density(d)</blockquote>
| |
| − | 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 <tt>CustomSystemBody</tt> object (for call chaining)
| |
| − | | |
| − | Example: <tt>venus:atmos_density(f(93,1))</tt>
| |
| − | | |
| − | '''atmos_oxidizing'''
| |
| − | <blockquote>b:atmos_oxidizing(o)</blockquote>
| |
| − | 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 <tt>CustomSystemBody</tt> object (for call chaining)
| |
| − | | |
| − | Example:
| |
| − | | |
| − | <tt>venus:atmos_oxidizing(f(8,10))</tt>
| |
| − | | |
| − | '''ocean_cover'''
| |
| − | <blockquote>b:ocean_cover(p)</blockquote>
| |
| − | 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 <tt>CustomSystemBody</tt> object (for call chaining)
| |
| − | | |
| − | Example:
| |
| − | | |
| − | <tt>earth:ocean_cover(f(7,10))</tt>
| |
| − | | |
| − | '''ice_cover'''
| |
| − | <blockquote>b:ice_cover(p)</blockquote>
| |
| − | 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 <tt>CustomSystemBody</tt> object (for call chaining)
| |
| − | | |
| − | Example:
| |
| − | | |
| − | <tt>earth:ice_cover(f(3,100))</tt>
| |
| − | | |
| − | '''life'''
| |
| − | <blockquote>b:life(p)</blockquote>
| |
| − | 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 <tt>CustomSystemBody</tt> object (for call chaining)
| |
| − | | |
| − | Example:
| |
| − | | |
| − | <tt>earth:life(f(9,10))</tt>
| |
