Introduction

SpaceEngine folders

SpaceEngine has two major folders with data files, which can be found in its root (installation) directory: data and addons. They are equivalent in many respects. The first contains the standard SpaceEngine files, which you should not modify. The second mirrors the internal structure of the first one, and is used for user mods and addons. It has a higher priority when searching for files at startup. This means that if you have some file in the addons folder with the same path and name as a file in the data folder, SpaceEngine will load the file from addons. This is useful for creating mods which change some of the system files (such as shaders), without actually touching the system files.

Internally, the data folder has these standard subfolders inside: catalogs, locale, models, music, scripts, shaders, sounds, textures. 'Standard' means that SpaceEngine expects to find specific data files in these subfolders, for example, music files must be in data/music/, and star catalogs must be in data/catalogs/stars/ (some of these subfolders have their own next-level standard subfolders inside).

The addons folder may also contain these standard subfolders, which would work as mirrors of the subfolders in data. This means that SpaceEngine will load data files from both data and addons as if they were a single large folder (but with higher priority for addons in case of a file name conflict, as has been described above).

The addons folder also allows the use of additional internal subfolders, for better organization of addons. These additional subfolders may have any name (which obviously cannot match the name of the standard subfolder), typically representing the name of an addon or a franchise, for example addons/StarWars/. Internally, the additional subfolder may contain standard subfolders with data files: catalogs, models, textures and so on, or it may contain pak files (see below), or it may contain a next-level additional subfolder, for example addons/StarWars/EmpireShips/. SpaceEngine allows for an unlimited amount of nested subfolders (limited by OS, typically the path length must not exceed 256 characters).

The pak files

pak files are zip archives provided for better organization and distribution of game content. For example, a large addon with thousands of files may be zipped into a single pak file and distributed in this form, which is more convenient for the user. Zip compression can also be used while creating the pak file, which is useful to save disk space and download traffic.

pak files are zip archives that include files and folders with the same structure as they have on the disk, starting from the data or addon root level (or addon/YourCustomFolder/). This means that the uppermost folder which can be zipped into a pak file is one of the standard subfolders: catalogs, models, textures and so on. SpaceEngine reads the content of all pak files at startup and uses them as a virtual file system with date priority. This leads to many consequences:

1) The pak file format

pak files are zip archives (i.e. .zip files with the extension renamed to .pak). You may associate the .pak file type with WinRar or 7zip or whatever program you use to work with archives, and open any .pak file and extract files from it. Creating a .pak file is easy too: just select needed files and folders and compress them as .zip, then rename it to .pak when finished.

2) Virtual path

You may think of a pak file as a container for files/folders. The internal folder structure inside a pak file is a continuation of the SE folder structure. This means that SE looks for files and folders on the disk and inside all pak files as if there were no pak files and all their content is extracted at the place where these pak files are. We will call this a virtual path. The path of the disk in this article will be colored green, and inside the pak file will be colored orange. For example, these three virtual paths are equal (remember that the StarWars folder is optional):
addons/StarWars/StarWarsPlanets.pak/catalogs/planets/Coruscant.sc (packed into pak file)
addons/StarWars/catalogs/planets/Coruscant.sc (unpacked on the disk)
addons/catalogs/planets/Coruscant.sc (unpacked addon content moved to the addons root - still works)

3) Priority by modification date

If there are two or more files with the same virtual path, SE will load the most recent one. It compares the modification date/time of the disk files, or those of the entire pak file. For example, consider that you have 3 files named SolarSys.sc in different places, but with the same virtual path:
data/catalogs/Catalogs0980.pak/planets/SolarSys.sc in the default pak file, pak date is 2016/08/06
data/catalogs/planets/SolarSys.sc unpacked on the disk, file date is 2016/09/01
data/catalogs/SolarSysUpdate001.pak/planets/SolarSys.sc in another pak, pak date is 2016/09/05
In this case, SpaceEngine will load the last one, because it has the most recent date. This is useful for making updates. Consider someone adding an addon with this file:
addons/SolarSystemMod.pak/catalogs/planets/SolarSys.sc pak date is 2016/08/15
In this case, SpaceEngine will load the file from this addon pak, despite its older date. This is because files in the addons folder have priority over files in the data folder. This is to prevent breaking addons after updating the default SE files. Inside the addons folder, the same file/pak modification date priority rules apply.

