Difference between revisions of "Modding Guide"

Latest revision as of 20:20, 26 January 2019

Modding is the process of injecting user-created content into Space Engineers. Currently what is available to be modded is limited, but already clever users have managed to create a wide variety of new content beyond the default vanilla game. With the introduction of the Modding API, a groundwork has been laid to even more customization of the Engineer experience.

There is currently no one-stop shop for all the information on modding. Information can be found here on the official wiki and the official modding section of the forums.

Tools

There are many different workflows used by various modders. There is also not a universal workflow that works for everyone. However, the following tools are recommend by most modders and make it much easier to create mods:

• Notepad++ (For XML, SBC, and general text editing)
• Visual Studio (For scripting)
• Blender (For creating 3d models)
• Harag's plugin for easily configuring blender and exporting 3d models into VRage format.
• Paint.NET (Photoshop also works if you have this plugin for exporting in the dds format)

Overview

Mods can alter the game in a variety of ways.

• Decorative Blocks alter the look and feel mods alter things like the Skybox, or add decorative blocks like hallways, exposed pipes, showers, beds, etc.
• Functional Blocks can be a combination of new looks and add existing or new functionality such as using a toilet model as a seat or making a cutting tool out of a Thruster.
  • Functional blocks can be extended further or used create entirely new types of blocks by adding scripting to a mod that controls how the block is used.
• Non Block mods can alter things other than Blocks or Skyboxes. These could be things like Character Animations, Space Suit variants, Inventory Sorting, or Combat AI for ships.

The ease of mod creation is highly dependent on what skills or ability to learn a modder brings with them.

Mods can be classified by complexity:

• Texture Mods involve editing or creating new game textures using programs like GIMP, Photoshop, Paint.net. Modifying existing textures, shaders, and stats of existing blocks is the simplest way to create a mod. Such mods can be created by simply copy/pasting the *.sbc info from an existing vanilla block, tweaking the values, and dropping the custom textures/shaders and *.sbc file into its own folder.
• Models also involve texturing, but allow you to add 3D rendered models to the game. Creating new blocks with their own look requires the use of 3D modelling and texturing, for which skills are outside of the scope of this guide. Using a 3D suite such as Blender, 3DS Max, or Maya, a modeller can create new objects for use within Space Engineers, which can then be converted for use by the game using the MwmBuilder utility.
• Scripts have two main types ModAPI and In-game. They are both written in the C# Programming Language. The first is in-effect on the entire game world and can interact with almost any game element. In-game scripts, however, are loaded into a special block called a Programming Block. These scripts can only access the ship grid or station grid they are attached to. They can read data from one block on your ship, for example, and trigger a Rotor to turn a certain amount in a specified direction. Actually changing the way things behave within the game is more complicated and requires the use of coding with C# to create scripts that modify the behavior of custom blocks.
• Plug-ins are a C# program(project) that is compiled as a DLL and is run by the game's .exe file directly. Plug-ins can alter almost anything in the game(as opposed to a game world or ship grid) , far beyond what an In-game or Mod API script can do.

Official guides have been written up on the Space Engineers website and the Steam Guides page. These will give new modders a feel for how to set up one's environment and what is required to get a mod going, but a lot of footwork is still needed by prospective modders to discover how all the parts work together. Modders can obtain help or information from the Keen Software House forums, Keen's partnered Discord channel as well as player run groups on other sites.

Save Files / World Files

Every world you generate is saved in its own folder that can be found in C:\Users\{WINDOWS USERNAME}\AppData\Roaming\SpaceEngineers\Saves\{STEAM ID}\

File types:

• Sandbox.sbc – basic description of a world. For more details, see: save file sbc

• SANDBOX_0_0_0_.sbs – detail definition of a world, positions and states of objects For more details see: save file sbs

• *.vox – binary voxel data for an asteroid (outdated, current game converts these to vx2 format on initial load)
• *.vx2 - proprietary octree voxel storage format

• [OBSOLETE] *.xmlcache – don’t modify these files, they are cache files regenerated on each save

Mod Files Location

Each mod has its own folder located in %AppData%\SpaceEngineers\Mods\{MOD NAME}

The mod folder has to contain a sub-folder called Data with definition files of added or updated mods. Almost everything can be replaced/updated by the modder (audio, video, textures, models, gui, etc). Mods are restricted to a single world and cannot change anything that exists outside the scope of that world. For example, while you can replace things like GUI Icons for block mods, you can't replace the graphics for the entire UI because it exists outside of a world that would load the mod.

Shaders

Files with *.fx and *.fxh extension are vertex/pixel shaders for various rendering operations and can be found in steamapps\common\SpaceEngineers\Content\Effects2\.

Every shader file gets recompiled on game launch. If you modify one, restart the game. If the game crashes on launch, it’s probably due to a compilation error caused by your changes.

Textures

