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

Galaxies, star clusters and nebulae have a similar format of catalog file. They are stored in the virtual folders */catalogs/galaxies/, */catalogs/clusters/ and */catalogs/nebuale/, respectively. To add a new object, create the sc file in the needed subfolder in the addons folder, and type the script in it (see below). You can add multiple object scripts to the sc file.

You can also create a custom 3D model for galaxy or nebula. Otherwise SpaceEngine will use one of the standard models, assigning it to your object based on its type. You can make a custom model and assign it to a specific galaxy/nebula, or tell SE to assign it procedurally to all galaxies/nebulae which have a certain type (for example, "Sa" galaxies). You can also modify the standard models.

Note: the current version of SpaceEngine does not support procedural generation of galaxies and nebulae, therefore all galaxies/nebulae uses one of the standard models. If you add new models to the types of galaxies/nebulae, some fraction of these objects in SpaceEngine will use your models.

The majority of galaxies in the default SpaceEngine installation are stored in the csv file data/catalogs/Catalogs0980.pak/galaxies/NGC-IC.csv. This is the NGC/IC galaxy catalog with about 10,000 galaxies. Some other galaxies are stored in few 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 galaxy, remove it, or add a new one, create your own sc or csv file in the addons/catalogs/galaxies/ folder. SpaceEngine has scripting options to modify and remove objects from the default catalogs, or to add new ones.

The csv format for a catalogs is designed to create a large list 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 any possible data that SE can use to describe an object. It is a script-like text with 'tags' used to describe an object and its various parameters. First we'll describe the sc file format.

The galaxy/cluster/nebula catalogs

Galaxies, star clusters and nebulae have very of catalog file formats. They differ only by location on the disk, main tag name, and a few parameters specific for only some types of object.

Let's consider you want to create a new galaxy called "MyGalaxy". Go to the addons/catalogs/galaxies/ directory (create it if it does not exist) and create a new text document there. Rename it to mygalaxy.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:

In the galaxy catalog, you can use only these two tags to add a new object or modify the old one:
Galaxy "name" { } - to add/modify a galaxy,
Quasar "name" { } - to add/modify a quasar.
Note that in the current version of SpaceEngine quasars do not differ from regular galaxies (except designation in the interface).

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

