Creating a ship

This tutorial describes how to import a custom ship model into SpaceEngine. Before continuing, it is recommended to read this manual: Introduction.
All the examples in this tutorial do not uses the pak files, but it is advisable to ensure that your final (release) version of the addon has been packed to a pak file.

Spaceships in SpaceEngine

Ships in SpaceEngine may consist of several parts, each of which is represented by a separate model file. For example, ships made in the SHW editor can have several engines, radiators, tanks, connecting farms, etc. Identical modules use the same model (for example, engines or farm element), which saves a lot of video memory. But the ship may also have a single module (like a Shuttle). If your new model is complex and has repetitive elements, it makes sense to cut it into modules.

Later in this guide we will assume that you are creating a model of the ship Discovery from the "2001: A Space Odyssey" story. We also assume that this is not the only ship of that franchise that you want to import. Therefore, create a new folder in the addons directory: 2001 (we will call it the worker folder), and default SE folders for models and textures inside it:

Any model of the ship, even a single-module one, consists of multiple files, split into two groups. The first group is related to the models, the second - to the textures. The models are stored in the addons/2001/models/spacecraft/, and textures in the addons/2001/textures/spacecraft/ folder. So now we need to create two folders called spacecraft:

addons/2001/models/spacecraft/ - we will call it the standard models folder
addons/2001/textures/spacecraft/ - we will call it the standard textures folder

Important note: all folders with a path which has the form of */models/spacecraft/ (and the same for */textures/spacecraft/) are considered by SpaceEngine as one large virtual folder. So if you put your texture or model addons directly into the default location, like this: addons/2001/texture/spacecraft/engine.jpg, it is likely to be overriden by some texture with the same name in another addon, according to the modification date priority rule (or your texture may override another texture in some addon). To avoid this situation, it is necessary to create additional folders with unique names inside our standard models and textures folders. For example, create a folder Odyssey2001:


Now the folder Odyssey2001 should be taken into account when specifying file paths in the ship's script and material files, but this is necessary to avoid ambiguities and overriding files in other addons.

If your addon may end up having many ship models, for convenience you can create another extra level of folders, although this is not necessary. For example, a unique named folder for each of the ship types. In our case, it makes sense to create a folder named Discovery, because we are importing the model of this ship:

addons/2001/models/spacecraft/Odyssey2001/Discovery/ - we will call it a models folder
addons/2001/textures/spacecraft/Odyssey2001/Discovery/ - we will call it a textures folder

If some models use common textures, you may create a folder for them called, for example, common. But this is not necessary either, it's just for convenience; you may store common textures directly in the addons/2001/textures/spacecraft/Odyssey2001/. In general, all such subfolders are optional, you decide whether or not to use them. But it is important to keep in mind that they affects the paths to the files, which are written to in the scripts. Furthermore, we assume in this manual that you have created an innermost folder Discovery.

So, any spaceship in SpaceEngine consists of these files:

  • One or more model files (modules) with the extension *.sm (Spacecraft Model), located in the folder addons/2001/models/spacecraft/Odyssey2001/Discovery/. The sm file is the binary file with the model's geometry, its description is given below. It is possible to import a model from the obj format (look below).
  • The configuration file with the extension *.cfg for each sm file model. The cfg file name must match the name of the sm file, and it must be in the same folder. The configuration file describes what material each sm model mesh uses, and some other parameters.
  • One or more texture files in the folder addons/2001/textures/spacecraft/Odyssey2001/Discovery/ (remember that the Discovery subfolder is optional). Texture files are in the common graphics file format jpg, png, tiff, dds, tga. The model can have no textures, but it must have materials.
  • One or more material library files with the extension *.sml (SpaceEngine Material Library), located in the default textures folder or in some optional inner subfolder. The library file contains a description of one or more materials used in the sm model. A material is a description of which textures are being used, with their paths, how they are using brightness, color, and other parameters.
  • A ship's scheme file with the extension *.sss (SpaceEngine Spacecraft Scheme), located in the folder addons/2001/models/spacecraft/Odyssey2001/Discovery/. The scheme file describes which modules the ship uses, their location and orientation, as well as the standard name of the ship, its class, size, weight, and other parameters. The ship must have at least one module. The ship scheme files are automatically searched in all subfolders which have a path like */models/spacecraft/*/ at the startup of SpaceEngine, and are displayed in the Ship manager's build menu. So, to make a ship visible in the Build menu, it must have the sss file. But to make its model visible in game, it must have all other files described above).
  • All ships built by the player are saved in the script file called config/ For all ships, it saves the ship's name, a path to its sss scheme file, its coordinates, velocity and orbit. This file is automatically generated, it is not necessary to change it when importing new ships.

