Space Engine | Creating a star
626
page-template-default,page,page-id-626,page-child,parent-pageid-519,eltd-cpt-1.0,ajax_leftright,page_not_loaded,,se-ver-2.1, vertical_menu_with_scroll,transparent_content,blog_installed,wpb-js-composer js-comp-ver-5.0.1,vc_responsive
Creating a star

This manual describes how to add a star to SpaceEngine. Before continue, it is recommended to read this manual: Introduction.

The majority of stars in default SpaceEngine installation are stored in the csv file data/catalogs/Catalogs0980.pak/stars/HIPPARCOS.csv. This is the HIPPARCOS star catalog with about 110,000 stars. Other stars, including binary systems, are stored in multiple sc files in the same system pak file. These default files should not be modified or changed in any way. If you want to update a star, remove it, or add a new one, create your own sc or csv file in the addons/catalogs/stars/ folder. SpaceEngine have scripting options to modify and remove a stars or other objects from the default catalogs, or to add a new ones.

The csv format for catalogs is designed to create a large catalogs of objects with similar data. It is more compact and load faster than sc, but have limited types of data which can be specified in it. It is just a table with values separated by coma. The sc format is designed to specify any possible data what SE can use to describe an object. It is a script-like text with ‘tags’ used to describe an object (star or star system in this tutorial) and its various parameters. First we’ll describe the sc file format.

The star catalog

Lets consider you want to create a new solitary star called “Mono”, a black hole with accretion disk called “Hole”, and a binary star system called “Bin”, which contains two stars “Bin A” and “Bin B”. Lets consider what stars “Bin A” and “Bin B” was described already in some catalog as a solitary stars, and you want to delete them to create a proper binary star system with orbits for each component. Go to the addons/catalogs/stars/ directory (create it if not exist) and create a new text document there. Rename it to mystars.sc (the file name doesn’t matter, but make sure it doesn’t match some existing file, otherwise you file will override it). Open it in the notepad and type this code:

Code


// Create a new object – a solitary star.
Star    “Mono”
{

RA       16 10 45  // right ascension
Dec     -25 12 11  // declination
Dist     100.0     // distance from the Sun
Class   “G5V”      // spectral class
Lum      0.86      // luminosity, or
//AbsMagn  5.31    // absolute magnitude, or
//AppMagn  10.31   // visual magnitude
RadSol   0.95      // radius in Solar radii
MassSol  0.91      // mass in Solar masses
Teff     5200      // surface temperature in Kelvins

}
// Create a new object – a solitary star (black hole) with extra
// parameters (accretion disk) in the planets catalog. Note
// what it’s name here is “Hole system”, read below why.
StarBarycenter    “Hole system”
{

RA       09 31 14  // right ascension
Dec      64 16 38  // declination
Dist     250.0     // distance from the Sun
Class   “X”        // spectral class – black hole
Lum      150       // luminosity of the whole system (accretion disk)// That’s enough, accretion disk will be described in the planets catalog (see below).

}

// Remove solitary stars from the older catalogs.
Remove “Bin A”
Remove “Bin B”

// Create a new object – a barycenter of a binary star system,
// which components will be described in the planets catalog (see below).
StarBarycenter    “Bin”
{

RA       19 50 18  // right ascension
Dec      28 18 47  // declination
Dist     251.652   // distance from the Sun

// That’s enough, StarBarycenter tag may not have other parameters (see below).

}

To add a new star or modify a star which has been already described in the catalogs, simply define a new object (Star or StarBarycenter) with the same name in the star script. SpaceEngine will update the old star with the new data (it’s also possible to change its type – from Star to StarBarycenter and back).

To remove a star from the catalogs, use the Remove parameter with the name of that star. This is useful to upgrade some binary catalog stars, which was represented in SE as a two solitary stars, into a complete binary star system with each star on a correct orbit. Note: the Remove parameter seems to affect all catalog files, despite on their modification date. It is a bug in the current version (0.9.8.0).