Star clusters can be added/modified by the same way. Go to the addons/catalogs/clusters/ directory (create it if it does not exist) and create a new text document there. Rename it to mycluster.sc (the file name doesn't matter). Open it in Notepad and type this code:

And nebulas can also be added/modified by the same way. Go to the addons/catalogs/nebulae/ directory (create it if it does not exist) and create a new text document there. Rename it to mynebula.sc (the file name doesn't matter). Open it in Notepad and type this code:

You can also remove the previously defined galaxy/quasar/cluster/nebula (i.e. object defined in some older catalog files). Use this parameter in the corresponding sc file (i.e. in the galaxy catalog to remove a galaxy, and so on):
Remove "name" - delete a previously defined object.

The galaxy/cluster/nebula script details

Here we will describe all the parameters which can be used in scripts for galaxies, star clusters and nebulae. They are very similar, though some parameters are allowed only for certain types of object. Also keep in mind that you must describe a galaxy in a galaxy catalog, it is not allowed in the nebula or star cluster catalog. And so on for nebulas and star clusters. This has been noted in the Introduction to SE scripts:

Galaxy catalogs */catalogs/galaxies/*.sc can have only Galaxy and Quasar tags;
Star cluster catalogs */catalogs/clusters/*.sc can have only Cluster tags;
Nebula catalogs */catalogs/nebuale/*.sc can have only Nebula tags.

Parameters, common for all catalogs

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.
The parameters RA, Dec and Dist can be adjusted in SE in the Edit mode (see below).

Yaw, Pitch, Roll - the Euler angles of orientation of the object, or
Axis - the orientation of the object in the axis-angle format, or
Quat - the orientation quaternion of the object.
The orientation parameters can be adjusted in SE in Edit mode (see below). If they are not specified, they are generated procedurally.

Lum, Luminosity - luminosity of the object in units of Sun's luminosity, or
AppMagn - apparent (optical) magnitude of the object, or
AbsMagn - absolute (optical) magnitude of the object.

Radius - radius of the object in parsecs.

Type - the morphological type of the object.
In the galaxy catalog it is the Hubble morphological type of a galaxy. Allowed types are:
"E0", "E1", "E2", "E3", "E4", "E5", "E6", "E7" - elliptical galaxies;
"S0" - lenticular galaxies;
"Sa", "Sb", "Sc", "Sd" - spiral galaxies;
"SBa", "SBb", "SBc", "SBd" - barred spiral galaxies;
"Irr" - irregular galaxies.
In the nebula catalog, allowed types are:
"Diffuse" - diffuse nebula;
"Planetary" - planetary nebula;
"SNR" - supernova remnant.
In the star cluster catalog, allowed types are:
"Globular" - globular cluster;
"Open" - open cluster;
"Kern" - the galactic center cluster (special type, used to represent the galaxy center);
"Part" - part of the galaxy (special type with no stars, used to represent a star clouds like M 24 - the Sagittarius Star Cloud).

Parameters, used only in the galaxy catalog

ModelBright - the overall brightness of the galaxy 3D model. Default value is 1.

SolFade true - if specified, generation of procedural objects (stars, star clusters and nebulae) near the Sun will be suppressed. So while looking from the Solar system, there are no visible procedural objects brighter than magnitude 8.1. This is done to prevent change of appearance of real constellations while looking look from the Solar system. The limiting magnitudes for this can be adjusted by the parameters StarMaxAppMagn, ClusterMaxAppMagn and NebulaMaxAppMagn in the config/main-user.cfg file.

Parameters, used only in the star cluster catalog

Galaxy - name of the galaxy to which this star cluster belongs. Example: Galaxy "Milky Way". This galaxy must exist in SE.

Age - age of the star cluster in millions of years. Affects the generation of procedural stars (younger clusters have more blue stars, older ones have more red giants).

CenPow - the parameter which defines the amount of "clustering" of stars in the center of the cluster. Larger value (>1) makes more concentrated clusters, lower value (<1) makes more fuzzy clusters.

NStars - number of stars in cluster, allowed only for open clusters. To disable procedural stars, specify zero: NStars 0 (used for Pleiades and other clusters which already have a stars in the star catalog). While generating an open cluster model, SpaceEngine sums up the luminosity of generated stars and stops generation when this sum reaches the luminosity of the cluster. So the actual number of stars may be lower than specified by NStars.

Color - the RGB vector of the color of the particle that is rendered instead of the cluster model when camera is far away. To disable this particle, set it to black: Color ( 0 0 0 ) (useful for large or very close clusters). If not specified, will be generated procedurally.

Parameters, used only in the nebula catalog

Galaxy - name of the galaxy to which this nebula belongs. Example: Galaxy "Milky Way". This galaxy must exist in SE.

Using the Edit mode

The coordinates, orientation and size of the object can be adjusted in SpaceEngine using the Edit mode. To enter the Edit mode, press the [*] button twice. The prompt table will appear in the bottom left of the screen. Using the keystrokes listed in it, you can adjust the parameters of the selected object. The values of RA, Dec, distance, radius and orientation (Axis and Quat) are displayed in the object's information table at the top left side of the screen (don't forgot to switch distance unit to parsecs in the Player settings menu).

To accurately adjust the visual position and orientation of the object with respect to real stars (using actual photos from telescopes as reference), do the adjusting while looking from the Solar System. Go to the Sun, center the camera view on the object, and use a telescope (Shift + Left mouse drag) to zoom in on it.

Note: changes are not saved to the script file. You must type them manually.

The csv format for a galaxy catalog

SpaceEngine supports the csv ("Comma-Separated Values") format for massive star and galaxy catalogs. It is a plain text format with one galaxy described per line, with values separated with commas. The default SpaceEngine installation has one csv galaxy catalog - data/catalogs/Catalogs0980.pak/galaxies/NGC-IC.csv, which has 10,896 galaxies, and a size (unpacked) of only 1.3 MB. The csv format is more compact than sc, but has some limitations:
1) Only galaxies can be described, quasars are not allowed.
2) Only these parameters are allowed: Name, Type, RA, Dec, Dist, AbsMagn, Radius, Quat.

The file format is simple: the first line is a header with the names of the parameters (separated by commas), the remaining lines are galaxies with their data - values of corresponding parameters (also separated by commas). Here is an example of the first 4 lines of the NGC-IC.csv file:

Note that the galaxy name and its Hubble type are not enclosed in quotes. Missing data for some parameters is allowed: just leave these parameters blank, but commas separating them is still necessary (like this: ,,).

The csv catalogs have a priority over sc catalogs, i.e. they are loaded first. But then the 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.

Creating a custom 3D model for a galaxy or nebula

The current version of SpaceEngine (0.9.8.0) uses sprites to render 3D models of galaxies and nebulae. They are very similar in format, thus their scripts are also very similar. There are many methods of creating models in SE, but they are all focussed on creating a 3D distribution of sprites with various sizes and colors. The user can control its shape and color by providing textures (image files) and specifying how to use them to create a 3D sprite model. Spiral galaxies can also use high-resolution disk textures to enhance the rendering quality when the galaxy is observed from the top. The methods provided by SE are:

• Elliptical galaxies: use a special ray-tracing shader, so they do not need 3D models.
• Spiral and lenticular galaxies: the "galaxy" method. Require a high-resolution RGBA texture of the disk with dust patterns in the alpha channel, it's reduced version (128x128), and a high-resolution RGB texture which maps the distribution of blue stars, open star clusters and nebulae in the disk.
• Irregular galaxies and nebulae: various texture projection methods. Require one to six RGBA textures, which represents view of the model from different sides (front, top, left and so on). Various applying methods are possible (cubic, cylindrical etc). Used to simulate real shapes of irregular galaxies and any type of nebula.
• Irregular galaxies and nebulae: fully procedural fractal-based generation of a sprite distribution. Used for procedural irregular galaxy and any type of nebula.

To describe a galaxy/nebula model, we need these frontal/projection textures, and a model script. Textures for galaxies are stored in the virtual folder */textures/galaxies/, and for nebulae in the */textures/nebulae/. The model script is a file with extension *.cfg, located in the */models/galaxies/ or */models/nebulae/ for galaxies and nebulae, respectively.

To add a new galaxy model, go to the addons/models/galaxies/ folder and create a new text document there. Rename it to mymodel.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:

The nebula model can be described in the same way. Go to the addons/models/nebulae/ folder and create a new text document there. Rename it to mymodel.sc (the file name doesn't matter), open it in Notepad and type this code:

Keep in mind that you must describe a galaxy model in the cfg file which is located in the */models/galaxies/ folder, and a nebulae model - in the cfg file located in the */models/nebulae/ folder. Only these tags are allowed in the corresponding cfg files:

GalaxyModel "name" { } - add/modify a galaxy model in the galaxy model script,
NebulaModel "name" { } - add/modify a nebula model in the nebula model script.

Multiple model tags are allowed in the a single cfg file, as well as for SpaceEngine catalogs of astronomical objects. If there are two descriptions of the same model found in the cfg files (tags with the same name, for example, GalaxyModel "MilkyWay"), SpaceEngine will update the older script with the data found in the newer one. So you can modify an existing model by making a new cfg script with the description of that model. Note: you must delete the binary file of the corresponding model from the cache to apply the update (see below).

The galaxy/nebula model script details

Here we will describe all parameters which can be used in model scripts for galaxies and nebulae. They are very similar, though some parameters are allowed only for certain types of object.

UseForObject - specifies which particular object this model must be used with.
UseForType - specifies which types of objects (procedural or catalog with no model) this model must be used with.
So you may choose one from 3 types of behaviour:
1) Model is used only for a galaxy/nebula, whose name is specified in the UseForObject parameter. The UseForType parameter is not present. This method is useful for some peculiar galaxies like LMC or Hoag's object, whose models you don't want used for other procedural galaxies/nebulae.
2) Model is procedurally assigned for galaxies/nebulae which have no custom models, but have a type, specified in the UseForType parameter. The UseForObject parameter is not present. For example, if there are many models with UseForType "SBa", then all galaxies of "SBa" type will use randomly one of these models. This method is useful for "random" models, made from art textures, rather than real photographs.
3) Model is used for a galaxy/nebula, whose name is specified in the UseForObject parameter, and also procedurally assigned for a galaxies/nebulae which have a type specified in the UseForType parameter.
You must specify at least one of both parameters: UseForObject and/or UseForType.