4) Extracting files

You may extract any file from the pak archives by opening it as a zip archive. When extracting the file, you must create all the folders contained inside the pak, so the extracted file will have the same virtual path as the packed one (use the 'extract here' option in your archiver program). For example, if you want to extract the file SolarSys.sc from the Catalogs0980.pak, you must create the folder data/catalogs/planets/ and extract that file into it so that it has this path:
data/catalogs/planets/SolarSys.sc
After this, SpaceEngine will load the extracted file, because it will have the more recent date. Now you may modify it.

5) Creating pak files

For example, consider you are making a planetary system addon which has these files:
addons/StarWars/catalogs/stars/StarWarsSystems.sc
addons/StarWars/catalogs/planets/Coruscant.sc
addons/StarWars/catalogs/planets/Tatooine.sc

When you finish creating it, testing everything, and are ready to release, go to the StarWars folder, select the catalogs folder and pack it into a zip archive. Rename that archive to StarWarsPlanets-v001.pak. The file name doesn't really matter, but it should reflect the file's content, and having a version/revision number in it is also a good idea. After that, delete the catalogs/ folder and its content (or move it to some backup place) and leave only the newly created pak file. If you did the packing correctly, your addon should work in SE as before. Your data files will have this virtual path:
addons/StarWars/StarWarsPlanets.pak/catalogs/stars/StarWarsSystems.sc
addons/StarWars/StarWarsPlanets.pak/catalogs/planets/Coruscant.sc
addons/StarWars/StarWarsPlanets.pak/catalogs/planets/Tatooine.sc
So you are ready to share the file StarWarsPlanets-v001.pak with the community. Note that it will work if it is placed in any subfolder in the addons folder (except standard subfolders of course):
addons/StarWarsPlanets-v001.pak
addons/StarWars/StarWarsPlanets-v001.pak
addons/blabla/ololo/123/StarWarsPlanets-v001.pak
You are free to put any set of data files in a single pak file. For example, you may create a full Star Wars franchise pak, which includes all planetary systems, galaxy and galaxy model, and all ship models. Note that there are some restrictions.

6) Restrictions

1) The SpaceEngine root folder cannot be used as a place for pak files. The following will not work:
SpaceEngine/StarWars.pak/data/catalogs/planets/Coruscant.sc
2) The pak file cannot contain additional subfolders, only default ones are allowed. The following will not work:
SpaceEngine/addons/StarWars.pak/StarWars/StarWarsPlanets/catalogs/planets/Coruscant.sc
3) The pak file should be less than 4GB in size. If your addon is bigger than that, split it into several smaller pak files.
4) Music and sound files in ogg format cannot be zipped into pak files.

7) Compression rate

Zip archives can be created with or without compression. SpaceEngine supports only the "Deflate" compression method. Some file types have a great compression rate (text files such as scripts and catalogs), some have a medium compression rate (binary files such as ship models .sm, .dds and uncompressed .tga images), some almost cannot be compressed (.jpg, .png, .tif images). It is a good idea to save a large set of image files (such as a planet textures addon) into an archive without compression, because it has great extracting/loading performance. Higher performance is always better than saving few megabytes of disk space. You could experiment to find better options for your addon. For example, you may save textures into a pak without compression, and scripts with models into another pak file with compression.

8) Never touch the default pak files

Just like in all other games, changing the default game resources is a bad idea. In the future, the game client will check the default files for changes and will kick you from the server if it finds that the default files have been changed. So remember these simple rules:
1) If you want to add something, create your own pak file (or simply store files in the folders, non-packed).
2) If you want to modify something, extract the file from the default pak and modify the extracted file.

SpaceEngine scripts