Note what the star catalog does not describes the components of the binary or multiple star system. They must be described in the planets catalog and referring to the barycenter with the parameter ParentBody (see below). So, strictly speaking, the stars catalogs in SE are catalogs of star systems, not stars themselves (although they allows to describe a solitary stars without creating a planets catalogs for them). Visual parameters such as summary luminosity of the system will be calculated by SpaceEngine automatically, based on data for the system’s components described in the planets catalog. Although they may be forced by defining parameters Luminosity, AppMagn etc in the StarBarycenter tag.

The star script details

The next parameters can be used inside the Star and StarBarycenter tags.

RA – right ascension in hours, in decimal format or formatted as HH MM SS.SSS
Dec – declination in degrees, in decimal format or formatted as DD MM SS.SSS
Dist – distance from the Sun in parsecs.

CenterOf – used to replace procedural supermassive black hole system in a center of galaxy or globular cluster. The parameter’s value is a name of the galaxy or cluster, for example CenterOf “Milky Way”. Only one supermassive black hole system can exist in a galaxy or cluster, if it is already defined in some catalog, it will be replaced/updated with this one. If this parameter is defined, procedural supermassive black hole system in the corresponding object will be disabled, but this one will be rendered as a usual star system. So RA, Dec and Dist parameters are still required. Typical system must contain the black hole, optional accretion disk and many stars orbiting it. All these must be described in the planets catalog, the star catalog only have coordinates of the system and it’s class (Class “X” or Class “BLACKHOLE”).

NoPlanets – disable generation of procedural planets, if specified as NoPlanets true.

Lum, Luminosity, AppMagn, AbsMagn – allows either of these options, or combination of them (see “star solver” below for details):
Lum, Luminosity – star’s luminosity in the units of Sun’s luminosity, or
AppMagn – star’s visual (optical) magnitude, or
AbsMagn – star’s absolute (optical) magnitude.
Advanced: AppMagnR, AppMagnr, AppMagnI, AppMagni, AppMagnJ, AppMagnH, AppMagnKs, AppMagnK, AppMagnW1, AppMagnW2, AppMagnW3 – star’s visual magnitude in corresponding spectroscopic bands. Use these only for brown dwarves, if their visual magnitude in optical band is unknown. SpaceEngine performs simple computation of the optical visual magnitude assuming what star is a brown dwarf or late M dwarf. Don’t use these parameters for other types of stars.

Class – a string with the spectral class of the star:
Normal star classes: O, B, A, F, G, K, M
Subdwarf classes: sdO, sdB, sdA, sdF, sdG, sdK, sdM (or O, B, A, F, G, K, M with luminosity class VI)
Brown dwarf classes: L, T, Y
White dwarf classes: DA, DB, DO, DQ, DZ, DC, DX, DAB, DAO, DAZ, DBZ or WD (general white dwarf class)
Wolf-Rayet classes: WN, WN/C, WC, WO
Zirconium and carbon classes: MS, S, SC, C-R, C-N, C-J, C-H, C-Hd, C, R, N
Special classes: Q, NEUTRON – neutron star, X, BLACKHOLE – black hole, Z, WORMHOLE – wormhole, P – planemo (rogue planet)
All classes listed above can have the subclass index – number 0 to 9 in decimal format (0 to 11 for Wolf-Rayet stars). SpaceEngine uses only up to one decimal, i.e. 3.25 will be rounded to 3.2.
All classes except white dwarfs can have the luminosity class index: 0, Ia0, Ia+, Ia, Iab, Ib, II, III, IV, V, VI
Examples: Class “G2V”, Class “M5.2III”, Class “DB3.1”, Class “sdB5” (equal to Class “B5VI”).
Space is also allowed: Class “G2 V”, Class “M5.2 III”, Class “DB 3.1”.
Subclass or luminosity index could not be provided: Class “G2”, Class “M III”, Class “K”. In this case SpaceEngine will try to calculate them based on available data (luminosity or visual magnitude and distance etc, see star solver), or assign default luminosity class “V” (the Main sequence star).

Mass – star mass in units of Earth’s masses, or
MassSol – star mass in units of Sun’s masses. Have sense only for solitary stars (tag Star). If defined in the StarBarycenter tag, it can be used in the star solver (see below).