First I will describe the format of the scheme file, as it is needed for further understanding.

The ship scheme file - *.sss

To add the Discovery ship, create an empty file with name DiscoveryShip.sss in the models folder addons/2001/models/spacecraft/Odyssey2001/Discovery/. Open it in Notepad and type the code shown below.

Name    "Discovery"
Class   "Planetship"
Pack    "2001"
Faction "NASA"
Length   168.63181
Offset  (0 1.5 5)
Quat    (1 0 0 0)
Mass     2000000
Albedo   0.1
Exposure 3
Color   (1 1 1)
MainEngines  30
RetroEngines 0
HoverEngines 0
CorrEngines  0.5
TurnEngines  0.002
WarpBoostLog 0
Hyperdrive   false
Aerodynamics false

Module  "Main"     { "Odyssey2001/Discovery/DiscoveryHull.cfg" (-1 0 0 0 0 1 0 0 0 0 -1 0 5 15 0 1) }
Module  "Engine1"  { "Odyssey2001/Discovery/DiscoveryEngine.cfg" (0.5 0.8660253882408142 0 0 -0.8660253882408142 0.5 0 0 0 0 1 0 0 60 -20 1) }
Module  "Engine2"  { "Odyssey2001/Discovery/DiscoveryEngine.cfg" (-0.5 0.8660253882408142 0 0 -0.8660253882408142 -0.5 0 0 0 0 1 0 -51.96152496337891 30 -20 1) }

Name - the default name of the ship, it is displayed in the Ship build menu. When building the first ship of this type, it will have the specified name - "Discovery". The second built ship of this type will be named "Discovery 01", the third one - "Discovery 02", and so on. You can rename the ship in the game by clicking the "Rename" button in the Ship manager window. You can give a name that matches the name of some existing ship, but this is not recommended because it would be difficult to distinguish them from each other.

Class - the ship class, shown in the table of information about the ship in SpaceEngine. Possible classes are
"Astronaut" - astronaut
"Probe" - probe
"Shuttle" - shuttle
"Starship" - interstellar spacecraft
"Planetship" - interplanetary spacecraft
"Station" - space station

Pack, Faction - the ships' pack (or collection, franchise) and faction. The Ship building menu has a two-level filter scheme using these parameters. In this example, it would be logical to include the ship in the pack called "2001", and a faction called "NASA". Other ships may by imported for this addon, with the same franchise name "2001", and the same or different faction. For example, "Leonov" ship have the faction "USSR". All names must be in English.

Length - length of the ship in meters. It is automatically calculated when you first load the ship (using information about the positions and sizes of modules). Therefore, when creating this script, specify a value of 0.

Offset - displacement of the center of the ship, in meters. It is automatically calculated when you first load the ship, and can be changed in the Ship editor. Therefore, when creating this script, specify the value of (0 0 0).

Quat - orientation quaternion of the whole ship, it can be changed in the Ship editor. Therefore, when creating this script, specify the value of (1 0 0 0).

Mass - ship's mass in kilograms. It is not yet calculated, and is not used by SE except in the info table of the ship.

Color - RGB color of the particle, which is drawn instead of the model, when the ship is far away. It is not calculated automatically.