Method - the method of generating the three-dimensional distribution of sprites of the model. Valid values are:
"Cylindrical" - a cylindrical distribution: the side texture sets the density along the radius ® and height (Z), the front texture gives the density in the XY plane. Example: models of the LMC and SMC galaxies.
"Spherical" - a spherical distribution: the front texture rotates around the Y axis, and thus sets the density of the sprites. Example: model of the Owl Nebula.
"Flat" - a flat layer of sprites, the density is defined by the front texture.
"EllipticGalaxy" - elliptical distribution of sprites, textures are not used. Note that elliptical galaxies in SE uses a custom ray-tracing shader, so the sprite model is not needed for them.
"SpiralGalaxy" - a spiral galaxy, cylindrical method for the disc is used, and elliptical distribution for the bulge is used. Example: almost any model of spiral and lenticular galaxy.
"CubeMap" - the density distribution is defined by the six textures CubePosXImage ... CubePosZImage. These textures describe the projection of a model onto 6 faces of a cube circumscribing the model. The sprite density and colors are obtained by cubic interpolation between these face textures. If some pos/neg image is not provided, the corresponding neg/pos image will be used (so at least 3 images must be provided). Example: models of the Carina nebula, Horsehead nebula.
"Diffuse" - a procedural cloud-like distribution, no textures are needed. Example: standard models for procedural diffuse nebulae "Diff0", "Diff1".
"Planetary" - a procedural spherical-shaped distribution. Example: standard models for procedural planetary nebulae "Plan0", "Plan1".
"SNR" - a procedural spherical-shaped distribution with thinner walls. Example: standard models for procedural planetary nebulae "SNR0", "SNR1".