Radius – star radius in kilometers, or
RadSol, RadiusSol – star radius in units of Sun’s radii. Have sense only for solitary stars (tag Star). If defined in the StarBarycenter tag, it can be used in the star solver (see below).

Teff, Temperature – temperature of the star’s photosphere (“surface”) in Kelvins. Have sense only for solitary stars (tag Star). If defined in the StarBarycenter tag, it can be used in the star solver (see below).

FeH – star metalicity. Not used for now, but can be used in future, so it’s worth to add it in the catalog if information is available.

You can use the star solver logging to detect some errors in the stars catalog (for details see Star solver and Checking for errors in the Introduction to SE scripts).

The planets catalog

Lets continue creating our example addon. The star “Mono” don’t need anything to be described in the planets catalog, all needed information was provided in the stars catalog. It must have the black hole “Hole” and binary components of the system “Bin”: “Bin A” and “Bin B”. Go to the addons/catalogs/planets/ directory (create it if not exist) and create a new text document there. Rename it to myplans.sc (as has been noted in “the star catalog” section, the file name doesn’t matter, but make sure it doesn’t match some existing file, otherwise you file will override it). Open it in the notepad and type this code:

Code

// Create a new object – a solitary black hole with an accretion disk
Star    “Hole”
{

ParentBody “Hole system” // = name of StarBarycenter in the stars catalog
Class           “X”     // black hole “spectral class”
MassSol         15.0    // in solar units, radius will be computed automatically
//Lum           0.0     // black hole itself have zero luminosity – simply don’t specify it    // rotational parameters
Obliquity       16
EqAscNode       64
RotationPeriod  1.0e-7  // black holes rotating really fast!// accretion disk
AccretionDisk
{

Radius      0.00002 // in AU
Temperature 3000    // in Kelvins
Luminosity  150     // in Solar luminosities
Brightness  1       // render brightness scale
Density     8       // some magic value
TwistMagn   60      // some magic value

}

// Orbit tag is skipped, equal to static position in the center of the system

}

// Create a new object – first component of a binary star system
Star    “Bin A”
{

ParentBody      “Bin”   // = name of StarBarycenter in the stars catalog
Class           “G1V”
Luminosity      1.02
MassSol         1.09
RadiusSol       1.1

// rotational parameters
Obliquity       82.2
EqAscendNode    67.726
RotationPeriod  923.6
RotationOffset  64.7

// orbit around the barycenter
Orbit
{

// mutual semimajor axis is 23.52 AU,
// but mass ratio 1.09:0.92 is taken into account!
SemiMajorAxis   10.765 // in AU
Period          79.914 // in years
Eccentricity    0.5179
Inclination     82.986
AscendingNode   67.726
ArgOfPericenter 3.772
MeanAnomaly     200.119

}

}

// Create a new object – second component of a binary star system
Star    “Bin B”
{

ParentBody      “Bin”   // = name of StarBarycenter in the stars catalog
Class           “K0V”
Luminosity      0.29
MassSol         0.92
RadSol          0.90

// rotational parameters
Obliquity       82.6
EqAscendNode    67.726
RotationPeriod  850.5
RotationOffset  127.4

// orbit around the barycenter
Orbit
{

// mutual semimajor axis is 23.52 AU,
// but mass ratio 1.09:0.92 is taken into account!
SemiMajorAxis   12.755 // in AU
Period          79.914 // in years
Eccentricity    0.5179
Inclination     82.986
AscendingNode   67.726
ArgOfPericenter 183.772
MeanAnomaly     200.119

}

}

Lets take a closer look on this script. It is called “planets catalog” because it is designed for making a planets and moons in the first place. But “star body” itself, especially in binary systems, also should be described here. It’s a common rule: any object that have an orbit must be described in the planets catalog. Components of a binary star do have orbits, so this is why they should be in the planets catalog. It also allows to describe much more parameters than stars catalog (rotation axis orientation and rotation period, star corona, accretion disk, surface textures, and orbit), this is why even solitary stars such as the Sun also may be described in the planets catalog. To learn more about parameters used in the planets catalog, and about creating a planet, read the Creating a planet guide.