Albedo - the average albedo (reflectivity) of the ship, which affects the brightness of the particle. It is not calculated automatically.

Exposure - this exposure level is applied to all materials on the ship. Sets the overall brightness of the model.

MainEngines, RetroEngines, HoverEngines, CorrEngines - maximum acceleration (in m/s2) caused by the engines: the main, braking, takeoff, and shunting engines. If the value is zero, it means that ship has no corresponding engines (for example, the Shuttle has no braking engines, while any starship has no takeoff engines).

TurnEngines - "thrust" of the shunting engines while using them to rotate the ship. Larger value for faster rotations.

WarpBoostLog - logarithm of the maximum warp drive boost factor (ie, how many times it increases the ship's physical speed when the warp engine is at full power). For example, to make it 1012, type WarpBoostLog 12. The value of 1012 corresponds to about 1 light year per second in warp with the physical speed of 10 km per second.

Hyperdrive or Warpdrive - does the ship have a warpdrive.

Aerodynamics - whether the ship is designed for atmospheric flight. If value is true, SpaceEngine uses the aerodynamic model of the shuttle with control surfaces (ailerons, elevator, rudder) that are controlled with the mouse and keyboard. If value is false, the ship behaves like an arrow (rotated in the direction of air flow) and has no control surfaces - the correction engines are used for turning instead (like in spaceflight).

Module - one or more tags describing the modules of the ship:

Module  "Main"     { "addons/Odyssey2001/DiscoveryHull.cfg" (-1 0 0 0 0 1 0 0 0 0 -1 0 5 15 0 1) }

In this code:
"Main" - the name of the module is used to distinguish one from the other modules in the Ship editor (see below).
"Addons/Odyssey2001/DiscoveryOne.cfg" - path to the cfg file of the module relative to the standard models folder addons/2001/models/spacecraft/.
(-1 0 0 0 0 1 0 0 0 0 -1 0 0 0 0 1) - the module transformation matrix (4x4) by rows, i.e. the first 4 numbers corresponds to the first row, the next 4 numbers to the second row, and so on. In this example the matrix is:
| -1  0  0  0 |
|  0  1  0  0 |
|  0  0 -1  0 |
|  5 15  0  1 |

The upper left sub-matrix is a rotation and scale matrix. The first three numbers on the bottom line (5 15 0) are the displacement of the module's center.
If you import a single-module ship, make this matrix uniform:
(1 0 0 0 0 1 0 0 0 0 1 0 0 0 0 1)
This will place the module in the center of the model and orients it like it was done by the model's author.

If the intended orientation does not coincide with the orientation in SpaceEngine's coordinate system, you can reorient the module or the entire ship in the Ship editor (see below).

The module model file - *.sm

SpaceEngine has its own binary format model *.sm. In the example above, the ship "Discovery" contains three modules, which correspond to two models - and (the latter is used twice). They are located in the folder addons/2001/models/spacecraft/Odyssey2001/Discovery/, as specified in the sss file. To create a new modular ship, you can use existing models of the modules, or import new models from the obj format (see below).

Below is the technical information about the *.sm file format provided, for those who want to make a converter or editor.

The *.sm format consists of a header and one or more meshes, each of which consists of a subheader, and the vertex and index arrays. The following items are stored right next to each other. An entry such as "3 * float32" means the three elements of type float32. The following notation is used in the data types:

char - C/C++ char (8-bit)
uint16 - C/C++ unsigned short (16-bit)
uint32 - C/C++ unsigned int (32-bit)
float32 - C/C++ float IEEE 754 standard (32-bit)
The file header
4 * char - 4 characters 'SM01'
1 * uint32 - mesh number
3 * float32 - displacement of the mesh center (the coordinates of the center of the bounding sphere)
1 * float32 - the radius of the sphere around the mesh (the radius of the bounding sphere)

Next to the header, there are several meshes stored, the number of which is specified in the second header's field. Each mesh has its own header, vertex array and index array.
The mesh header
uint32 - number of vertices
uint32 - number of indices
uint16 - index of the material used with this mesh (materials are counted in order, starting from the beginning of the list in the cfg file which is associated with the current sm file)
uint16 - drawing mode:


The mesh is drawn by the same shader (material) regardless of the mode, therefore points and lines will be painted with the color and textures as if the mode were GL_TRIANGLES. The shader is selected based on material, such as diffuse + normal, diffuse + bump + specular, or even just a monotone color without texture (see materials description). Each mesh of the model is drawn by only one material and has one diffuse texture, one normal texture, etc.

Next is a continuous array of vertices, the number of which is specified in the second field of the mesh header.
Format of the vertices
3 * float32 - vertex coordinates
3 * float32 - vertex normal
3 * float32 - tangent vector
1 * float32 - binormal sign
2 * float32 - texture coordinates

Next is a continuous array of indices in the format of uint32. The mesh is drawn by the mode that is specified in the object's header.

The sm-model configuration file - *.cfg

This is a text file whose name must match the name of the sm file. In this example, there should be two such files - DiscoveryHull.cfg and DiscoveryEngine.cfg, located where the corresponding sm files are, i.e. in the folder addons/2001/spacecraft/Odyssey2001/Discovery/. An example of the content of the DiscoveryHull.cfg file is:

Unit    1
Length  168.6318Material "Discovery_hull"
Material "Discovery_hull1"
Material "Discovery_HAL2001"
Material "Discovery_Sideairlockete"
Material "Discovery_antenna"
Material "Discovery_bridge"
Material "Discovery_bridge1"
Material "Discovery_elbow"
Material "Discovery_keyboard1"
Material "Discovery_material01"
Material "Discovery_material02"
Material "Discovery_material05"
Material "Discovery_podbayDiscoveryhull"
Material "Discovery_podbaydoors"
Material "Discovery_radar1"
Material "Discovery_sideairlockintDiscoveryhull"

Length, Unit - length of the model in meters or length of the 3D editor's unit in meters. These values are necessary for the proper scaling of the model. Initially, one of the values may be zero, depending on whether unit length or model length is known. In this case, SpaceEngine calculates the second value and stores it in the script:
1) Unit = 0, Length = 0
Unit is equal to 1 meter, Length is calculated from the farthest vertex coordinates of the model.
2) Unit = 0, Length != 0
Length is specified, therefore Unit is calculated by dividing the Length value by the length of the model, calculated by the coordinates of the farthest vertex.
3) Unit != 0, Length = 0
Unit is specified, therefore Length is calculated by multiplying the Unit value by the length of the model model, calculated by the coordinates of the farthest vertex.
4) Unit != 0, Length != 0
Both Unit and Length are specified, nothing to calculate.

