Space Engineers

Space Engineers

60 ratings
Space Engineers Modding API Guide
By Marek Rosa
This guide will tell you how to start with our new Modding API and get it in your game
 
Rate  
Favorite
Favorited
Unfavorite
Modding API Guide 1/2
Important note
Shortly after releasing the API we will be doing some large changes to the codebase. Basic API gateway should remain compatible, but for blocks there will be probably change in the way you access and use them. Logic will stay the same you will probably just need to rename/ add some functions to get to the entities.

Basic setup for writing a script
Create new project in your favorite IDE (we use VS2012)
It does not matter what kind of project you create since you will not be compiling the code, you will use the IDE just for intelisense and highlighting.
Reference our libraries that can be found in Bin folder of your game (architecture does not matter since again its just for)
You can try start fresh or download some of usecase or other players script.

Entry point
To get anything from game you should go through interfaces provided by Sandbox.ModAPI.MyAPIGateway

Most of thing you get this way will be in form of interface, they are not complete though, they serve more like a filter to what you can access so implementing let’s say IMyEntity and trying to pass it to game will fail.

Getting your code executed
There are several ways to this
You add handler on MyAPIGateway.Utils.MessageEntered and execute your code depending on player input to chat
You can subclass MySessionComponentBase, add Attribute and it will get loaded before world and then updated each frame.
You can subclass MyGameLogicComponent, add Attribute and it will get hooked to any object

Some usecases
- SirBeacon - uses MyGameLogicComponent subclass http://steamcommunity.com/sharedfiles/filedetails/?id=315635351
inside you will find a hook for our Beacon block, which will make it more polite and greet you when you come near it
Sample Mission (Advanced)
- Map : http://steamcommunity.com/sharedfiles/filedetails/?id=315629274
- Script: http://steamcommunity.com/sharedfiles/filedetails/?id=315628704






Where to put files
In your Space engineers Mods folder create a new folder with name of your mod with structure like this
Mods\YourMod\Data\Scripts\YourScript\
And put all the .cs files in YourScript folder

Debugging your code
For now the debugging options are limited, after loading mod with script you can see F11 screen for any compilation or restriction errors.
While debugging you can wrap all your code in try-catch blocks and write any exceptions to custom log file so your game does not crash each time something goes wrong.

Restrictions

There will be at least three levels for scripting. Dlls, Scripts as mods and Ingame scripting.
Currently you are looking at the middle of these and since they are to be distributed by workshop we cannot risk someone wiping drives or downloading trojans and because you cannot possibly blacklist every way to the system we decided for whitelisting, that means if method/ class / namespace(bound to actual dll) is not whitelisted you cannot use it.
For the dlls there should be no such restrictions as they will be distributed the way community API was.
On the contrary Ingame scripting will be highly restricted since anyone will be able to write it at runtime. Preview of these is ModAPI.Ingame
Modding API Guide 2/2
Current whitelist

NullReferenceException
ArgumentException
ArgumentNullException
InvalidOperationException
FormatException
System.Exception
System.DivideByZeroException
System.InvalidCastException
System.Math
System.Enum;
System.Int32
System.Int16
System.Int64
System.UInt32
System.UInt16
System.UInt64
System.Double
System.Single
System.Boolean
System.Char
System.Byte
System.SByte
System.Decimal
System.DateTime
System.TimeSpan
System.Object
System.IDisposable
System.Random
System.Convert
System.Nullable<>

System.IO.Stream
System.IO.TextWriter
System.IO.TextReade

System.Collections.IEnumerator
System.Collections.Generic.IEnumerable<>
System.Collections.Generic.HashSet<>
System.Collections.Generic.Queue<>

System.Linq.Enumerable

System.Text.StringBuilder
System.Text.RegularExpressions.Regex;

System.Timers.Timer;

System.Globalization.Calendar;