In the example code above, we first described the solitary star “Hole” with additional parameters which cannot be described in the stars catalog (rotational parameters and accretion disk). To specify them, it’s necessary to describe the star in the stars catalog as a StarBarycenter, despite on the star is solitary, and make a second description for it in the planets catalog with the tag Star. The ParentBody parameter in that Star tag must be set to the name of the StarBarycenter which you have described in the stars catalog. Important notice: the Star tag in the planets catalog and the StarBarycenter tag in the stars catalog must have different names. I.e. if the star have a name “Hole”, then the barycenter should have a name “Hole system” or “Hole bar” or something like that. When creating an addon with some real star, which have multiple designations in the astronomical catalogs, it’s a good practice to give one to the StarBarycenter, and the rest ones to the Star.

The planets catalog also allow to specify star’s luminosity, absolute or apparent magnitude, spectral class, mass, radius and temperature – the same parameters as in the stars catalog. It’s up to you where to specify these parameters: in the stars catalog or in the planets catalog, duplication in both is not necessary.

The Orbit tag must be skipped for solitary star, SpaceEngine will generate a static position in the center of the system for that star. You may use Orbit { Type “Static” } or StaticPosXYZ (0 0 0) with the same effect, but this is not necessary.

The barycenter is also could be used to create a binary and multiple stars. In the planets catalog, we have described two stars “Bin A” and “Bin B” with their orbits around the main barycenter of the system “Bin” (see description of the Orbit tag in the Creating a planet guide for details). To create a hierarchical multiple star system, create a secondary barycenter (using the Barycenter tag in the planet catalog script), which orbits the main barycenter of the system, then add two stars which are orbiting this secondary barycenter. You may repeat this scheme many times to create more complex systems. SpaceEngine unlimited hierarchy of objects, but in reality, star systems have no more than 3-4 levels of hierarchy.

The planets for each star or local barycenter could also be specified in the planets catalog. The parameter ParentBody for each planet/barycenter/star should be set to the name of the parent object which it is orbiting. If the star is solitary, and planets catalog does not have any children object (planet) for that star described, SpaceEngine will generate procedural planetary system. You can disable this by specifying NoPlanets true in the stars script.

The parameters of a star/barycenter in the star catalog determines the appearance of a star while looking from the interstellar space, i.e. when it is rendered as a point. For multiple star system, SpaceEngine needs some “average” spectral class to render the system from far away. For procedural systems, SpaceEngine chooses the spectral class of the most bright star of the system (see “star solver” for details). This is working very well in most cases, because luminosities of stars are differ by many orders of magnitude. So when creating a multiple star system, you can specify the same spectral class for StarBarycenter (in the stars catalog) as the class of the most bright star in that system. Otherwise SpaceEngine will do that automatically. The luminosity of the StarBarycenter should be equal to the summary luminosity of all stars in the system (including luminosity of the accretion disks), or ignored to force star solver to automatically calculate it.

Please pay attention to these features, otherwise the code will not work or will work incorrectly:

1) In the stars catalog, describe a star with the StarBarycenter, if you want to specify the custom rotation parameters, accretion disk etc, or if you creating a multiple star system. In that case you also must create a planets catalog and describe the star or multiple star components there. If you need only mass, radius and temperature for your star, or if you okay with those values generated/computed by SpaceEngine, describe it with the Star tag, and do not create a planets catalog.
2) The name of a star in the planets catalog must not be the same as the name of StarBarycenter. The name of StarBarycenter must be specified as the parent of the star in it’s ParentBody parameter.
3) If the star is solitary, do not use the Orbit tag for it, or make its orbit static (Orbit { Type “Static” } or StaticPosXYZ (0 0 0)), so it coincides with the barycenter.
4) If the star is binary, describe the two stars with name of the StarBarycenter in their ParentBody parameter, and make proper orbits around the barycenter for them.

You can use the star solver logging to detect some errors in the planets catalog, as well as for the stars catalog (for details see Star solver and Checking for errors in the Introduction to SE scripts)