Some textures are in the DirectX *.dds format (DXT5 compression). You will need an editing program that can manipulate them. If you use Adobe Photoshop, we recommend installing this plugin and using these settings for exporting:

Settings for exporting textures

Textures can be found in: steamapps\common\SpaceEngineers\Content\Textures\. There are multiple categories of texture files: GUI, particles, lights, models, voxels, etc. Model textures with “_ns” in their name contain the "normal map" in the RGB channels and the "specular map" in the ALPHA channel. Model textures with “_de” in their name contain the "diffuse map" in the RGB channels and "emissive map" in the ALPHA channel.

The textures which can use the above method are limited primarily to GUI Graphics such as Block or menu icons.

With Space Engineers moving from DX9 to DX11 PBR textures, the Method for creating textures has changed.

The easiest method is to create PNG or TIFF files for each texture and use the Texture Packing Tool to compile them into a .dds texture. DX11 textures use a different compression type (BC3 to BC7), therefore the plugins for DX9 will not work to open or save textures in this format. The DX11 textures are:

• “_cm” - Color(albedo) and Metalness map (alpha).
• “_ng” - Normal map and Gloss map (alpha).
• “_add” - Add texture - AO (Red channel), G (emissive) and B channels are not specified yet and Custom Color mask (alpha channel).
• “_alphamask” - alpha map.

More information can be found here. While this link is for Space Engineer's sister title, Medieval Engineers, the games share a common code base and the modding process is nearly the same for both games.

3D Models

MwmBuilder is the utility built by the devs for converting fbx files to mwm models.

Note: You may need administrator rights to copy or create files in Program Files folder; you can copy MwmBuilder and dlls into a different folder.

MwmBuilder Location: {Steam installations directory}\SteamApps\common\SpaceEngineers\Tools\MwmBuilder.exe

Models are stored in: steamapps\common\SpaceEngineersModSDK\OriginalContent\Models\

Models have been moved to the SpaceEngineers ModSDK. For information on obtaining the SDK on Steam check here

SIMPLE USAGE:

1. ) Copy FBX models to the same directory as MwmBuilder.exe
2. ) Create an XML file with the same name as the model. Giraffe.fbx will have Giraffe.xml.
3. ) Run MwmBuilder.exe
4. ) You'll find .mwm files in the same folder

For advanced usage see here: ADVANCED 3D MODELS GUIDE

Moddable collision models: Adding new model with collision geometry.

API

Creating a working script is a difficult process for a single individual to do, and to facilitate easy creation of scripts an API is required to guide a prospective modder in the correct direction. Initially the community did this themselves with the Mod:SEModAPI, but in Update 01.048 Keen released an official API as well. SEModAPI is no longer in development and should no longer be used. This guide and others like it on the official wiki will only discuss how to use the official API.

There are three planned "levels" of script modding for the official API:

• Plug-ins(DLLs) - will be the most powerful (and most difficult to create). This involves creating a set of custom methods, objects, and interfaces in Visual Studio and compiling the project into a .DLL file.
• ModAPI script mods - will allow access to objects at the world level as opposed to a single ship grid with in-game scripts. This level of script can, for example, add an effect to all blocks of a certain type on all ships regardless of owner. One such early script mod was used to create a teleporter.
• In-game scripts - will provide the quickest form of modification for simple or low-scope scripts. These are loaded via the Programmable Block's Menu. They can be written directly into the the text panel of the block or downloaded from a subscribed script in the workshop by clicking on a button in the same panel.

The current implementation of the API includes all three methods. Since these mods can be subscribed to and downloaded within Steam's infrastructure, certain limitations are in place to make sure that malicious mods cannot do irreversible damage (such as deleting files on the hard drive, etc). As such, not every in-game or out-of-game function can be used. See the Scripting Whitelist page for more information.

Plug-in DLL mods

These can bypass all protections in place in the game for preventing malicious code. That is what makes them so powerful as they can use functions normally restricted. They can do things like changing the GUI menus to add custom screens or add custom functions to blocks which are normally hard coded in the game. They are not available as workshop mods and are manually downloaded and loaded in the game with a specially created shortcut to SpaceEngineers.exe. It is advisable to only use plugins from a trusted programmer, or one that has the plugin source publicly viewable. Some plugins also have their own mods that need to be subscribed and added to a world through the Steam Workshop in addition to manually installing the plugin. Because of the potential for plugins to cause damage to not only the game saves, but to an individual PC, they are not officially supported by KSH.

Tutorials/Guides

• How to Mod Blocks
• How to Mod the Skybox
• How to Mod Characters
• How to Mod Character Animations
• How to Mod Ore
• How to Mod Production
• How to Mod Script
• How to Mod Respawn Ships
• How to Mod NPC Cargo Ships
• How to Mod Exploration
• How to Mod Scenarios

See also

• SE Workbench - an independent scripting IDE