Material - name of the material that is used by the model's mesh (see description of the *.sm format). The number of Material parameters is equal to the number of the meshes in the model, and they are stored in numerical order of the meshes, starting from zero. The list of materials is automatically generated while importing from the *.obj format. The materials themselves are described in the *.sml files - the SpaceEgnine Material Libraries (see below).

The material library file - *.sml

This is a text file that contains a description of one or more materials. SpaceEngine automatically searches for all sml files in the folders like */textures/spacecraft/*/. Thus, it is possible to have any number of material libraries, e.g., one library per ship model, or one library for a set of ship models. Similar ships can use the same materials, so it makes sense to combine them into a single library.

The ship's module model can consist of multiple meshes. Each mesh has one material assigned, containing from 0 to 6 textures (see below), and the Material tag which describes how to use these textures (if no texture is assigned, then mesh will have a uniform color).

While importing from *.obj format, the material library is created automatically from a *.mtl file, which comes with the *.obj file. The names of the materials are taken from there, as are most of their parameters (detailed textures are not supported by *.obj, so they can be added to materials after importing). Names of the materials in the cfg file are stored in the order in which they were used in the *.obj file.

Important! During the import, if a duplicate material is found (all parameters, except the name, are identical to some existing material from this or another library), then the already-existing material will be assigned to the mesh. This is done to increase the performance of the engine - the smaller the number of different materials used by the model, the less they need to be switched, which reduces the cost of CPU time. Automatic combining of materials only works while importing, and can be disabled in SpaceEngine's main config file main-user.cfg (the parameter ReplaceDuplicateMat).

In our example, we will use the single material library 2001.sml for all the ships from the 2001 franchise, located in the folder addons/2001/textures/spacecraft/Odyssey2001/ (outside the innermost subfolder Discovery):

Material    "Discovery hull notex"

DiffColor       (0.878 0.878 0.878)
SpecColor       (1.000 1.000 1.000)
SpecPower       362.039


Material    "Discovery hull"

DiffColor      (0.878 0.878 0.878)
SpecColor      (1.000 1.000 1.000)
SpecPower       362.039
DiffMap        "Odyssey2001/Discovery/Discovery hull.png"
BumpMap        "Odyssey2001/Discovery/Discovery hull bump.png"
BumpHeight      5.0
DetDiffMap     "default/detail-noise.*"
DetBumpMap     "default/detail-noise.*"
DetDiffScale    8.0
DetBumpScale    8.0
DetBumpHeight   0.3
DiffMapAlpha   "Transp"
TwoSided        true


Material    "Discovery engine01"

DiffColor      (0.500 0.500 0.500)
SpecColor      (1.000 1.000 0.800)
SpecPower       15.0
EmisColor      (1.000 1.000 1.000)
EmisBright      0.5
DiffMap        "Odyssey2001/Discovery/Discovery engine.jpg"
NormMap        "Odyssey2001/Discovery/Discovery engine bump.png"
EmisMap        "Odyssey2001/Discovery/Discovery engine"
DetBumpMap     "default/detail-noise.*"
DetBumpScale    20.0
DetBumpHeight   0.5


Material "Discovery_hull_notex" - the tag's title; "Discovery_hull_notex" is the name of the material. When importing from obj + mtl, the name of the material will be the same as in the mtl file.

DiffMap - the diffuse color texture, RGB or RGBA format (if there is an alpha channel, it is interpreted as the size (exponent) of the specular flare, or transparency, see the DiffMapAlpha parameter). The path is relative to the standard textures folder: addons/2001/textures/spacecraft/ folder.

BumpMap - the bump texture, Grayscale or RGB format (grayscale is better). If only this texture is specified, the normals texture is generated from this texture automatically, using the BumpHeight parameter (see below). The path is relative to the addons/2001/textures/spacecraft/ folder.

NormMap - the texture of the normals in the tangent space, RGB format. If this texture is specified, parameters BumpMap and BumpHeight are ignored. The path is relative to the addons/2001/textures/spacecraft/ folder.

SpecMap - the reflectance (specular) texture, RGB or RGBA format. The RGB channels set the color of the specular spot. If it has an alpha channel, it is interpreted as the size (exponent) of the spot, so you can set the size of your spot for each pixel. The brightness of the alpha channel of this texture is multiplied on the SpecPower parameter. The path is relative to the addons/2001/textures/spacecraft/ folder.

EmisMap - the emission (glow) texture, RGB or RGBA format. Alpha channel is not used. The path is relative to the addons/2001/textures/spacecraft/ folder.

DetDiffMap - the detail diffuse texture, i.e. small color pattern. Applied to the entire model with repetitions, so should be cycled. The format is similar to DiffMap.

DetBumpMap - the detail bump texture, i.e. small surface irregularities. Applied to the entire model with repetitions, so should be cycled. The format is similar to BumpMap. Note that in this example, the path default/Detail-noise.* is used, so SE will load the texture Detail-noise.png from the default texture pack (it's virtual path is data/textures/spacecraft/default/Detail-noise.png). Remember that all folders like */textures/spacecraft/ are treated as a single virtual folder.

