| SpaceEngineer | Date: Tuesday, 13.09.2016, 13:40 | Message # 1 |
 Author of Space Engine
Group: Administrators
Russian Federation
Messages: 4800
Status: Offline
| Last Updated: 2016/09/14 (version 0.9.8.0)
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/ (read more about SpaceEngine directories and pak files here: SE folders and pak files). Both 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). 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 (see SE folders and pak files for details).
The csv format is used to create large catalogs of objects with similar data. It is more compact and loads 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.
The *.sc files
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.8
Surface
{
// 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 - ξ (Ksi)
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) at the left side and the parameter value at the right side. The name and value must be separated with spaces or tabulations. 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 (logical): 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 one in 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 */
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 and the same name does already exist 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 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 alternate 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 alternate names, so it will become "ALF Cen/Toliman/Bungula/Rigel Kentaurus/Gliese 559". For 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 alternate 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 of 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 planetary objects 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
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.
|
| |
| |
| sinsforeal | Date: Tuesday, 13.09.2016, 13:56 | Message # 2 |
 Space Pilot
Group: Users
United States
Messages: 129
Status: Offline
| Very nice guide!
"Man once looked up at the stars and wondered, Now all we do is look at our hands and hesitate"
|
| |
| |
ENG
New site
Russian Federation 
United States