Overview
This guide will tell you how to start with our new Modding API and get it in your game
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 [link]
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 : [link]
– Script: [link]
Where to put files
In your Space engineers Mods folder create a new folder with name of your mod with structure like this
ModsYourModDataScriptsYourScript
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