Mod Scripting
Before proceeding
First you need to know at least the basics of the C# language. It is too vast and complicated to teach in this wiki, however C# is a very widely used programming language so you will have no trouble finding tutorials in any format you wish (text, video, practice, etc) on the internet.
Once you have that down, be sure to use a proper IDE: Setting up a Modding Environment - C# programming
Where to place scripts
Mod scripts must reside in: <ModName>\Data\Scripts\<ModName>\
That last ModName folder is very important.
Every file or folder directly in the Scripts folder will be compiled as a separate assembly, which will cause your scripts to not see each other and can even break things in hidden ways; which is why it's also recommended to have only one folder directly in Scripts. You can however have as many subfolders as you like after your ModName folder.
The next thing: it's recommended that the name of that folder is the same as the mod name, because it's also used for the assembly name, and for the folder name in mod or world storage. If you've ever used any mod that has its own storage you may have seen in %appdata%\SpaceEngineers\Storage\ that they have a format like <workshopId>.sbm_<SomeName> - that last SomeName is their folder name from Scripts, and because the number is so bad at identifying the mod, having that second thing be the mod name helps a lot.
How scripts are used
The game only cares about .cs files, which it will compile on its own while checking the code against the whitelist -- because there are a lot of powerful things in C#/.NET that would not be safe to run.
You cannot publish a .dll/.exe, and even if you did, the game wouldn't use them anyway.
For security reasons, mods on the workshop are intended to only have access to the game and limited access to game-specific folders.
What the whitelist looks like: Mod Script Whitelist
How to find things
There is an official ModAPI documentation site: https://keensoftwarehouse.github.io/SpaceEngineersModAPI/api/index.html
A few issues with that however:
- It's not complete, there are certain types that are individually whitelisted which do not show up there (for example
MyGunBase). - It does not list the whitelisted C#/.NET types.
Both of these things can be alleviated by not relying on that site for whitelist checking, but only as a general guide. The VS setup page does include an analyzer that will check the whitelist and alert you.
Because the API has a severe lack of documentation on various methods, you will find yourself needing to dig inside the source of the methods to find out more.
To do that you can use ILspy or dnSpy (see Modding Tools - Misc and Shared) which involve opening all dll files from the game's Bin64 folder and then searching and/or using right-click -> Analyze on fields/properties/methods/etc to see where they're used/read to trace-back code.
Be warned
- Avoid
usingfor namespaces containingIngame: that will generally lead to ambiguity errors.
Even if you don't have the modAPI usings in your script, the ambiguity errors can still happen because the game injects some modAPI usings before compiling (for backwards compatibility).
If you do need a type from the Ingame namespaces, best to use an alias:
using MyShipConnectorStatus = Sandbox.ModAPI.Ingame.MyShipConnectorStatus; (left side name can be invented too)
- The game injects a Mod profiler into every method (including properties' get/set if they're not automatic). This requires you to be careful about hot paths.
Where next
- Gamelogic and Session component examples - these are the most commonly-used entry points; read comments in both as they contain important info.
- Various other code examples