DetDiffScale, DetBumpScale - the scale (frequency) of the detail color and bump textures.

BumpHeight, DetBumpHeight - the amplitude (height) of the detail bump texture.

DiffMapAlpha - how to interpret the alpha channel of the DiffMap texture, if it is used:
"None" - the alpha channel is ignored
"Spec" - the alpha channel gives the size (exponent) of the specular flare. It is multiplied by SpecPower. If there is a SpecMap texture used, this effect is added to the effect of the SpecMap alpha channel.
"Transp" - the alpha channel is transparency. When alpha is less than 0.5 (or 128 units of integers from 0 to 255), the pixel is discarded and there will be a hole. Used to create lattice/truss structures with a minimum of polygons (see the TwoSided parameter).

TwoSided - if this flag is set to true, the material is considered to be two-sided, i.e. backface culling is not used. Thus the inner (back) faces of the mesh will be rendered. If you create a truss using DiffMapAlpha "Transp", you must use this parameter, otherwise the back (inner) surfaces of the truss will not be visible. The outer and inner faces of this texture coincide. Another way to create truss structures with different textures on the outer and inner surfaces - make an overlapping geometry, but with reversed normals and different texture coordinates (or different materials) for the inner surface. In this case, the transparency should be enabled (DiffMapAlpha "Transp"), and two-sided materials must be disabled (the TwoSided parameter is false or simply not specified).

