Difference between revisions of "Modding Guide"

Revision as of 15:48, 19 November 2014

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, the official modding section of the forums, the SEModAPI project topic, and the se-modz website.

Overview

Most mods under the current system can be classified under three main groups, roughly in order from least to most difficult: those that modify existing assets, such as changing the look of the Skybox or introducing variants of existing blocks such as the Thruster or Armor Block; those that introduce new aesthetic blocks such as wings, ramps, or other nonfunctional doodads; and those that change the way the game is played, either through functionally improving certain aspects of the game or introducing blocks with no real equivalent in vanilla Space Engineers.

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.

Creating new blocks with their own look requires the use of 3D modelling and texturing, 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.

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.

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.

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

• SANDBOX_0_0_0_.sbs – detail definition of a world, positions and states of objects (we don’t have more details at this moment, but it should be pretty self-explanatory – run some experiments)

• *.vox – binary voxel data for an asteroid (outdated, current game converts these to vx2 format on initial load)
• *.vx2 - binary voxel data for an asteroid (we don’t have more details at this moment)

• *.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 C:\Users\{WINDOWS USERNAME}\AppData\Roaming\SpaceEngineers\Mods\{MOD NAME}

The mod folder has to contain a sub-folder called Data with definition files of added or updated mods. Everything can be replaced/updated by the modder (audio, video, textures, models, gui, etc).

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.

Shaders

Almost all textures are in the DirectX *.dds format (DXT 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.

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\SpaceEngineers\Content\Models\

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. Currently SEModAPI is still being developed, as there are certain things that are possible under that API that are not in the official one, but once that ceases to be the case the official API will be the sole avenue for creating custom scripts for modding. 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: DLLs, script mods, and in-game scripting. Presumably a standalone DLL will be the most powerful (and most difficult to create), with in-game scripting providing the quickest form of modification for simple or low-scope scripts, with standalone mods standing somewhere in between.

The current implementation of the API only includes script mods, with the other two completely unsupported (though a bare-bones preview of the in-game scripting does exist). 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 API Documentation page for more information.