System.Xml.Serialization.XmlElementAttribute
System.Xml.Serialization.XmlAttributeAttribute
System.Xml.Serialization.XmlArrayAttribute
System.Xml.Serialization.XmlArrayItemAttribute
System.Xml.Serialization.XmlAnyAttributeAttribute
System.Xml.Serialization.XmlAnyElementAttribute
System.Xml.Serialization.XmlAnyElementAttributes
System.Xml.Serialization.XmlArrayItemAttributes
System.Xml.Serialization.XmlAttributeEventArgs
System.Xml.Serialization.XmlAttributeOverrides
System.Xml.Serialization.XmlAttributes
System.Xml.Serialization.XmlChoiceIdentifierAttribute
System.Xml.Serialization.XmlElementAttributes
System.Xml.Serialization.XmlElementEventArgs
System.Xml.Serialization.XmlEnumAttribute
System.Xml.Serialization.XmlIgnoreAttribute
System.Xml.Serialization.XmlIncludeAttribute
System.Xml.Serialization.XmlRootAttribute
System.Xml.Serialization.XmlTextAttribute
System.Xml.Serialization.XmlTypeAttribute


Sandbox.ModAPI.Ingame.IMyCubeBlock
Sandbox.ModAPI.IMySession
Sandbox.ModAPI.Interfaces.IMyCameraController
Sandbox.Common.MySessionComponentBase
Sandbox.Common.ObjectBuilders.MyObjectBuilder_Base
Sandbox.Common.ObjectBuilders.Voxels.MyObjectBuilder_VoxelMap
Sandbox.Common.Components.MyComponentBase
Sandbox.Common.Localization.MyTextsWrapper
Sandbox.Definitions.MyDefinitionId
VRageMath.Vector3
VRage.Voxels.MyStorageDataCache
VRage.MyFixedPoint
Sandbox.Common.ObjectBuilders.VRageData.SerializableVector3
VRage.Collections.ListReader<>
Sandbox.Common.ObjectBuilders.Definitions.SerializableDefinitionId
VRage.Common.Utils.MyStringId

Details
Few things you might find yourself fiting with.
First of them will be our internal object names.
Object builder - storing structure used for serializing and deserializing object states.
CubeGrid - Large/small ship, station.
SlimBlock - base for all blocks used for memory optimization. Armors, catwalks, ramps and similar have only this.
FatBlock - more complex blocks with some logic or functionality - Door, Refinery, Piston and others have this in addition to
Modding API basics video
We have released a youtube video explaining the basics of API, visit this link for more info https://www.youtube.com/watch?v=gAh1bNfRLPw&list=UUiIu5_NeaCkv3Nt8R5u7pNg
< >
67 Comments
Adreden Feb 10, 2016 @ 5:23pm 
@TEEN , I agree Update this. Also the other page modding--source-code . html. So many broken links.
DropBearGamer Oct 18, 2015 @ 1:45pm 
i subscribed to that BeaconHello and the missions and i can't &*%^ find it anywhere on my computer. Where the heck are they saved???
TEEN Sep 19, 2015 @ 2:47pm 
Update this!
DranKof Sep 18, 2015 @ 6:37pm 
There's no more VRage.common. It was probably replaced with VRage.Game ?

The [bracketed label] at the top can't be formed correctly without looking at other mods for correct examples.

The position section with Forward and Up don't seem to work. They are of two different location/3d data types now that don't implicitly convert and I can't seem to intellisense a conversion.

If there's anything else that may be causing it to not work, I'm not sure it is.
[FP] Banshee Aug 7, 2015 @ 7:37pm 
This needs to be updated, the video is completely useless now with the most recent updates.
sudoroot Jun 25, 2015 @ 8:51am 
Please update guide! Information was obsolete!
fuze Mar 24, 2015 @ 7:07am 
full documentation or riot!
Szymekk Dec 25, 2014 @ 1:40pm 
I want full documentation
[FP] Banshee Nov 27, 2014 @ 8:22am 
@nennog it's written in C#
Manyack Nov 27, 2014 @ 4:59am 
I urge anyone who does not mind or even the developers of Space Engineers (if I knew where to write a letter / petition would) help us to understand Spanish speaking guides creating these mods, or users with knowledge on the subject can do so in Spanish-speaking community to offer ideas and mods that come to mind. A tutorial where you see that the mods and you need to carry them out are implemented, because I have knowledge of 3D design without tools or configuration to implement my designs to suit. A tutorial on youtube, a written guide, a translation of that where I make this comment, something, but someone please assist Spanish-speaking Hispanic to understand what is the process for creating mods for Space engineers.

Thanks for your attention and best regards. (sorry for my english is google traductor).

P.D: I hope someone hears my request.