The star solver

The star solver is a code what tries to compute or generate missing data for a star based on the provided data. It’s often situation in astronomy when some data is provided in catalogs, but some does not. SpaceEngine requires at these parameters to correctly render a star (star system):

– Full 3D coordinates of a star (RA, Dec, Dist). If the star catalog does not provide distance, star solver may try to compute it based on apparent and absolute magnitude (or luminosity) of a star. If RA and Dec are not provided, star solver will generate random values for them, because there is no way to calculate them. Random value for distance is also generated if star solver failed to compute it (see about error logging below).

– Star’s spectral class. Without it, SpaceEngine will have no idea what this star is, and cannot render it. Star solver can try to determine the spectral class by looking at radius, mass and temperature, if they are provided. For the multiple star system, star solver takes the spectral class of the most bright component (either computed or taken from the planets catalog), and assigns it as the “class” of the whole system (if it was not specified in the StarBarycenter tag directly).

– Star’s brightness. It can be computed from luminosity, absolute magnitude or visual magnitude and distance. If neither are provided, spectral class can be used to roughly determine the luminosity. If even spectral class is not provided, star solver may try to use radius and temperature to calculate luminosity using the Stefan–Boltzmann equation. For the multiple star system, star solver sums up the luminosity of each component, and assigns it as the luminosity of the whole system (if it was not specified in the StarBarycenter tag directly).

– Star’s physical properties: mass, radius and temperature. If not provided, star solver will compute them based on spectral class (typically). Temperature can be derived from the spectral class directly, then radius is computed based on temperature and luminosity using the Stefan–Boltzmann equation. So if you run into incorrect or unrealistic size of a star, try to find it’s real radius data and specify it in the catalog.

As has been noted, the star catalog cannot be used to define rotational parameters of a star (i.e. rotation period, axial tilt and oblateness), as well as surface appearance (granulation cells size, etc), corona, accretion disk and orbit: the planets catalog is used for this. Some parameters can be generated procedurally if missing in the planets catalog. The planets are also can be described in the planets catalog or generated procedurally (if the planets catalog does not have any children objects for the star described, and the star script does not have NoPlanets true specified).

The star solver can write notifications about performed calculations, warnings and errors to the log file system/se.log at SpaceEngine startup. See Introduction to SE scripts for details about error checking in scripts.

The csv format for the star catalog

SpaceEngine supports the csv (“Comma-Separated Values”) format for massive stars and galaxies catalogs. It is a plain text format with one star described per line, with values separated with comma. Default SpaceEngine installation have one csv star catalog – data/catalogs/Catalogs0980.pak/stars/HIPPARCOS.csv, which have 112,523 stars, and have a size (unpacked) of only 7.5 MB. The csv format is more compact than sc, but have some limitation:
1) Only solitary stars can be described, analog of the StarBarycenter tag is impossible.
2) Only these parameters are allowed: Name, RA, Dec, Dist, AppMagn, SpecClass, MassSol, RadSol, Temperature.

The file format is simple: the first line is header describing the names of parameters (separated by comma), the rest lines are stars data – values of corresponding parameters (also separated by comma). Here is the example of the first 4 lines of the HIPPARCOS.csv file:

Code
Name,RA,Dec,Dist,AppMagn,SpecClass,MassSol,RadSol,Temperature
HIP 14066/HD 18665,3.02094205,36.1179219,487.804884,7.24999999,K2V,,,
HIP 14775/HD 278329,3.17876994,36.5130485,505.050497,10.1093756,K0V,,,
HIP 12888,2.76132567,32.8238759,476.190497,9.64843834,K0V,,,

Note what star name and its spectral class does not enclosed in quotes, and missing parameters (MassSol, RadSol and Temperature) are just blank, but commas separated them are still necessary.

The csv catalogs have a priority over sc catalogs, i.e. they are loaded first. But then star solver takes the file/pak modification date to perform star data merging or updating. The config-file parameter CsvLogLevel in the config/main-user.cfg file controls the star solver’s logging level for all the csv files.