Position, Radius, BulgeRadius - shifts and zooms the sprite model and its parts.

floatLOD, LODbase - sprite model LOD settings.

FrontTexture - the front texture of the galaxy. Rendered as a transparent textured square in the plane of the galactic disk, superimposed on the sprite model. It must have a dust pattern in the alpha channel (see Creating textures). RGB channels determine the distribution and color of the emission sprites, and the alpha channel - the distribution of the dust sprites.

SysTexture - the texture of the subsystems of the galaxy, used to generate procedural objects in the galaxy. R, G and B channels define the distribution of nebulae, open star clusters and blue stars, respectively.

FrontImage, SideImage - textures of the galaxy/nebula in the frontal and lateral projections, used in the "Cylindrical" and "SpiralGalaxy" methods. For galaxies, the FrontImage must be reduced to a 128x128 copy of the FrontTexture, also with the dust pattern in the alpha channel. The SideImage may be one of the following default side images, or the custom one:
S0_side.png, Sa_side.png, Sb_side.png, Sc_side.png, SBa_side.png, SBb_side.png, SBc_side.png
RGB channels determine the distribution and color of the emission sprites, and the alpha channel - the distribution of the dust sprites.

CubePosXImage, CubePosYImage, CubePosZImage, CubeNegXImage, CubeNegYImage, CubeNegZImage - textures of a galaxy/nebula as viewed from 6 sides of a circumscribing cube. Used in the "CubeMap" method. RGB channels determine the distribution and color of the emission sprites, and the alpha channel - the distribution of the dust sprites.

sumColor, clipRadius - these parameters are automatically updated by SpaceEngine when creating or updating the model. Used for nebulae. When you create a new model, it is necessary to add these parameters to the script, with any numbers as the initial values, for example:
sumColor (1 1 1) - overall color of the model,
clipRadius 1 - radius of the bounding sphere;