SpaceEngine has a special scripting language to describe astronomical objects, ships, models and configuration files, and for scenarios. Scripts are stored in files with the extensions *.sc, *.sss, *.cfg, *.se. All file formats are plain text documents, so you can edit them with notepad (or the better program Notepad++, which we recommend you download and install). Lets take a look at some of SpaceEngine's default catalog scripts. For example, look at the description of Saturn, located in the file data/catalogs/Catalogs0980.pak/planets/SolarSys.sc:

Code
Planet   "Saturn"
{

ParentBody     "Sol"
Class          "GasGiant"
Mass            95.162
Radius          60268
Oblateness      0.09796
RotationPeriod  10.65622
RotationOffset  358.922
Obliquity       28.049
EqAscendNode    169.53
Color         ( 1.000 1.000 0.850 )
Albedo          0.342
AlbedoBond      0.342
AlbedoGeom      0.47
Brightness      1.8Surface
{

// Surface map author: Bjorn Jonsson
DiffMap        "Saturn/Surface-BJ"
DiffTileSize    256
DiffTileBorder  0
DayAmbient      0
NoClouds     true

}
Atmosphere
{

Height   250  // km
Model   "Earth"
Bright   5.0
Opacity  0.2
SkyLight 0.002

Composition // values in percent
{

H2   96.3
He   3.25
CH4  0.45
NH3  0.0125
C2H6 0.0007

}

}

Aurora
{

Height       1000   // km
TopColor    (1.5 0.0 0.8)
BottomColor (1.0 0.1 0.0)
NorthLat     90    // degrees
NorthLon     0     // degrees
NorthRadius  15000 // km
NorthWidth   5000  // km
NorthRings   3     // number of rings
NorthBright  1.0
SouthLat    -90    // degrees
SouthLon     0     // degrees
SouthRadius  16000 // km
SouthWidth   5000  // km
SouthRings   3     // number of rings
SouthBright  1.0

}

Rings
{

// Rings texture author: Vladimir Romanyuk "SpaceEngineer"
Texture        "Saturn-rings.*"
InnerRadius     60284
OuterRadius     356993
FrontBright     1.0
BackBright      5.0
Brightness      1.5

}

Orbit
{

RefPlane       "Ecliptic"
Period          29.4577
SemiMajorAxis   9.5371
Eccentricity    0.0542
Inclination     2.4845
AscendingNode   113.715
LongOfPericen   92.432
MeanLongitude   49.944

}

}

The script starts with the keyword Planet, followed by the string "Saturn". After that, there are many lines with some parameters enclosed in a curly braces. The construction Planet "Saturn" { ... } is called a tag and plays an important role in SE scripts. Tags divide the script into logical sections, and they can themselves include other tags (for example, Surface { ... }).

Tags can be named, like the Planet tag, or unnamed, like Surface. A named tag can have multiple, or alternate, names, separated by a slash '/'. For example: Star "ALF Cen/Toliman/Rigel Kentaurus/Gliese 559". All of these names identify the same object in SpaceEngine, and they can each be used to search for the object in-game, or to refer to it from another script (for example, you must specify a star name in the parameter ParentBody in the planet script - you can use one of the multiple names of the star there).

Greek letters, if used, must be entered in the object's name using abbreviations: ALF, BET, etc. This is the full list of abbreviations:

ALFα(alpha)
BETβ(beta)
GAMγ(gamma)
DELδ(delta)
EPSε(epsilon)
ZETζ(zeta)
ETAη(eta)
TETθ(theta)
IOTι(iota)
KAPκ(kappa)
LAMλ(lambda)
MUμ(mu)
NUν(nu)
KSIξ(xi)
OMIο(omicron)
PIπ(pi)
RHOρ(rho)
SIGσ(sigma)
TAUτ(tau)
UPSυ(upsilon)
PHIφ(phi)
CHIχ(chi)
PSIψ(psi)
OMEω(omega)

A parameter is a line with the parameter name (keyword) on the left side and the parameter value on the right side. The name and value must be separated with spaces or tabs. Only one parameter per line is allowed. Parameters can be one of the following types:

string (text): Class "GasGiant"
number: Mass 95.162
vector: Color ( 1.000 1.000 0.850 ) or Color ( 1.000, 1.000, 0.850 )
number in 'deg min sec' or 'hrs min sec' format: Dec 18 32 16.23
boolean (binary): NoClouds true or NoClouds 1

Comments are allowed in SE scripts, which are in the C/C++ format:
// this is a single-line comment
/* this is an inline comment */
The first is the single-line comment. All text after the // symbols until the end of line is considered a comment and ignored by SE. The second is an inline or multi-line comment. All text between /* and */ is considered a comment and ignored by SE. New lines are allowed in this type of comment:
/* this is a
multi-line
comment */

Catalogs of astronomical objects

SpaceEngine handles information about all catalog objects in script files (with the extension *.sc) or in CSV files (*.csv), located in the virtual directory */catalogs/. Both file formats are plain text documents, so you can edit them with notepad. The csv files can be edited using specialized software for editing csv (like Microsoft Excel, with some side effects). The directory */catalogs/ has subdirectories named galaxies/, clusters/, nebulae/, stars/ and planets/, for each type of object.

The majority of stars in the default SpaceEngine installation are stored in the csv file data/catalogs/Catalogs0980.pak/stars/HIPPARCOS.csv, and the main catalog of galaxies is in data/catalogs/Catalogs0980.pak/galaxies/NGC-IC.csv. They are the HIPPARCOS star catalog containing about 110,000 stars, and the NGC/IC galaxy catalog containing about 10,000 galaxies. Other objects, including some galaxies and stars with additional data, binary star systems, black holes, star clusters and nebulae, Solar System objects, and exoplanets and their host stars, are stored in multiple sc files in the same system pak. These default files should not be modified or changed in any way. If you want to update an object, remove it, or add a new one, create your own sc or csv file in the corresponding addon folder (addons/catalogs/stars/ for stars and so on). SpaceEngine has scripting options to modify and remove stars or other objects from the default catalogs, or to add new ones. After finishing work on your catalogs, you can zip the catalog files into the pak file and share it with the community.

The csv format is used to create large catalogs of objects with similar data. It is more compact and a lot faster than sc, but has limitations in the types of data which can be specified in it. It is just a table with values separated by a comma. The current version of SpaceEngine (0.9.8.0) supports csv files only for stars and galaxies. The sc format is designed to specify any possible data that SE can use to describe an object. It is script-like text with 'tags' used to describe an object (galaxy, star, planet etc) and its various parameters.

Adding, updating, and removing catalog objects

If you describe a new object using SpaceEngine sc scripts, it will be added to the game. "New object" means that it didn't exist in SE before you made a script for it. More precisely, an object of the same type (for example, a star) and the same name didn't exist in SE. If the object of that type with the same name already exists in SE, it will be updated or merged with the data you have provided in your script. The order of merging (which data has priority) is defined by the modification date of the sc file or the pak file in which this sc file is packed. The newer file has higher priority, so some data from the script of this object in a previous file will be replaced with the new data provided. If the previous script doesn't have some specific data (for example, planet mass), but the new one has it, the newly provided data will be used.

Planetary objects (planets, moons, asteroids, comets, and stars in multiple-star systems) are identified in a more complicated way. SpaceEngine allows there to be many planetary objects with the same name, but with different parent bodies (specified in the parameter ParentBody). For example, the Solar system has two objects with the name "Pandora": a moon of Saturn and an asteroid. They have different parent bodies, Saturn and Sun, so they are different objects in SE.

While looking for identical objects, SpaceEngine scans all alternative names provided in the scripts. For example, you may update the old star Star "ALF Cen/Toliman/Rigel Kentaurus/Gliese 559" by describing a star in your script by Star "Toliman/Bungula". SpaceEngine will detect that this is the same object when it finds the name "Toliman". It will update the old star with the new data provided in your script, including the star name: it will add the new provided name "Bungula" to the list of alternative names, so it will become "ALF Cen/Toliman/Bungula/Rigel Kentaurus/Gliese 559". For a planetary object, as has been noted, you have to specify the parent object. SpaceEngine will merge them only if the object's name and parent object name are identical (any alternative name of the parent object can be used).

