Space Engine | Creating a ship
page-template-default,page,page-id-633,page-child,parent-pageid-519,eltd-cpt-1.0,ajax_leftright,page_not_loaded,,se-ver-2.1, vertical_menu_with_scroll,transparent_content,blog_installed,wpb-js-composer js-comp-ver-5.0.1,vc_responsive
Creating a ship

This tutorial describes how to import a custom ship model to 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 the pak file.

Spaceships in SpaceEngine

Ship 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 uses the same model (for example, engines or farm element), that allows to save a lot of video memory. But the ship may also have a single module (like Shuttle). If your new model is complex and have 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 of the “2001: A Space Odyssey”. We also assume that this is not the only ship of this 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 notice: all folders with the path which has a form of */models/spacecraft/ (and the same for */textures/spacecraft/) are considered by SpaceEngine as one large virtual folder. So if you put your addon’s texture or model directly to the default location, like this: addons/2001/texture/spacecraft/engine.jpg, it is likely that it can be overriden by some texture with the same name in some other 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 some additional folders with unique name inside our standard models and textures folders. For example, create a folder Odyssey2001:


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

If your addon may have 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 type. 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 uses a common textures, you may create for them a folder called for example common. But this is not necessary ewither, just for convenience; you may store common textures directly in the addons/2001/textures/spacecraft/Odyssey2001/. In general, all such innermost folders are optional, you decide to not use them. But it is important to take in mind, what 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, what the Discovery subfolder is optional). Texture files are 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 subfolders. 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 using 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 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 sips built be 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 the 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, it is needed for further understanding.

The ship scheme file – *.sss

To add the Discovery ship, create and 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 falseModule  “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 have a two-level filter scheme using this parameters. In this example, it would be logical to include the ship to the pack called “2001”, and to a fraction called “NASA”. There are 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 the SE except for display 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 in 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 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 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 Ship editor (see below).
“Addons/Odyssey2001/DiscoveryOne.cfg” – path to the cfg file of the module relative to 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 (4×4) 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 a folder addons/2001/models/spacecrafts/Odyssey2001/Discovery/, as specified in the sss file. To create a new modular ship, you can use existing models of the modules, or import the 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 notations are 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 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 in the list in the cfg file which as associated with the current sm file) uint16 - drawing mode: 0 - GL_TRIANGLES 1 - GL_TRIANGLE_STRIP 2 - GL_TRIANGLE_FAN 3 - GL_QAUDS 4 - GL_QAUD_STRIP 5 - GL_LINES 6 - GL_LINE_STRIP 7 - GL_LINE_LOOP 8 - GL_POINTS 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 is 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/. Example of the content of the DiscoveryHull.cfg file:


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 model’s mesh (see description of the *.sm format). The number of the 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 each 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 (detail 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 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 other 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 the materials only works while importing, and can be disabled in SpaceEngine main config file main-user.cfg (the parameter ReplaceDuplicateMat).

In 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 what 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 what 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 a 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 a 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 material 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 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 shining effect around it (if the 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 shining effect around it (if the 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 shining effect around it (if the 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 placing textures of your model to the addons/2001/textures/spacecraft/Odyssey2001/Discovery/, you need to specify the paths in the sml in 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 the png format is not easy, because formally png does not support alpha channel. To get around this, save the RGBA image to the tga format, and then convert it to a alpha-png using 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 options to export mesh as triangles, 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 what we are working on the “Discovery” ship main body model without engines, called DiscoveryHull (in our example, engines was 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 also must 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 some 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 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 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. 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 does not supports 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 file *.cfg file to some already existed materials in other libraries.

Using the ship editor

If orientation of the ship in SpaceEngine after the importing 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’s modes are selected by tickboxes in the upper side of the panel.

Editing the whole ship

Tick the “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 [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 right mouse drag to determine whether the alignment is done correctly. Take control of the ship to determine whether the model is orientation in the game is correct (it must be view from the automatic camera, see below). Cameras can be added/edited in this mode also (see below).

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

Editing the module

Tick the “Edit Module”. Select a module from the drop-down list below. Selected module will start blinking. You can rotate, pan and resize module using the “Position”, “Rotation” and “Size” buttons. The distance unit is meters, angle unit is degrees. Pressing [Shift] key toggles these buttons to “coarse mode” – useful for fast moving of the module. Changes applied only to that particular copy of the module in this class of ships. I.e. if you displace 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 of SpaceEngine.

Adding or changing the engine exhaust effect

Tick the “Edit engine effect”, while module is selected. The effect is applied to the module. This allows to add the single effect to some “engine” module and use it multiple times in the modular ships. In contrast, a 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 means 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 the 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 of the module editing. The changes applied to all modules of this type, and for all ship using that modules! So if you adjusted the engine module once, then you can not 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 the “Edit docking port” while module is selected. The docking port effect is applied to the module, as long as engine the exhaust effect. This allows 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 by buttons, similar to those in the module editing. The Type drop-down box does not affect anything for now. The changes 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 the “Edit docking port corridor” while module is selected. Docking ports in SpaceEngine have a visual markers which looks like a shimmering corridor of rectangles. It allows pilot to navigate his arriving ship before docking. Therefore, the end of the corridor (from whence 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 buttons similar to those of the 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 Editor is in the “Edit entire ship” mode. Choose 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 hardly coupled with the ship model.
Auto – default smooth third-person camera, it is also used if there is no custom cameras were added to the ship.

By clicking “Add”, the camera is created at the point where the observer at the 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 (tags Camera are added).

Saving changes

Click the “Save” button to save the changes. Saving into pak-file is not performed, instead SpaceEngine will create a 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 this particular ship which you are editing.

When you click “Close”, it closes the editor without saving the recent changes to the disk. Changes however remains on the ship which was edited, but only until the restart of SpaceEngine.