Note: all of the following parameters have the same meaning for the sprites of the star disk of the galaxy or emission sprites of the nebula (prefix em), the dust sprites (prefix abs) and the galaxy bulge sprites (prefix b). For brevity, we will describe only the parameters for the emission sprites.

emParticleColor - the color of the sprites, modulates the color of the pixels in the textures. For the absorption (dust) sprites, values are amount of light absorption in the given channel. Good values are absParticleColor (0.0 0.3 0.5). This means (roughly) that the sprite absorbs 50% of the passing light in the blue channel, 30% in the green channel, and 0% in the red channel.

emDetailR, emDetailZ - level of detail of the sprite model along the radius and the Z axis:
2.0 - 128 sprites,
1.0 - 64 sprites,
0.5 - 32 sprites, etc.
Note: setting a large number may hit the rendering performance very hard!

emParticleDispR, emParticleDispZ - the magnitude of the random offset of a sprite from a rectangular grid, in the radial and the Z-axis directions:
1.0 - the width of the cell,
0.5 - half the width of the cell,
0.0 - no offset, etc.
Used to reduce the grid effect on the sprite model.

emParticleSizeCenter, emParticleSizeEdge - sprite size at the center and the edge of the model:
1.0 - sprite diameter is equal to the width of the cell,
2.0 - sprite diameter is 2 times greater than the width of the cell, etc.
The size of sprites interpolates linearly from the center to the edge.

emParticleMinBrightCenter, emParticleMinBrightEdge - the minimum brightness of the generated sprite to include it to the model (at the center and the edge of the model). Interpolates linearly from the center to the edge. If the value in the density map that was built using textures or procedural noise is less than this value, then the sprite in this cell is skipped. Used for optimization of the model - very dark and black (invisible) sprites are excluded.

emParticleBrightnessCenter, emParticleBrightnessEdge - sprite brightness at the center and the edge of the model. Interpolates linearly from the center to the edge.

emNoiseRandomize ... emNoiseOffset - parameters of the noise function (Distorted fBm), which is used in the "Diffuse" method of generation (irregular galaxies and nebulae):
emNoiseRandomize - seed for the generator,
emNoiseFreq - noise frequency,
emNoiseOctaves - number of noise octaves,
emNoiseDistort - amplitude of the distortion,
emNoiseLacunarity - lacunarity (heterogeneity),
emNoiseH - the parameter H,
emNoiseOffset - the shift.

Updating the model in the runtime

