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

The majority of stars in the 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 has scripting options to modify and remove stars or other objects from the default catalogs, or to add a new ones.

The csv format for catalogs is designed to create large catalogs of objects with similar data. It is more compact and loads faster than sc, but has limits to the types of data which can be specified in it. It is just a table with values separated by commas. The sc format is designed to specify all the possible data which 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

Let's consider that 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 that stars "Bin A" and "Bin B" are described already in some catalog as 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 it does 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 your file will override it). Open it in Notepad and type this code:

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 for upgrading binary stars in the catalog that are represented in SE as two seperate stars, into a complete binary star system with each star in a correct orbit. Note: the Remove parameter seems to affect all catalog files, regardless of their modification date. It is a bug in the current version (0.9.8.0).

Note that the star catalog does not describe the components of binary or multiple star systems. 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 allow describing solitary stars without creating a planets catalogs for them). Visual parameters such as the overall luminosity of the system will be calculated by SpaceEngine automatically, based on the data of the system's components, described in the planets catalog. They may, however, be forced by defining parameters Luminosity, AppMagn etc. in the StarBarycenter tag.

The star script details

The following 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 the procedural supermassive black hole system in the center of a galaxy or globular cluster. The parameter's value is the 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, the 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. A 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 deals with the coordinates of the system and its class (Class "X" or Class "BLACKHOLE").

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

Lum, Luminosity, AppMagn, AbsMagn - allows one of these options, or combination of them (see "star solver" below for details):
Lum, Luminosity - star's luminosity in units of the Sun's luminosity, or
AppMagn - star's apparent (optical) magnitude, or
AbsMagn - star's absolute (optical) magnitude.
Advanced: AppMagnR, AppMagnr, AppMagnI, AppMagni, AppMagnJ, AppMagnH, AppMagnKs, AppMagnK, AppMagnW1, AppMagnW2, AppMagnW3 - star's apparent magnitude in corresponding spectroscopic bands. Use these only for brown dwarves, if their apparent magnitude in the optical band is unknown. SpaceEngine performs a simple computation of the optical apparent magnitude, assuming that 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 dwarves 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").
A space is also allowed: Class "G2 V", Class "M5.2 III", Class "DB 3.1".
If the 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 masses, or
MassSol - star mass in units of Solar masses. Used 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 Solar radii. Used 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 Kelvin. Used only for solitary stars (tag Star). If defined in the StarBarycenter tag, it can be used in the star solver (see below).

FeH - star metallicity. Not used for now, but will be used in future, so it's worthwhile to add it to the catalog if information is available.

You can use the star solver logging to detect 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" doesn't need anything extra to be put into 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 it does 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 your file will override it). Open it in Notepad and type this code:

Lets take a closer look at this script. It is called "planets catalog" because it is primarily designed for making planets and moons. But the "star body" itself, especially in binary systems, should also be described here. It's a common rule: any object that has 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 you to describe many more parameters than the stars catalog (rotation axis orientation and rotation period, star corona, accretion disk, surface textures, and orbit), so 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 the fact that 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 note: the Star tag in the planets catalog and the StarBarycenter tag in the stars catalog must have different names. I.e. if the star has the name "Hole", then the barycenter should be named "Hole system" or "Hole bar" or something like that. When creating an addon with some real star, which has multiple designations in the astronomical catalogs, it's a good practice to give one to the StarBarycenter, and the rest to the Star.

The planets catalog also allow you to specify the 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 stars, 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 could also be used to create 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 allows unlimited-tier 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 the planets catalog does not have any child objects (planets) for that star described, SpaceEngine will generate a 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 the star while looking at it from interstellar space, i.e. when it is rendered as a point. For multi-star systems, SpaceEngine needs some "average" spectral class to render the system from far away. For procedural systems, SpaceEngine chooses the spectral class of the brightest star of the system (see "star solver" for details). This works very well in most cases, because luminosities of stars differ by many orders of magnitude. So when creating a multiple star system, you can specify the spectral class of the StarBarycenter (in the stars catalog) as the same as class of the brightest star in that system. Otherwise SpaceEngine will do that automatically. The luminosity of the StarBarycenter should be equal to the sum luminosity of all stars in the system (including luminosity of the accretion disks), or ignored to force star solver to automatically calculate it.

To summarise, please pay attention to the following, 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 are 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 are okay with those values being 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 its ParentBody parameter.
3) If the star is solitary, either 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 the 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 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 set of code that tries to compute or generate missing data for a star based on the provided data. It's often the situation in astronomy that some data is provided in catalogs, but some is missing. SpaceEngine requires 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 a distance, the star solver may try to compute it based on the apparent and absolute magnitude (or luminosity) of the star. If RA and Dec are not provided, star solver will generate random values for them, because there is no way to calculate them. A random value for distance is also generated if the star solver failed to compute it (see error logging below for more details).

- Star's spectral class. Without it, SpaceEngine will have no idea what this star is, and cannot render it. The star solver can try to determine the spectral class by looking at the radius, mass and temperature, if they are provided. For multi-star systems, the star solver takes the spectral class of the brightest 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 apparent magnitude and distance. If none are provided, the spectral class can be used to roughly determine the luminosity. If even spectral class is not provided, the star solver may try to use radius and temperature to calculate luminosity using the Stefan–Boltzmann equation. For multi-star systems, the 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, the 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 an incorrect or unrealistic size of a star, try to find its real radius data and specify it in the catalog.

As has been noted, the star catalog cannot be used to define the 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 can also be described in the planets catalog or be generated procedurally (if the planets catalog does not have any child objects for the star described, and the star script does not have NoPlanets true specified).

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

The csv format for the star catalog

SpaceEngine supports 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 commas. The default SpaceEngine installation has one csv star catalog - data/catalogs/Catalogs0980.pak/stars/HIPPARCOS.csv, which has 112,523 stars, and has a size (unpacked) of only 7.5 MB. The csv format is more compact than sc, but has some limitations:
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 a header describing the names of the parameters (separated by commas), all the other lines are stars data - values of corresponding parameters (also separated by commas). Here is the example of the first 4 lines of the HIPPARCOS.csv file:

Note that star name and its spectral class are not enclosed in quotes, and missing parameters (MassSol, RadSol and Temperature) are just blank, but commas separating 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.