DiffColor - the diffuse color of the surface. If the DiffMap texture is not assigned or not yet loaded, the mesh is drawn with this color. Otherwise the DiffMap texture is modulated by this color. This can be useful for the quick creation of a different colored skin for the same mesh. But make sure DiffColor is non-zero, otherwise the mesh will be black!

SpecColor - the specular flare color multiplier. Final specular spot color is multiplied by this color. The components of the SpecColor can be greater than 1.0, in which case the flare effect will be very bright, with a shining effect around it (if Bloom is enabled in the graphics settings).

SpecPower - the size (exponent) multiplier of the specular flare. Multiplied by the pixel's alpha channel value in the SpecMap or DiffMap texture.

EmisColor - the color of the emission light. The EmisMap texture is modulated by this color. If the EmisMap texture is not assigned or not yet loaded, the emission effect is not drawn. The components of the EmisColor can be greater than 1.0, in which case the emission effect will be very bright, with a shining effect around it (if Bloom is enabled in the graphics settings).

EmisBright - brightness of the emission effect. May be greater than 1.0, in which case the emission effect will be very bright, with a shining effect around it (if Bloom is enabled in the graphics settings).

All paths to the textures in the *.sml should be specified relative to the default textures folder addons/2001/textures/spacecraft/. That is, if you are placing textures for your model in the addons/2001/textures/spacecraft/Odyssey2001/Discovery/ folder, you need to specify the paths in the sml in the form of DiffMap "Odyssey2001/Discovery/texture.jpg". A wildcard is allowed for the file format, i.e. specifying DiffMap "Odyssey2001/Discovery/texture.*" forces SpaceEngine to find and load the texture in one of the supported formats, in this order of priority: dds, png, jpg, tif, tga. Your ships can also use some of the standard textures from the (virtual) folder data/textures/spacecraft/default/, like the detail textures in this example.

It is better to use textures in png or dds format (dds supports compression: DXT1, DXT3, DXT5, LATC1 and LATC2). But remember, that if you use Photoshop, saving RGBA images to png format is not easy, because png does not formally support an alpha channel. To get around this, save the RGBA image to the tga format, and then convert it to an alpha-png using the SpaceEngine console command:

SavePNG addons/2001/textures/spacecraft/Odyssey2001/Discovery/texture.tga

You must specify the full path inside the SpaceEngine folder. Similarly, you can convert to other texture formats by commands SavePNG, SaveDDS, SaveJPG, SaveTIF, SaveTGA.

Importing the model from the *.obj format

SpaceEngine supports importing models from the *.obj format with an automatic conversion into *.sm format. All you need to do is export your model from your 3D editor to the format *.obj with the creation of the materials library *.mtl (optional), copy these files and texture files into the appropriate SpaceEngine subfolders (see below), and create a ship scheme file *.sss.