When first approaching the created galaxy, SpaceEngine creates a sprite model, using data from the model script and textures specified in it. The generated model is saved in a special binary format to the cache folder cache/models/galaxies/*.gm (for galaxies) or cache/models/nebulae/*.nm (for nebulae) and a name that matches the name of the model tag. The next time you load SpaceEngine, it will load the binary file from the cache, instead of generating the model again, which is much faster. If you remove the model file from the cache, it will be generated again using scripts and textures.

You can change the script and textures of the model while running SpaceEngine, and update the model on-the-fly. To do this, you should select the galaxy or nebula you wish to edit, switch to the Edit mode (press the [*] key twice), and press [Ctrl]-[Shift]-[F5]. The model of the currently selected galaxy or nebula will be updated and saved to the cache.

If there is any error while generating or updating the model and the galaxy/nebula disappears in SpaceEngine, you will need to remove the model from the cache manually and restart SpaceEngine.

Creating textures

Lets take as an example the textures of the M 51 galaxy. It is made based on the Hubble photo of this galaxy (similar to this). Here is a description of steps needed to make a good textures for SpaceEngine from this photo. Textures for nebulae can be made in similar way.

1) The first step is cropping, centering and resizing of the image to nearest power-of-two dimensions. Make it a square with a side of 512, 1024, 2048, 4096 pixels. The higher the resolution, the better. The limit is 4096. Make the texture so that the galaxy is almost fully filled by it. There should be a minimum of unused space around the edges, and the center of the texture should coincide with the center of the galaxy. If the galaxy is seen in the photo slightly at an angle, stretch the image so that it becomes circular (if it is known that it does not feature the actual shape of the galaxy).

2) The next step is removing of the background stars (which this image almost doesn't have, luckily). In Photoshop, one tool for removing stars is Filter -> Noise -> Dust & Scratches. Another possible way is to copy the original texture layer twice, blur the top layer (Filter -> Gauss blur, or Box blur), and use a Difference blending mode for second layer. This isolates small details - the stars. Then merge the top two layers and set a Difference blending mode for the merged layer. This cases the small details to be subtracted from the lower (original) layer. Then use the tool Image -> Adjustments -> Levels to pick up the black level of the upper layer to a more precise subtraction of the stars. The brightest stars should be removed manually by copying the neighboring areas of the image (eg. with the Clone Stamp Tool). There is some noise left after removing the stars, and it must be smoothed out in some way, for example by walking through the image with a Blur tool, leaving the dust/nebula details where they should be, but smoothing out the noise from removed stars.

3) Increase the contrast of the image, and attenuate (fade) the edges. It must completely fade to black at the edges, otherwise edges will be very noticeable in SpaceEngine. Here is the example of what you must achieve (click to enlarge):

4) The next step is selecting the interstellar dust pattern. Dust is brown streaks visible on the galaxy's spiral arms. Near the center you can see how they gradually disappears into a yellow "fog" - the spherical bulge of the galaxy. Select the dust like you selected the stars, or use the tool Select -> Color Range. Create an alpha channel and copy the selected dust there. Bright areas in the alpha channel must outline the dust in the galaxy, so you may need to invert the image. Here is the example of what you must achieve in the alpha channel (click to enlarge):

5) Create a small version of this texture i.e. just a reduced 128 x 128 copy of the front texture. It is used as "LOD 0" texture if the galaxy is far away, and also for generating the 3D sprite model. Note: Photoshop likes to add a thin gray frame around the image while rescaling. So make sure you have removed it with the eraser tool or another method. Look at the small texture example below: its alpha channel has a noticeable frame. If not removed, these gray pixels may lead to generating redundant sprites in the 3D model.

6) Now it's time to create a subsystems texture. Create a new document (image) with the same dimensions as the edited (big) front texture. Then copy the RGB image of the front texture into that new document. The subsystems texture is a pattern which is used to generate procedural diffuse nebulae (the red channel), open star clusters (green channel) and the young blue stars (blue channel). So it can easily be made by adjusting the levels/contrast in each of the color channels separately. You also need to erase the galaxy core - there must be no nebulae, star clusters, or blue giants generated. You can use the hand tools Burn and Dodge to enhance star forming regions (in the blue channel) and nebulae (in the red channel). If galaxy image has no very well defined nebulae, you can copy the dust distribution map to the red channel and (nebulae appear near dust clouds). Here is an example of what you must achieve (click to enlarge):

7) Save the files. It is recommended to save the front texture and its small version into alpha-PNG format. Note: Photoshop can't save PNG with the alpha channel, so it is better to save the texture in TGA format, and then convert it to PNG using SpaceEngine. It has an option for converting any texture to any supported format, correctly saving the alpha channel. To use it, run SpaceEngine, open the console with [~] key and type:
SavePNG addons/textures/galaxies/MyGalaxy.tga
where MyGalaxy.tga is the file name of the texture you want to convert. This command loads the texture MyGalaxy.tga and saves it with name MyGalaxy.png, to the same folder. There are commands for converting to all other formats available: SaveJPG, SaveDDS, SaveTGA, SavePNG, SaveTIF.
The subsystems texture can be saved in any format, including JPEGб because it does not have an alpha-channel.

8) You can edit the model script and textures while running SpaceEngine, and update the model on-the-fly. To do this, select the galaxy you are editing, switch to the Edit mode (hit the [*] key twice), and press [Ctrl]-[Shift]-[F5]. The model of the galaxy that is currently selected will be updated.

Good photos of galaxies can be taken from the Hubble website. Choose the galaxies which have full coverage in the frame, using images that were taken in the visible part of the spectrum, in natural color. It is better to grab photos in TIFF format without compression so there will not be JPEG compression artifacts.