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/spacecraft.sc. 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 - 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:
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 - DiscoveryHull.sm and DiscoveryEngine.sm (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.