When you export the model to the *.obj format in the 3D editor, you must select the option to export meshes as triangles (triangulation), and tick the following boxes - save vertices, normals, texture coordinates, and create a materials library (Create mat-library).

Example settings for 3ds Max

Lets consider that we are working on the "Discovery" ship's main body model without engines, called DiscoveryHull (in our example, engines were imported as a separate models). After exporting, you should have two files - the model geometry and the material library: DiscoveryHull.obj and DiscoveryHull.mtl. They should be copied to the models and textures folders of your addon:
DiscoveryHull.obj - copy to addons/2001/models/spacecraft/Odyssey2001/Discovery/
DiscoveryHull.mtl - copy to addons/2001/textures/spacecraft/Odyssey2001/Discovery/
Textures must also be copied to the folder addons/2001/textures/spacecraft/Odyssey2001/Discovery/.

You then need to create a ship scheme file *.sss (see above), with the path addons/2001/models/spacecraft/Odyssey2001/Discovery/DiscoveryHull.cfg specified in the Module parameter. Although this *.cfg file does not exist, it will be created automatically by SE. You can create your own *.sss file, or copy and change an existing file.

After that, you just have to run SpaceEngine, find the ship in the build menu and build it. SpaceEngine will load the *.obj and *.mtl files and automatically create the *.sm and *.cfg files in the models folder and the *.sml file in the textures folder. Depending on the number of polygons, importing of the *.obj file may take a while. While importing, some progress and possible error messages will appear in the log file system/se.log. After a successful import, the *.obj and *.mtl files can be removed. If it is necessary to repeat the import (e.g. update the model), simply remove the *.sm file and copy the new *.obj to the models folder and new *.mtl to the textures folder, and start SpaceEngine again.

To check the orientation of the spacecraft or module, take control of it. If the orientation is not correct, change it in the Ship editor (see below).

If there is no materials library *.mtl or it has not been exported, SpaceEngine will create the *.cfg file anyway, but it will contain only the parameters Unit and Length, without links to materials. Links to materials (and possibly an entire materials library) must be added manually.

When you import a model with a materials library *.mtl, the paths and extensions of the textures will be automatically replaced to Odyssey2001/Discovery/ and .*. That is, for example, if the there is this description of a texture in the *.mtl file:
then in the *.sml file it will be changed to
If this change is not correct (e.g. the model uses a texture from a different SpaceEngine folder, for example Odyssey2001/Discovery/engine1.jpg), it will be necessary to close SpaceEngine, open the *.sml file and correct the path manually.

Since formats *.obj + *.mtl do not support such effects as detail textures, transparency, two-sided materials, etc., after importing you will need to edit the *.sml file manually, or change links to materials in the *.cfg file to existing materials in other libraries.

Using the ship editor

If the orientation of the ship in SpaceEngine after the import is not correct, it is possible to rotate the whole ship model or individual modules in the Ships editor in SpaceEngine. To do this, select the ship and press [Shift]+[F2]. There you can also add engine exhaust effects, docking ports and the first- and third-person camera. Editor modes are selected by tickboxes in the upper side of the panel.

Editing the whole ship

Tick "Edit entire ship". You can rotate and move the ship as a whole using the "Position" and "Rotation" buttons. The distance unit is meters, angle unit is degrees. Pressing the [Shift] key toggles these buttons to "coarse mode" - useful for fast moving of the model. Checking "Show axes" will help in determining the position of the model's center. Rotate the camera around the ship using the right mouse button to drag, to determine whether the alignment is done correctly. Take control of the ship to determine whether the model is orientated in the game correctly (it must be viewed from the automatic camera, see below). Cameras can be added/edited in this mode also (see below).

Note: unpause time, otherwise there may be errors in the alignment of the model.

Editing the module