It's possible to cancel out some data in the old scripts, for example, NoClouds true will disable Clouds { } tags in the old scripts. But if the Clouds { } tags are provided for the planet which had NoClouds true in the old script, these Clouds { } tags will be used.

It's possible to change the type of an object by defining it with the other tag. For example, if older script has a planet "Kek" defined as Planet "Kek", and you create a new script and define it as Moon "Kek", it will change its type to moon. Changing the type is only possible within the set of types supported by the current catalog. This means that you cannot add a galaxy named "Saturn" to the planets catalog using the tag Galaxy "Saturn". It will be ignored by SE, because tag Galaxy is not allowed in the planets catalog. Here is the list of object types (tags) which are allowed in the corresponding catalogs:

Planet catalogs */catalogs/planets/*.sc: Star, Planet, Moon, DwarfPlanet, DwarfMoon, Asteroid, Comet, Barycenter
Star catalogs */catalogs/stars/*.sc: Star, StarBarycenter
Galaxy catalogs */catalogs/galaxies/*.sc: Galaxy, Quasar
Star cluster catalogs */catalogs/clusters/*.sc: Cluster
Nebula catalogs */catalogs/nebuale/*.sc: Nebula

It's possible to remove (more precisely, disable) some object from the old catalogs. Use the parameter Remove with the name of object you want to remove. For example, Remove "Toliman". It must be used outside any tag. Any of the object's alternate names can be used. Star catalogs also support the RemoveStar parameter with the same effect (for backward compatibility). In the planets catalog you must use a more complex construction: Remove "Saturn" { ParentBody "Sol" }. This is because SpaceEngine identifies a planetary object by its name and its parent's name.

Removing old objects is useful when upgrading the default SE catalogs. For example, the default star catalogs still have many binary stars described by two solitary stars. One can use Remove in the star catalog to delete them, and add a barycenter description to the same star catalog. Then make a planet catalog with two stars with proper orbits and that barycenter as their parent. See Creating a star for details.

Note: the Remove parameter affects all catalog files, regardless of their modification date. So if you used it once, it will no longer be possible to create an object of the same type with the same name. It is a bug in the current version (0.9.8.0).

Checking for errors in catalogs

SpaceEngine can output some errors and warnings into the log file system/se.log while loading catalogs. This is useful for catching possible errors. There are two ways to enable logging: global and per catalog file. The global logging level is controlled by the parameters CatalogLogLevel (for sc catalogs) and CsvLogLevel (for csv catalogs) under the Log tag in the config/main-user.cfg file. Possible values are:

0 - do not log anything
1 - log errors and warnings, using the lesser log level between those in the main-user.cfg and in the sc file, if defined there
2 - log everything, using the lesser log level between those in the main-user.cfg and in the sc file, if defined there
3 - log errors and warnings, ignoring log level in all sc files
4 - log everything, ignoring log level in all sc files

The last two are used to override the log level settings in all sc files (not usable in the CsvLogLevel parameter). They are provided for global searching for catalog errors.

Each sc catalog file may have its own log level settings, specified by the parameter LogLevel, added somewhere in the global space (i.e. outside the tags Star, StarBarycenter etc). Possible values are:

0 - do not log anything
1 - log errors and warnings only
2 - log everything

It is recommended to specify LogLevel 2 in your sc files and CatalogLogLevel 2 in main-user.cfg while you are working on catalogs so you will have all information about star solver work in the log file (see Creating a star for details). If you need to see only possible errors, specify LogLevel 1. If some errors or warnings are still visible in the release version of your catalog (for example, no RA/Dec data are provided for a star, and star solver generates them procedurally), it's recommended to specify LogLevel 0, so other users will have their log files clean of errors related to your catalog.