Tick "Edit Module". Select a module from the drop-down list below. The selected module will start blinking. You can rotate, pan and resize the module using the "Position", "Rotation" and "Size" buttons. The distance unit is meters, the angle unit is degrees. Pressing the [Shift] key toggles these buttons to "coarse mode" - useful for fast moving of the module. Changes apply only to that particular copy of the module in this class of ship. I.e. if you displace the engine module of the ship "Explorer-1", all new instances of the "Explorer-1" ship will have this module displaced, and all old instances as well after restarting SpaceEngine.

Adding or changing the engine exhaust effect

Tick "Edit engine effect", while a module is selected. The effect is applied to the module. This allows you to add a single effect to some "engine" module and use it multiple times in the modular ships. In contrast, single-module ships needed multiple exhaust effects added to the single module.

Type - affects the appearance of the jet effect.
Group - affects the behavior of the jet effect.

Main, Retro, Hover, Thruster mean, respectively: the main engines, reverse (brake) engines, engines for hovering and vertical take-off, and shunting engines. SpaceEngine automatically determines the size and brightness of the effect depending on its position, orientation, and group. So if you put the main engine effect (Group "Main") to the nose of the ship, it will not work (i.e. the effect will never be shown). The engine exhaust effect is not related to physics, it is just a visual effect.

The position, orientation and scale of the effect can be changed using buttons similar to those in module editing. The changes are applied to all modules of this type, and for all ships using that modules! So if you adjusted the engine module once, then you can't return back to it. The changes are saved to the module's cfg file (tags EngineEffect are added).

Adding or changing the docking port

Tick "Edit docking port" while a module is selected. The docking port effect is applied to the module, as well as the engine exhaust effect. This allows you to add docking ports to some "docking bay" module and use it multiple times in the modular ships. For example, this is done for the "shuttle_deck_front" and "shuttle_deck_back" modules in the SHW ships.

The edited port can be chosen in the drop-down list below. The position and orientation of the port are controlled using the same buttons as in module editing. The Type drop-down box does not affect anything for now. The changes are applied to all modules of this type, and for all ship using that modules, similar to the engine exhaust effect. The changes are saved to the module's cfg file (tags DockingPort are added).

Adding or changing the docking port corridor

Tick "Edit docking port corridor" while a module is selected. Docking ports in SpaceEngine have visual markers which look like a shimmering corridor of rectangles. It allows a pilot to navigate his ship before docking. Therefore, the end of the corridor (where the "light wave" comes out) must be located next to the docking port itself.

The corridor effect is also saved to the module's cfg file, to the same DockingPort tag as the docking port itself. Therefore its name in the drop-down list is the same as that of the docking port. The position, orientation and size of the effect are controlled by the same buttons as in module editing. The Type drop-down box does not affect anything for now.

Adding or changing the behind camera

To add an external third-person view camera or a cockpit first-person view camera, tick the "Edit behind camera" when the Editor is in the "Edit entire ship" mode. Choose an existing camera in the drop-down list below, or click "Add" to add a new camera. Its type can be changed in the drop-down list:

Behind - third-person view, camera is smoothly coupled with the ship model.
Cockpit - view from the cockpit, camera is fixed with the ship model.
Auto - default smooth third-person camera, it is also used if no custom cameras were added to the ship.

By clicking "Add", the camera is created at the point where the observer is at that moment. After that, it can be moved/rotated using the corresponding buttons. The position and orientation of the "Auto" camera are ignored, they are calculated by SpaceEngine. You can check the camera by simply taking control of the ship and switching view to it.

The changes are saved in the ship's sss-file (Camera tags are added).

Saving changes

Click the "Save" button to save the changes. Saving into pak-files is not performed, instead SpaceEngine will create an sss or cfg file on the disk with the same virtual path as the original file in the pak-file. Be careful when editing the ship! As long as changes are saved to the ship's sss file, they will affect all the ships of this type, not only the particular ship you are editing.

When you click "Close", it closes the editor without saving the recent changes to the disk. Changes, however, remain on the ship which was edited, but only until SpaceEngine is restarted.