Difference between revisions of "Programming Guide"

From Space Engineers Wiki
Jump to: navigation, search
(Added info from http://steamcommunity.com/sharedfiles/filedetails/?id=360966557 to match the /In-game_coding/ru page. Still needs formatting applied to rest of article.)
 
 
(43 intermediate revisions by 14 users not shown)
Line 1: Line 1:
==Known Limitations==
+
Programming in Space Engineers is done with the [[Programmable Block]] which can be given scripts written in C# (pronounced C Sharp). This can be used to make autonomous mining drones, long-range player-killing torpedoes, automated welding arms for ship construction and much more.
Below is a list of the known limitations that we are aware of and the possible workarounds for each of them:
 
  
===Foreach not working at 64- bit===
+
There is documentation on Github which is maintained by certain contributors and is very useful if you are already familiar with C# in general. https://github.com/malware-dev/MDK-SE/wiki
''Problem'':
 
Currently using of foreach loop inside script will cause “bad program exception” at some configurations and prevent script from running. We are working of fixing this issue.  
 
  
''Workaround'':
+
== Introduction ==
All our interfaces used in in-game scripting are using lists as collections. Please use For loop for iteration across these lists
+
=== Editor access ===
 +
Only one player can edit the same script at a time. If someone else has an editor for the current block open and someone else tries to open that block's editor, a notification will be shown that the editor is already open.
  
===Lambda functions not working===
+
=== Main method ===
''Problem'':
 
Currently lambda functions are not supported, if you use them in script, exception will be thrown and script will not run.
 
  
''Workaround'':
+
When the editor is opened for first time on a block, the Program constructor and the Main method are present inside the code editor. The code in the editor becomes the body of the Program class definition.  
Please use method instead of lambda function if possible.
 
  
===User defined static variables and methods not working===
+
This Main method is the entry point that will be called when executing script. If Main method is removed / renamed, the script will not run and you will be notified in the programmable block details area.  
''Problem'':
 
Currently using user defined static members or methods will cause script to throw exception and the script will not run.
 
  
''Workaround'':
+
Custom methods/variables can be defined and used, but only the Main method will be called by the program.
Please don’t define static methods or variables.
 
  
===User defined variables are not saved===
+
=== Variable lifetime and scoping ===
''Problem'':  
+
There are two types of variables for scripting:
None of user defined variables inside the script is saved, therefore after loading the game they are reset into their default values.
+
;Local (inside the methods) : these variables will keep their value only during execution of a method. Value will be “lost” when the method ends.
 +
;Global (outside the methods) : these variables will keep their values during the lifetime of script. For example, if the variable needs to keep its value between separate runs of the script, it needs to be defined outside the methods.
  
Workaround:
+
After pressing “Remember & Exit” or “Remember” buttons, the previous script will be overwritten and all Global variables will be lost.
None.
 
  
==GUI Overview==
+
All variables, local and global except for the built-in Storage variable will lose their value or return to their default value when recompiling the code and between saved game loads.
===Programmable block===
+
The Storage variable is unique in that it will store the data as a string for use between saved sessions and recompile.
  
The programmable block terminal panel screen currently contains two buttons:
+
=== Compiling ===
 +
When the “Check code” button is pressed, the code will be compiled and the result of the compilation will be shown.
 +
There are two steps of the compilation process:
 +
First the code inside editor is compiled by c# compiler for language errors.
 +
If there are any errors during compilation the following dialog is shown:
 +
It this case “aaa” string is placed before Main method. This is the wrong language construction and the compilation failed.
 +
In the error dialog the Line number error and description of the error is shown.
  
''Edit'' – it will open the editor for editing scripts and the ability to save/load scripts from and to disk.
+
After compilation, the code is checked for usage of disallowed namespaces and types. In case that check fails,
Also, you can upload your scripts to workshop and download subscribed scripts.
+
the following dialog is shown:
 
+
In this case System.IO.Directory was used to delete some directory. This is forbidden and error is shown that “Not allowed type was used in script”.
''Run'' – it will run the script that was remembered in editor. It will run the script only once. However this button is terminal action, so you can attach it to sensor, timer block, and button or add it to toolbar.
 
 
 
[[File:Steamworkshop webupload previewfile 360966557 preview.jpg|500px]]
 
 
 
''Details section'' – In this area the script exception will be shown (if any will occur)
 
 
 
===Editor===
 
 
 
[[File:Steamworkshop webupload previewfile 360966557 preview (1).jpg|500px]]
 
 
 
Code editor contains these buttons:
 
''Help'' – it will open the help guide inside the game.
 
''Check Code'' – it will check the code for code mistakes and also check if used code isn’t forbidden.
 
''Remember & Exit'' – it will save the code for execution, close editor screen and returns to terminal panel.
 
''Remember code'' – it will save code for execution and leave editor open.
 
''Browse Workshop'' – it will open a window for script management, you can save/load scripts from disk , upload scripts to workshop and download subscribed scripts.
 
''Line counter'' – it shows current line number and total number of lines in code
 
 
 
===Browse Workshop===
 
 
 
[[File:Browse workshop.jpg|200px]]
 
 
 
This screen is similar to blueprint screen and contains these buttons :
 
''Ok'' – it will load the selected script into the editor and close the screen
 
''Cancel'' – it will close the screen (no changes to code in editor)
 
''Details'' – it will open the "details" screen, where you can see description of script
 
''Rename (only for local scripts)'' – it will rename the selected script, if you try to rename to existing script, the game will ask you if you want to overwrite the existing script.
 
''Delete (only for local scripts)'' – it will ask you if you really want to delete the script, after the confirmation script will be deleted.
 
''Create from editor''– it will create new script with default name Script_XX it starts with 0 and if the script with the selected name already exists, it will increment the value. E.g. first there will be Script_0 then Script_1 etc…
 
''Replace from editor (only for local scripts)'' – it will replace (after user confirmation) the selected script with script from the editor.
 
''Refresh Scripts'' – will reload the local and subscribed script list
 
 
 
===Details (local script)===
 
 
 
[[File:Details (local script).jpg|500px]]
 
  
This screen will show up when you press details for local script and contains the following buttons:
+
If compilation and checks pass, a dialog is shown, confirming the checks passed, and the code is saved.
''Rename'' – it will rename the selected script, if you try to rename to existing script, the game will ask if you want to overwrite the existing script.
 
''Delete'' – it will ask you if you want to delete the script, after confirmation script will be deleted.
 
''Publish'' – it will publish the script into workshop and show the workshop page with the script.
 
''Browse Workshop'' – it will open the workshop screen to browse and subscribe scripts.
 
''Close'' – it will close the screen
 
  
===Details (workshop script)===
+
=== Script execution ===
 +
Script can be triggered by the following means:
  
This screen will show up when you press details for script from workshop and it contains these buttons:
+
1. By pressing "Run" button in terminal properties of programmable block.
Open in Workshop – it will open the current script workshop page.
 
Close – it will close the screen
 
Programming Guide
 
Introduction
 
  
Editor access
+
2. By assigning terminal action and manually pressing the action button (1-9) while controlling the grid using cockpit, control station or remote control.
Only one player can edit same script at time. If someone else have open editor for current block and someone else will try to open editor, notification will be shown that editor is already open.
 
  
Main method
+
3. By pressing button on a button panel with assigned action "Run".
When editor is opened for first time, void Main() method is present inside code editor.
 
This is entry point that will be called when executing script. If Main method is removed / renamed, script will not run and you will be notified in programmable block details area.
 
Custom methods/variables can be defined and used, but only Main method will be called by script.
 
  
Variables life
+
4. By a timer with assigned action "Run".
There are two types of variables for script:
 
Local (inside the methods) – these variables will keep theirs value only during execution of method.
 
Value will be “lost” when method ends.
 
Global (outside the methods) - these variables will keep theirs values during lifetime of script. E.g.
 
If variable needs to keep value between separate runs of program ,it needs to be defined outside the methods.
 
After pressing “Remember&Exit” or “Remember” buttons, previous script will be overwritten and all Global variables will be lost.
 
  
Compiling
+
5. By another script in another programmable block in the same grid.
When “Check code” button is pressed, code will be compiled and result of compilation will be shown.
 
There are two steps of compilation process:
 
First code inside editor is compiled by c# compiler for language errors.
 
If there is any error during compilation following dialog is shown:
 
It this case “aaa” string is placed before Main method. This is wrong language construction and compilation failed.
 
In error dialog Line number error and description of the error is shown.
 
  
After compilation, code is check for usage of not allowed namespaces and types. In case that check fails,
+
6. By antenna with assigned programmable block, when recieved message from another antenna. (see [[Antenna#Programming]])
Following dialog is shown:
 
In this case System.IO.Directory was used to delete some directory. This is forbidden and error is shown that “Not allowed type was used in script”.
 
  
If compilation and check passes following dialog is shown:
+
7. By the script itself, by assigning a value to Runtime.UpdateFrequency variable. In this case, '''no argument can be specified''', however, you can use the following Main method signature: void Main(string argument, UpdateType updateSource) to gain acces to the information about what exactly triggered the script and so make the script "know" if it was triggered by Update1, Update10, Update100 events or manually or whatever event was the reason of trigger execution.
This means that code doesn’t contain any language errors or not allowed methods.
 
  
Script execution
 
When “Run” button is pressed or “Run” is assigned as terminal action, script is executed. Currently “Run” needs to be called manually e.g. user need to click on “Run” button or attach it as terminal action.
 
 
Script is executed only on server even if it’s triggered from client. If there is any exception during script execution, all clients will be notified in programmable block details area about failure.
 
Script is executed only on server even if it’s triggered from client. If there is any exception during script execution, all clients will be notified in programmable block details area about failure.
 
In case of exception during script execution, script will not run again unless User opens editor and change script.
 
In case of exception during script execution, script will not run again unless User opens editor and change script.
  
Counting of instructions
+
=== Counting of instructions ===
Every time script is executed, every instruction of script is counted. If script executes more instruction than limit, execution is stopped and user is notified that script is too complex for execution. This prevents scripts to “freeze” game.
+
Every time script is executed, every instruction of script is counted. If script executes more instruction than limit, execution is stopped and user is notified that script is too complex for execution. This prevents scripts from freezing the game. It is similar to the idea of a stack overflow exception, and is unrealistically high. If you get this error, it is more likely you have an infinite loop than that you are trying to do too much. The count can be accessed on <code>this.Runtime.CurrentInstructionCount</code> to narrow down the problem.
 +
 
 +
=== Whitelist ===
 +
The types and classes allowed in scripts are restricted. Refer to the [[Scripting Whitelist]] to see what you are allowed to use.
  
Available interfaces
+
== Available interfaces ==
  
Possible actions
+
=== Possible Actions ===
 
Currently only terminal actions can be triggered inside scripts. User can access terminal system for grid on which programmable block is located and trigger any terminal action on any block at grid.
 
Currently only terminal actions can be triggered inside scripts. User can access terminal system for grid on which programmable block is located and trigger any terminal action on any block at grid.
 +
:* [[Programming_Guide/API_List|API List]]
  
GridTerminalSystem variable
+
=== Block Classes (Action List) ===
Currently only following “built-in” variable that user can use: GridTerminalSystem. This is entry point of entire grid terminal system.
+
:* [[Programming_Guide/Action_List|Block Action List]]
It has following methods available:
 
List<IMyTerminalBlock> Blocks{get;}
 
List<IMyBlockGroup> BlockGroups { get; }
 
void GetBlocksOfType<T>(List<IMyTerminalBlock> blocks, Func<IMyTerminalBlock, bool> collect = null);
 
void SearchBlocksOfName(string name,List<IMyTerminalBlock> blocks, Func<IMyTerminalBlock, bool> collect = null);
 
IMyTerminalBlock GetBlockWithName(string name);
 
With these methods all terminal blocks of grid can be collected.
 
  
Blocks property will get all block of grid terminal, this method internally allocates new memory.
+
=== Same block class for different SubTypeID ===
BlockGroups will get all groups of grid terminal, this method internally allocates new memory
+
Some blocks have the same parent (e.g. <TypeId> in cubeblocks.sbc) and differs only by subtype (e.g. <SubtypeId>). This means there is no distinction between these blocks in code.
GetBlocksOfType will get all blocks of given type.
 
SearchBlocksOfName method will fulltext search between all blocks and returns block that contains searched string , search is case insensitive.
 
GetBlockWithName method will get first block with exact name as provided , search is case sensitive.
 
  
Func<IMyTerminalBlock, bool> collect method can be used for defining search condition within search. E.g. Collect method for IMyRadioAntenna can define search function to search only for turned on antennas or antennas with specific range.
+
Example of these blocks is the Cargo Container: there are 3 types of cargo containers in the game: small, medium and large. These three types differ only by the Subtype and Type is the same for them e.g. large cargo container id is:
  
IMyCubeBlock
+
<Id>
IMyCubeBlock is base class for every terminal block. It has following Properties and methods:
+
  <TypeId>CargoContainer</TypeId>
bool IsBeingHacked { get; }
+
  <SubtypeId>LargeBlockLargeContainer</SubtypeId>
bool IsFunctional { get; }
+
</Id>
bool IsWorking { get; }
 
VRageMath.Vector3I Position { get; }
 
  
IsFunctional property tells if current block is constructed to the level it can operate
+
Medium is:
IsWorking property tells if current block is powered
 
 
IMyTerminalBlock
 
IMyTerminalBlock is base class for every terminal block, all of the block will have following properties and methods:
 
  
string CustomName
+
<Id>
string CustomNameWithFaction
+
  <TypeId>CargoContainer</TypeId>
string DetailedInfo
+
  <SubtypeId>SmallBlockMediumContainer</SubtypeId>
bool HasLocalPlayerAccess()
+
</Id>
bool HasPlayerAccess(long playerId)
 
void RequestShowOnHUD(bool enable)
 
void SetCustomName(string text)
 
void SetCustomName(StringBuilder text)
 
bool ShowOnHUD
 
void GetActions(List<Sandbox.ModAPI.Interfaces.ITerminalAction> resultList, Func<Sandbox.ModAPI.Interfaces.ITerminalAction, bool> collect = null);
 
void SearchActionsOfName(string name,List<Sandbox.ModAPI.Interfaces.ITerminalAction> resultList, Func<Sandbox.ModAPI.Interfaces.ITerminalAction, bool> collect = null);
 
Sandbox.ModAPI.Interfaces.ITerminalAction GetActionWithName(string name);
 
  
GetActions method will get all action available for current block.
+
And small is:
SearchActionsOfName method will fulltext search between all blocks actions and returns actions that contains searched string e.g. if block has actions : OnOff ,OnOff_On ,OnOff_Off
 
 
 
SearchActionsOfName with “OnOff” returns all actions SearchActionsOfName with _On will return only “OnOff_On”, searching with “On” will return all actions, search is case insensitive.
 
 
 
GetActionWithName method will get first action with exact name as provided , search is case sensitive.
 
 
 
ITerminalAction
 
ITerminal action is representation of concrete action that can be triggered. It has following properties and methods:
 
string Id { get; }
 
StringBuilder Name { get; }
 
void Apply(Sandbox.ModAPI.Ingame.IMyCubeBlock block);
 
 
 
Id is Id of action e.g. OnOff, OnOff_On
 
Name is name of the action shown in UI e.g. Toggle block On/Off ,Toggle block On
 
Apply will apply action for given block (you need to provide block from which you took actions)
 
 
 
IMyFunctionalBlock
 
IMyFunctionalBlock is base class for every block that can be turned on or off, it’s derived from IMyTerminal block e.g. every Functional block is Terminal block but not all terminal blocks can be turned on or off.
 
It has one Property:
 
bool Enabled
 
This property indicates if block is turned on or off by user.
 
Terminal block and action name list - 1/3
 
Disclaimer
 
All terminal blocks have the following properties:
 
Interface name: this name is the name of the block in code, it can differ from the name as displayed in the building screen. E.g. Antenna interface name is IMyRadioAntenna - you need to use this interface if you want to get all antennas.
 
 
 
Parent: this is parent of the block (all blocks have IMyTerminalBlock as parent), this can be used for getting type of blocks instead of concrete block type. E.g. if you want to get all lights in grid you will use IMyLightingBlock, if you want only interior light you can use IMyInteriorLight.
 
 
 
Field: this is read only field available for block e.g. for IMyBeacon you can get Radius property. Based on this property you can increase/decrease radius of beacon.
 
 
 
Actions: these are all available actions for block with their names in game, so if you want to increase broadcast radius for antenna, you need to execute DecreaseRadius action for block.
 
  
Same block class for different SubTypeID
+
<Id>
Some blocks have same parent (e.g. <TypeId> in cubeblocks.sbc) and differs only by subtype (e.g. <SubtypeId>). This means there is no distinction between these block in code.
+
  <TypeId>CargoContainer</TypeId>
Example of these blocks is the Cargo Container: there are 3 types of cargo containers in the game: small, medium and large. These three types differ only by subtype and Type is same for them e.g. large cargo container id is:
+
  <SubtypeId>LargeBlockSmallContainer</SubtypeId>
<Id>
+
</Id>
<TypeId>CargoContainer</TypeId>
 
<SubtypeId>LargeBlockLargeContainer</SubtypeId>
 
</Id>
 
Medium is:
 
<Id>
 
<TypeId>CargoContainer</TypeId>
 
<SubtypeId>SmallBlockMediumContainer</SubtypeId>
 
</Id>
 
And small is:
 
<Id>
 
<TypeId>CargoContainer</TypeId>
 
<SubtypeId>LargeBlockSmallContainer</SubtypeId>
 
</Id>
 
  
 
In this case there is only one class IMyCargoContainer for all types of cargo containers.
 
In this case there is only one class IMyCargoContainer for all types of cargo containers.
  
Antenna
+
== Example programs ==
Interface name: IMyRadioAntenna
 
Parent: IMyFunctionalBlock
 
Fields: float Radius
 
Actions:
 
OnOff -> Toggle block On/Off
 
OnOff_On -> Toggle block On
 
OnOff_Off -> Toggle block Off
 
IncreaseRadius -> Increase Broadcast radius
 
DecreaseRadius -> Decrease Broadcast radius
 
 
 
Arc furnace
 
Interface name: IMyRefinery
 
Parent: IMyProductionBlock
 
Parent: IMyFunctionalBlock
 
Fields: bool UseConveyorSystem
 
Actions:
 
OnOff -> Toggle block On/Off
 
OnOff_On -> Toggle block On
 
OnOff_Off -> Toggle block Off
 
UseConveyor -> Use Conveyor System On/Off
 
 
 
Artificial Mass
 
Interface name: IMyVirtualMass
 
Parent: IMyFunctionalBlock
 
Fields: None
 
Actions:
 
OnOff -> Toggle block On/Off
 
OnOff_On -> Toggle block On
 
OnOff_Off -> Toggle block Off
 
 
 
Assembler
 
Interface name: IMyAssembler
 
Parent: IMyProductionBlock
 
Parent: IMyFunctionalBlock
 
Fields: bool UseConveyorSystem
 
Actions:
 
OnOff -> Toggle block On/Off
 
OnOff_On -> Toggle block On
 
OnOff_Off -> Toggle block Off
 
UseConveyor -> Use Conveyor System On/Off
 
 
 
Battery
 
Interface name: IMyBatteryBlock
 
Parent: IMyFunctionalBlock
 
Fields: bool HasCapacityRemaining
 
Actions:
 
OnOff -> Toggle block On/Off
 
OnOff_On -> Toggle block On
 
OnOff_Off -> Toggle block Off
 
Recharge -> Recharge On/Off
 
 
 
Beacon
 
Interface name: IMyBeacon
 
Parent: IMyFunctionalBlock
 
Fields: float Radius
 
Actions:
 
OnOff -> Toggle block On/Off
 
OnOff_On -> Toggle block On
 
OnOff_Off -> Toggle block Off
 
IncreaseRadius -> Increase Broadcast radius
 
DecreaseRadius -> Decrease Broadcast radius
 
 
 
Button Panel
 
Interface name: IMyButtonPanel
 
Fields: bool AnyoneCanUse
 
Actions:
 
AnyoneCanUse -> Anyone Can Use On/Off
 
 
 
Camera
 
Interface name: IMyCameraBlock
 
Parent: IMyFunctionalBlock
 
Fields: None
 
Actions:
 
OnOff -> Toggle block On/Off
 
OnOff_On -> Toggle block On
 
OnOff_Off -> Toggle block Off
 
View -> View
 
 
 
Cockpit
 
Interface name: IMyCockpit
 
Parent: IMyShipController
 
Fields:
 
bool ControlWheels
 
bool ControlThrusters
 
bool HandBrake
 
bool DampenersOverride
 
Actions:
 
ControlThrusters -> Control thrusters On/Off
 
ControlWheels -> Control wheels On/Off
 
HandBrake -> Handbrake On/Off
 
DampenersOverride -> Inertia dampeners On/Off
 
 
 
Collector
 
Interface name: IMyCollector
 
Parent: IMyFunctionalBlock
 
Fields: bool UseConveyorSystem
 
Actions:
 
OnOff -> Toggle block On/Off
 
OnOff_On -> Toggle block On
 
OnOff_Off -> Toggle block Off
 
UseConveyor -> Use Conveyor System On/Off
 
 
 
Connector
 
Interface name: IMyShipConnector
 
Parent: IMyFunctionalBlock
 
Fields:
 
bool ThrowOut
 
bool CollectAll
 
bool IsLocked
 
Actions:
 
OnOff -> Toggle block On/Off
 
OnOff_On -> Toggle block On
 
OnOff_Off -> Toggle block Off
 
ThrowOut -> Throw Out On/Off
 
CollectAll -> Collect All On/Off
 
SwitchLock -> Switch lock
 
 
 
Control Panel
 
Interface name: IMyControlPanel
 
Fields: None
 
Actions: None
 
 
 
Control Station
 
Interface name: IMyCockpit
 
Parent: IMyShipController
 
Fields:
 
bool ControlWheels
 
bool ControlThrusters
 
bool HandBrake
 
bool DampenersOverride
 
Actions:
 
ControlThrusters -> Control thrusters On/Off
 
ControlWheels -> Control wheels On/Off
 
HandBrake -> Handbrake On/Off
 
DampenersOverride -> Inertia dampeners On/Off
 
 
 
Door
 
Interface name: IMyDoor
 
Parent: IMyFunctionalBlock
 
Fields: bool Open
 
Actions:
 
OnOff -> Toggle block On/Off
 
OnOff_On -> Toggle block On
 
OnOff_Off -> Toggle block Off
 
Open -> Open/Closed
 
Open_On -> Open
 
Open_Off -> Closed
 
 
 
Drill
 
Interface name: IMyShipDrill
 
Parent: IMyFunctionalBlock
 
Fields: bool UseConveyorSystem
 
Actions:
 
OnOff -> Toggle block On/Off
 
OnOff_On -> Toggle block On
 
OnOff_Off -> Toggle block Off
 
UseConveyor -> Use Conveyor System On/Off
 
 
 
Flight Seat
 
Interface name: IMyCockpit
 
Parent: IMyShipController
 
Fields:
 
bool ControlWheels
 
bool ControlThrusters
 
bool HandBrake
 
bool DampenersOverride
 
Actions:
 
ControlThrusters -> Control thrusters On/Off
 
ControlWheels -> Control wheels On/Off
 
HandBrake -> Handbrake On/Off
 
DampenersOverride -> Inertia dampeners On/Off
 
 
 
Gatling Turret
 
Interface name: IMyLargeGatlingTurret
 
Parent: IMyLargeConveyorTurretBase
 
Parent: IMyLargeTurretBase
 
Parent: IMyFunctionalBlock
 
Fields:
 
bool UseConveyorSystem
 
bool CanControl
 
float Range
 
Actions:
 
OnOff -> Toggle block On/Off
 
OnOff_On -> Toggle block On
 
OnOff_Off -> Toggle block Off
 
Control -> Control
 
IncreaseRange -> Increase Radius
 
DecreaseRange -> Decrease Radius
 
UseConveyor -> Use Conveyor System On/Off
 
 
 
Gravity Generator
 
Interface name: IMyGravityGenerator
 
Parent: IMyGravityGeneratorBase
 
Parent: IMyFunctionalBlock
 
Fields:
 
float FieldWidth
 
float FieldHeight
 
float FieldDepth
 
float Gravity
 
Actions:
 
OnOff -> Toggle block On/Off
 
OnOff_On -> Toggle block On
 
OnOff_Off -> Toggle block Off
 
IncreaseWidth -> Increase Field width
 
DecreaseWidth -> Decrease Field width
 
IncreaseHeight -> Increase Field height
 
DecreaseHeight -> Decrease Field height
 
IncreaseDepth -> Increase Field depth
 
DecreaseDepth -> Decrease Field depth
 
IncreaseGravity -> Increase Acceleration
 
DecreaseGravity -> Decrease Acceleration
 
 
 
Grinder
 
Interface name: IMyShipGrinder
 
Parent: IMyShipToolBase
 
Parent: IMyFunctionalBlock
 
Fields: None
 
Actions:
 
OnOff -> Toggle block On/Off
 
OnOff_On -> Toggle block On
 
OnOff_Off -> Toggle block Off
 
UseConveyor -> Use Conveyor System On/Off
 
 
 
Gyroscope
 
Interface name: IMyGyro
 
Parent: IMyFunctionalBlock
 
Fields:
 
float GyroPower
 
bool GyroOverride
 
float Yaw
 
float Pitch
 
float Roll
 
Actions:
 
OnOff -> Toggle block On/Off
 
OnOff_On -> Toggle block On
 
OnOff_Off -> Toggle block Off
 
IncreasePower -> Increase Power
 
DecreasePower -> Decrease Power
 
Override -> Override controls On/Off
 
IncreaseYaw -> Increase Yaw override
 
DecreaseYaw -> Decrease Yaw override
 
IncreasePitch -> Increase Pitch override
 
DecreasePitch -> Decrease Pitch override
 
IncreaseRoll -> Increase Roll override
 
DecreaseRoll -> Decrease Roll override
 
Terminal block and action name list - 2/3
 
Interior Light
 
Interface name: IMyInteriorLight
 
Parent: IMyLightingBlock
 
Parent: IMyFunctionalBlock
 
Fields:
 
float Radius
 
float Intensity
 
float BlinkIntervalSeconds
 
float BlinkLenght
 
float BlinkOffset
 
Actions:
 
OnOff -> Toggle block On/Off
 
OnOff_On -> Toggle block On
 
OnOff_Off -> Toggle block Off
 
IncreaseRadius -> Increase Radius
 
DecreaseRadius -> Decrease Radius
 
IncreaseBlink Interval -> Increase Blink Interval
 
DecreaseBlink Interval -> Decrease Blink Interval
 
IncreaseBlink Lenght -> Increase Blink Length
 
DecreaseBlink Lenght -> Decrease Blink Length
 
IncreaseBlink Offset -> Increase Blink Offset
 
DecreaseBlink Offset -> Decrease Blink Offset
 
 
 
Interior Turret
 
Interface name: IMyLargeInteriorTurret
 
Parent: IMyLargeTurretBase
 
Parent: IMyFunctionalBlock
 
Fields:
 
bool CanControl
 
float Range
 
Actions:
 
OnOff -> Toggle block On/Off
 
OnOff_On -> Toggle block On
 
OnOff_Off -> Toggle block Off
 
Control -> Control
 
IncreaseRange -> Increase Radius
 
DecreaseRange -> Decrease Radius
 
 
 
Landing Gear
 
Interface name: IMyLandingGear
 
Parent: IMyFunctionalBlock
 
Fields:
 
float BreakForce
 
Actions:
 
OnOff -> Toggle block On/Off
 
OnOff_On -> Toggle block On
 
OnOff_Off -> Toggle block Off
 
Lock -> Lock
 
Unlock -> Unlock
 
SwitchLock -> Switch lock
 
Autolock -> Autolock On/Off
 
IncreaseBreakForce -> Increase Break Force
 
DecreaseBreakForce -> Decrease Break Force
 
 
 
Small Cargo Container
 
Interface name: IMyCargoContainer
 
Fields: None
 
Actions: None
 
 
 
Medium Cargo Container
 
Interface name: IMyCargoContainer
 
Fields: None
 
Actions:None
 
 
 
Large Cargo Container
 
Interface name: IMyCargoContainer
 
Fields: None
 
Actions: None
 
 
 
Small Reactor
 
Interface name: IMyReactor
 
Parent: IMyFunctionalBlock
 
Fields:
 
bool UseConveyorSystem
 
Actions:
 
OnOff -> Toggle block On/Off
 
OnOff_On -> Toggle block On
 
OnOff_Off -> Toggle block Off
 
UseConveyor -> Use Conveyor System On/Off
 
 
 
Large Reactor
 
Interface name: IMyReactor
 
Parent: IMyFunctionalBlock
 
Fields: bool UseConveyorSystem
 
Actions:
 
OnOff -> Toggle block On/Off
 
OnOff_On -> Toggle block On
 
OnOff_Off -> Toggle block Off
 
UseConveyor -> Use Conveyor System On/Off
 
 
 
Small Thruster
 
Interface name: IMyThrust
 
Parent: IMyFunctionalBlock
 
Fields: float ThrustOverride
 
Actions:
 
OnOff -> Toggle block On/Off
 
OnOff_On -> Toggle block On
 
OnOff_Off -> Toggle block Off
 
IncreaseOverride -> Increase Thrust override
 
DecreaseOverride -> Decrease Thrust override
 
 
 
Large Thruster
 
Interface name: IMyThrust
 
Parent: IMyFunctionalBlock
 
Fields: float ThrustOverride
 
Actions:
 
OnOff -> Toggle block On/Off
 
OnOff_On -> Toggle block On
 
OnOff_Off -> Toggle block Off
 
IncreaseOverride -> Increase Thrust override
 
DecreaseOverride -> Decrease Thrust override
 
 
 
Medical Room
 
Interface name: IMyMedicalRoom
 
Parent: IMyFunctionalBlock
 
Fields: None
 
Actions:
 
OnOff -> Toggle block On/Off
 
OnOff_On -> Toggle block On
 
OnOff_Off -> Toggle block Off
 
 
 
Merge Block
 
Interface name: IMyShipMergeBlock
 
Parent: IMyFunctionalBlock
 
Fields: None
 
Actions:
 
OnOff -> Toggle block On/Off
 
OnOff_On -> Toggle block On
 
OnOff_Off -> Toggle block Off
 
 
 
Missile Turret
 
Interface name: IMyLargeMissileTurret
 
Parent: IMyLargeConveyorTurretBase
 
Parent: IMyLargeTurretBase
 
Parent: IMyFunctionalBlock
 
Fields:
 
bool UseConveyorSystem
 
bool CanControl
 
float Range
 
Actions:
 
OnOff -> Toggle block On/Off
 
OnOff_On -> Toggle block On
 
OnOff_Off -> Toggle block Off
 
Control -> Control
 
IncreaseRange -> Increase Radius
 
DecreaseRange -> Decrease Radius
 
UseConveyor -> Use Conveyor System On/Of
 
 
 
Ore Detector
 
Interace name: IMyOreDetector
 
Parent: IMyFunctionalBlock
 
Fields:
 
float Range
 
bool BroadcastUsingAntennas
 
Actions:
 
OnOff -> Toggle block On/Off
 
OnOff_On -> Toggle block On
 
OnOff_Off -> Toggle block Off
 
 
 
Passenger Seat
 
Interface name: IMyCockpit
 
Parent: IMyShipController
 
Fields:
 
bool ControlWheels
 
bool ControlThrusters
 
bool HandBrake
 
bool DampenersOverride
 
Actions:
 
ControlThrusters -> Control thrusters On/Off
 
ControlWheels -> Control wheels On/Off
 
HandBrake -> Handbrake On/Off
 
DampenersOverride -> Inertia dampeners On/Off
 
 
 
Piston
 
Interface name: IMyPistonBase
 
Parent: IMyFunctionalBlock
 
Fields:
 
float Velocity
 
float MinLimit
 
float MaxLimit
 
Actions:
 
OnOff -> Toggle block On/Off
 
OnOff_On -> Toggle block On
 
OnOff_Off -> Toggle block Off
 
Reverse -> Reverse
 
IncreaseVelocity -> Increase Velocity
 
DecreaseVelocity -> Decrease Velocity
 
ResetVelocity -> Reset Velocity
 
IncreaseUpperLimit -> Increase Maximal distance
 
DecreaseUpperLimit -> Decrease Maximal distance
 
IncreaseLowerLimit -> Increase Minimal distance
 
DecreaseLowerLimit -> Decrease Minimal distance
 
 
 
Programmable block
 
Interface name: IMyProgrammableBlock
 
Parent: IMyFunctionalBlock
 
Fields: bool IsRunning
 
Actions:
 
OnOff -> Toggle block On/Off
 
OnOff_On -> Toggle block On
 
OnOff_Off -> Toggle block Off
 
Run -> Run
 
Terminal block and action name list - 3/3
 
Refinery
 
Interface name: IMyRefinery
 
Parent: IMyFunctionalBlock
 
Parent: IMyProductionBlock
 
Fields: bool UseConveyorSystem
 
Actions:
 
OnOff -> Toggle block On/Off
 
OnOff_On -> Toggle block On
 
OnOff_Off -> Toggle block Off
 
UseConveyor -> Use Conveyor System On/Off
 
 
 
Spotlight
 
Interface name: IMyReflectorLight
 
Parent: IMyLightingBlock
 
Parent: IMyFunctionalBlock
 
Fields:
 
float Radius
 
float Intensity
 
float BlinkIntervalSeconds
 
float BlinkLenght
 
float BlinkOffset
 
Actions:
 
OnOff -> Toggle block On/Off
 
OnOff_On -> Toggle block On
 
OnOff_Off -> Toggle block Off
 
IncreaseRadius -> Increase Radius
 
DecreaseRadius -> Decrease Radius
 
IncreaseBlink Interval -> Increase Blink Interval
 
DecreaseBlink Interval -> Decrease Blink Interval
 
IncreaseBlink Lenght -> Increase Blink Length
 
DecreaseBlink Lenght -> Decrease Blink Length
 
IncreaseBlink Offset -> Increase Blink Offset
 
DecreaseBlink Offset -> Decrease Blink Offset
 
 
 
Remote Control
 
Interface name: IMyRemoteControl
 
Parent: IMyShipController
 
Fields:
 
bool ControlWheels
 
bool ControlThrusters
 
bool HandBrake
 
bool DampenersOverride
 
Actions:
 
ControlThrusters -> Control thrusters On/Off
 
ControlWheels -> Control wheels On/Off
 
HandBrake -> Handbrake On/Off
 
DampenersOverride -> Inertia dampeners On/Off
 
Control -> Control
 
 
 
Rocket Launcher
 
Interface name: IMySmallMissileLauncher
 
Parent: IMyFunctionalBlock
 
Fields: bool UseConveyorSystem
 
Actions:
 
OnOff -> Toggle block On/Off
 
OnOff_On -> Toggle block On
 
OnOff_Off -> Toggle block Off
 
UseConveyor -> Use Conveyor System On/Off
 
  
Reloadable Rocket Launcher
+
=== Hello world ===
Interface name: IMySmallMissileLauncherReload
+
The standard Hello World program in Space Engineers can be written as such:
Parent: IMyFunctionalBlock
 
Fields: bool UseConveyorSystem
 
Actions:
 
OnOff -> Toggle block On/Off
 
OnOff_On -> Toggle block On
 
OnOff_Off -> Toggle block Off
 
UseConveyor -> Use Conveyor System On/Off
 
  
Rotor
+
public void Main()
Interface name: IMyMotorStator
+
{
Parent: IMyMotorBase
+
    Echo ("Hello, world!");
Parent: IMyFunctionalBlock
+
}
Fields:
 
bool IsAttached
 
float Torque
 
float BrakingTorque
 
float Velocity
 
float LowerLimit
 
float UpperLimit
 
float Displacement
 
Actions:
 
OnOff -> Toggle block On/Off
 
OnOff_On -> Toggle block On
 
OnOff_Off -> Toggle block Off
 
Reverse -> Reverse
 
Detach -> Detach
 
Attach -> Attach
 
IncreaseTorque -> Increase Torque
 
DecreaseTorque -> Decrease Torque
 
IncreaseBrakingTorque -> Increase Braking tor.
 
DecreaseBrakingTorque -> Decrease Braking tor.
 
IncreaseVelocity -> Increase Velocity
 
DecreaseVelocity -> Decrease Velocity
 
ResetVelocity -> Reset Velocity
 
IncreaseLowerLimit -> Increase Lower limit
 
DecreaseLowerLimit -> Decrease Lower limit
 
IncreaseUpperLimit -> Increase Upper limit
 
DecreaseUpperLimit -> Decrease Upper limit
 
IncreaseDisplacement -> Increase Rotor displacement
 
DecreaseDisplacement -> Decrease Rotor displacement
 
  
Sensor
+
If this program is entered into a programmable block and run, it will result in "Hello, world!" being displayed in the programmable block's interface on the lower right hand side of the screen.
Interface name: IMySensorBlock
 
Parent: IMyFunctionalBlock
 
Fields:
 
float LeftExtend
 
float RightExtend
 
float TopExtend
 
float BottomExtend
 
float FrontExtend
 
float BackExtend
 
bool DetectPlayers
 
bool DetectFloatingObjects
 
bool DetectSmallShips
 
bool DetectLargeShips
 
bool DetectStations
 
bool DetectAsteroids
 
Actions:
 
OnOff -> Toggle block On/Off
 
OnOff_On -> Toggle block On
 
OnOff_Off -> Toggle block Off
 
IncreaseLeft -> Increase Left extent
 
DecreaseLeft -> Decrease Left extent
 
IncreaseRight -> Increase Right extent
 
DecreaseRight -> Decrease Right extent
 
IncreaseBottom -> Increase Bottom extent
 
DecreaseBottom -> Decrease Bottom extent
 
IncreaseTop -> Increase Top extent
 
DecreaseTop -> Decrease Top extent
 
IncreaseBack -> Increase Back extent
 
DecreaseBack -> Decrease Back extent
 
IncreaseFront -> Increase Front extent
 
DecreaseFront -> Decrease Front extent
 
Detect Players -> Detect players On/Off
 
Detect Floating Objects -> Detect floating objects On/Off
 
Detect Small Ships -> Detect small ships On/Off
 
Detect Large Ships -> Detect large ships On/Off
 
Detect Stations -> Detect stations On/Off
 
Detect Asteroids -> Detect Asteroids On/Off
 
  
Solar Panel
+
=== Getting your position ===
Interface name: IMySolarPanel
+
This program will show the current GPS coordinates of your programming block's position in the world.
Fields:None
 
Actions:None
 
  
Sound Block
+
public void Main()
Interface name: IMySoundBlock
+
{
Parent: IMyFunctionalBlock
+
    var pos = Me.GetPosition();
Fields:
+
    Echo (pos.ToString());
float Volume
+
}
float Range
 
bool IsSoundSelected
 
float LoopPeriod
 
Actions:
 
OnOff -> Toggle block On/Off
 
OnOff_On -> Toggle block On
 
OnOff_Off -> Toggle block Off
 
IncreaseVolumeSlider -> Increase Volume
 
DecreaseVolumeSlider -> Decrease Volume
 
IncreaseRangeSlider -> Increase Range
 
DecreaseRangeSlider -> Decrease Range
 
PlaySound -> Play
 
StopSound -> Stop
 
IncreaseLoopableSlider -> Increase Loop time
 
DecreaseLoopableSlider -> Decrease Loop time
 
  
Spherical Gravity Generator
 
Interface name: IMyGravityGeneratorSphere
 
Parent: IMyGravityGeneratorBase
 
Parent: IMyFunctionalBlock
 
Fields:
 
float Radius
 
float Gravity
 
Actions:
 
OnOff -> Toggle block On/Off
 
OnOff_On -> Toggle block On
 
OnOff_Off -> Toggle block Off
 
IncreaseRadius -> Increase Radius
 
DecreaseRadius -> Decrease Radius
 
IncreaseGravity -> Increase Acceleration
 
DecreaseGravity -> Decrease Acceleration
 
  
Timer Block
+
=== Checking a sensor ===
Interface name: IMyTimerBlock
+
It's easy to get a sensor to open a door or trigger some other action even without any programming if you just place that action in the sensor's "Setup actions" list. However, triggering an action when a sensor does ''not'' detect something is more difficult, and cannot be done with timer blocks. This program will automatically check a sensor every 10 ticks (working out to about 6 times per second) and close a door if the sensor does not detect anything. This can easily be applied to other purposes, like turning off drills when asteroids are not in sensor range.
Parent: IMyFunctionalBlock
 
Fields:
 
bool IsCountingDown
 
float TriggerDelay
 
Actions:
 
OnOff -> Toggle block On/Off
 
OnOff_On -> Toggle block On
 
OnOff_Off -> Toggle block Off
 
IncreaseTriggerDelay -> Increase Delay
 
DecreaseTriggerDelay -> Decrease Delay
 
TriggerNow -> Trigger now
 
Start -> Start
 
Stop -> Stop
 
  
Warhead
+
List<MyDetectedEntityInfo> entity_list = new List<MyDetectedEntityInfo>();
Interface name: IMyWarhead
+
public Program()
Fields:
+
{
bool IsCountingDown
+
    Runtime.UpdateFrequency = UpdateFrequency.Update10;
float DetonationTime
+
    //This makes the program automatically run every 10 ticks.
Actions:
+
}
IncreaseDetonationTime -> Increase Detonation time
+
public void Main()
DecreaseDetonationTime -> Decrease Detonation time
+
{
StartCountdown -> Start countdown
+
    var door_sensor = GridTerminalSystem.GetBlockWithName("Door Sensor 1") as IMySensorBlock;
StopCountdown -> Stop countdown
+
    door_sensor.DetectedEntities (entity_list);
Safety -> Safety On/Off
+
    if (entity_list.Count == 0)
Detonate -> Detonate
+
    {
 +
        var door = GridTerminalSystem.GetBlockWithName("Door 1") as IMyDoor;
 +
        door.ApplyAction ("Open_Off");
 +
    }
 +
}
  
Welder
+
For this script to work, the sensor must be named "Door Sensor 1" and the door must be named "Door 1". If you configure the sensor to open the door, the door will automatically open when the player enters the sensor range and close when the player leaves the sensor range.
Interface name: IMyShipWelder
 
Parent: IMyShipToolBase
 
Parent: IMyFunctionalBlock
 
Actions:
 
OnOff -> Toggle block On/Off
 
OnOff_On -> Toggle block On
 
OnOff_Off -> Toggle block Off
 
UseConveyor -> Use Conveyor System On/Off
 
  
Wheel Suspension 1x1
+
=== Firing Thrusters ===
Interface name: IMyMotorSuspension
 
Parent: IMyMotorBase
 
Parent: IMyFunctionalBlock
 
Fields:
 
bool Steering
 
bool Propulsion
 
float Damping
 
float Strength
 
float Friction
 
float Power
 
Actions:
 
OnOff -> Toggle block On/Off
 
OnOff_On -> Toggle block On
 
OnOff_Off -> Toggle block Off
 
Steering -> Steering On/Off
 
Propulsion -> Propulsion On/Off
 
IncreaseDamping -> Increase Damping
 
DecreaseDamping -> Decrease Damping
 
IncreaseStrength -> Increase Strength
 
DecreaseStrength -> Decrease Strength
 
IncreaseFriction -> Increase Friction
 
DecreaseFriction -> Decrease Friction
 
IncreasePower -> Increase Power
 
DecreasePower -> Decrease Power
 
  
Wheel Suspension 3x3
+
// ship remote control or cockpit
Interface name: IMyMotorSuspension
+
IMyShipController myRemote;
Parent: IMyMotorBase
+
// List of thrusters
Parent: IMyFunctionalBlock
+
List<IMyThrust> myThrusters;
Fields:
+
// ship velocity
bool Steering
+
Vector3D velocity { get { return myRemote.GetShipVelocities().LinearVelocity; } }
bool Propulsion
+
// ship center of mass (so rotation doesn't make us change position)
float Damping
+
Vector3D position { get { return myRemote.CenterOfMass; } }
float Strength
+
// ship gravity, including any artificial gravity fields
float Friction
+
Vector3D gravity { get { return myRemote.GetTotalGravity(); } }
float Power
+
// physical mass includes multipliers etc.
Actions:
+
double mass { get {return myRemote.CalculateShipMass().PhysicalMass; } }
OnOff -> Toggle block On/Off
+
public void Move(double speed, Vector3D targetPos)
OnOff_On -> Toggle block On
+
{
OnOff_Off -> Toggle block Off
+
  // get a vector from out current position to our desired position
Steering -> Steering On/Off
+
  // use ClampToSphere so we aren't constantly at full thrust like the stock autopilot
Propulsion -> Propulsion On/Off
+
  //Vector3D desiredVelocity = Vector3D.ClampToSphere(targetPos - position, 1) * speed;
IncreaseDamping -> Increase Damping
+
  // get a vector from our current velocity to our desired velocity
DecreaseDamping -> Decrease Damping
+
  //Vector3D travelVec = desiredVelocity - velocity;
IncreaseStrength -> Increase Strength
+
  // apply the thrust to these thrusters
DecreaseStrength -> Decrease Strength
+
  ApplyThrust(myThrusters, Vector3D.Zero /* travelVec */);
IncreaseFriction -> Increase Friction
+
}
DecreaseFriction -> Decrease Friction
+
public void ApplyThrust(List<IMyThrust thrusters, Vector3D move) {
IncreasePower -> Increase Power
+
  move += -gravity;
DecreasePower -> Decrease Power
+
  move *= mass;
 +
  double totalThrust = 0;
 +
 
 +
  // this can be optimized later. There are faster ways.
 +
  foreach(var thruster in thrusters)
 +
    totalThrust += Math.Max(0, Vector3D.Dot(thruster.WorldMatrix.Backward, move));
 +
 +
  foreach(var thruster in thrusters) {
 +
    // Thrust override is using MaxThrust so we need to convert to that
 +
    var comp = thruster.MaxThrust / thruster.MaxEffectiveThrust;
 +
    // calculate how much this thrust helps with the total thrust
 +
    var part = thruster.MaxEffectiveThrust / totalThrust;
 +
    // Dot product with the travel direction of the thruster, not the flame direction
 +
    var thrust = Vector3D.Dot(thruster.WorldMatrix.Backward, move);
 +
    // set the thrust override based on all the parameters
 +
    thruster.ThrustOverride = (float)(thrust > 0 ? thrust * part * comp : 0.001);
 +
  }
 +
}
  
Wheel Suspension 5x5
+
== Compilation errors ==
Interface name: IMyMotorSuspension
+
This is a list (in progress) of known compilation errors and what causes them.
Parent: IMyMotorBase
 
Parent: IMyFunctionalBlock
 
Fields:
 
bool Steering
 
bool Propulsion
 
float Damping
 
float Strength
 
float Friction
 
float Power
 
Actions:
 
OnOff -> Toggle block On/Off
 
OnOff_On -> Toggle block On
 
OnOff_Off -> Toggle block Off
 
Steering -> Steering On/Off
 
Propulsion -> Propulsion On/Off
 
IncreaseDamping -> Increase Damping
 
DecreaseDamping -> Decrease Damping
 
IncreaseStrength -> Increase Strength
 
DecreaseStrength -> Decrease Strength
 
IncreaseFriction -> Increase Friction
 
DecreaseFriction -> Decrease Friction
 
IncreasePower -> Increase Power
 
DecreasePower -> Decrease Power
 
Programmable block video
 
  
 +
* Method name expected: The compiler found parentheses when it wasn't expecting them. You could be missing a method name before the parentheses, or you might be inappropriately using parentheses instead of square or curly brackets, depending on what you're trying to do.
  
 +
== See also ==
 +
* [[API:Sandbox.ModAPI.Ingame.MyGridTerminalSystem|MyGridTerminalSystem]] - Methods for getting object references to your various ship components.
 +
* [[Programming Guide/Action List]] - Actions you can apply to objects via the Object.ApplyAction method. Also includes some of the object properties. Data appears incomplete as of March 19th, 2018.
  
EDIT 01/02/15 - Changes: Allowed namespaces
+
== External links ==
Currently you can use only the following namespaces from Modding API:
+
* [https://github.com/malware-dev/MDK-SE/wiki/Quick-Introduction-to-Space-Engineers-Ingame-Scripts Quick Introduction to Space Engineers Ingame Scripts · malware-dev/MDK-SE Wiki] - Autogenerated API listing, tutorials, and more.
Sandbox.ModAPI.Ingame
+
* [https://forums.keenswh.com/threads/guide-programmable-block-c-101-for-space-engineers.7225150/ <nowiki>[Guide]</nowiki> Programmable Block - C# 101 For Space Engineers] - Basic intro to C# programming for Space Engineers.
Sandbox.ModAPI.Interfaces
+
* [https://forum.keenswh.com/threads/guide-programmable-block-c-102-for-space-engineers-loops-strings-and-other-things.7229828/ <nowiki>[Guide]</nowiki> Programmable Block - C# 102 for Space Engineers: Loops, Strings, and Other Things] - Basic intro to using loops and strings in C#
Sandbox.Common.ObjectBuilders
+
* [https://forum.keenswh.com/threads/guide-programmable-block-c-103-for-space-engineers-math-class.7231429/ <nowiki>[Guide]</nowiki> Programmable Block - C# 103 for Space Engineers - Math Class] - Basic intro to using the Math library in C#
VRageMath
+
* [https://forums.keenswh.com/threads/programmable-block-inter-grid-communication-guide.7392031/ Programmable Block Inter-Grid Communication Guide] - Using antennas to enable programming blocks to remotely communicate with each other.
VRage
+
* [https://github.com/malware-dev/MDK-SE/wiki/Continuous-Running-No-Timers-Needed Continuous Running No Timers Needed] - Configuring programming blocks to run automatically without needing to use a timer.
 +
* [https://forum.keenswh.com/threads/tutorial-constructor-and-save.7382338/ Tutorial: Constructor And Save] - Saving and reloading data
 +
* [https://docs.microsoft.com/en-us/dotnet/csharp/language-reference/operators/ C# Operators] - C# language reference for all operators, such as and, or, greater than, less than, etc.
 +
* [https://fresc81.github.io/SpaceEngineers/index.html Space Engineers API documentation]
 +
* [https://bloc97.github.io/SpaceEngineersModAPIDocs/html/b2d609dc-672a-3d90-cdc0-3753ce60d06f.htm Space Engineers ModAPI Documentation] - Includes many API methods and properties which can be used by Programmable Blocks.
  
You cannot use Sandbox.ModAPI namespace or any other game namespaces
+
[[Category:Game Mechanics]]

Latest revision as of 04:52, 3 June 2022

Programming in Space Engineers is done with the Programmable Block which can be given scripts written in C# (pronounced C Sharp). This can be used to make autonomous mining drones, long-range player-killing torpedoes, automated welding arms for ship construction and much more.

There is documentation on Github which is maintained by certain contributors and is very useful if you are already familiar with C# in general. https://github.com/malware-dev/MDK-SE/wiki

Introduction

Editor access

Only one player can edit the same script at a time. If someone else has an editor for the current block open and someone else tries to open that block's editor, a notification will be shown that the editor is already open.

Main method

When the editor is opened for first time on a block, the Program constructor and the Main method are present inside the code editor. The code in the editor becomes the body of the Program class definition.

This Main method is the entry point that will be called when executing script. If Main method is removed / renamed, the script will not run and you will be notified in the programmable block details area.

Custom methods/variables can be defined and used, but only the Main method will be called by the program.

Variable lifetime and scoping

There are two types of variables for scripting:

Local (inside the methods) 
these variables will keep their value only during execution of a method. Value will be “lost” when the method ends.
Global (outside the methods) 
these variables will keep their values during the lifetime of script. For example, if the variable needs to keep its value between separate runs of the script, it needs to be defined outside the methods.

After pressing “Remember & Exit” or “Remember” buttons, the previous script will be overwritten and all Global variables will be lost.

All variables, local and global except for the built-in Storage variable will lose their value or return to their default value when recompiling the code and between saved game loads. The Storage variable is unique in that it will store the data as a string for use between saved sessions and recompile.

Compiling

When the “Check code” button is pressed, the code will be compiled and the result of the compilation will be shown. There are two steps of the compilation process: First the code inside editor is compiled by c# compiler for language errors. If there are any errors during compilation the following dialog is shown: It this case “aaa” string is placed before Main method. This is the wrong language construction and the compilation failed. In the error dialog the Line number error and description of the error is shown.

After compilation, the code is checked for usage of disallowed namespaces and types. In case that check fails, the following dialog is shown: In this case System.IO.Directory was used to delete some directory. This is forbidden and error is shown that “Not allowed type was used in script”.

If compilation and checks pass, a dialog is shown, confirming the checks passed, and the code is saved.

Script execution

Script can be triggered by the following means:

1. By pressing "Run" button in terminal properties of programmable block.

2. By assigning terminal action and manually pressing the action button (1-9) while controlling the grid using cockpit, control station or remote control.

3. By pressing button on a button panel with assigned action "Run".

4. By a timer with assigned action "Run".

5. By another script in another programmable block in the same grid.

6. By antenna with assigned programmable block, when recieved message from another antenna. (see Antenna#Programming)

7. By the script itself, by assigning a value to Runtime.UpdateFrequency variable. In this case, no argument can be specified, however, you can use the following Main method signature: void Main(string argument, UpdateType updateSource) to gain acces to the information about what exactly triggered the script and so make the script "know" if it was triggered by Update1, Update10, Update100 events or manually or whatever event was the reason of trigger execution.

Script is executed only on server even if it’s triggered from client. If there is any exception during script execution, all clients will be notified in programmable block details area about failure. In case of exception during script execution, script will not run again unless User opens editor and change script.

Counting of instructions

Every time script is executed, every instruction of script is counted. If script executes more instruction than limit, execution is stopped and user is notified that script is too complex for execution. This prevents scripts from freezing the game. It is similar to the idea of a stack overflow exception, and is unrealistically high. If you get this error, it is more likely you have an infinite loop than that you are trying to do too much. The count can be accessed on this.Runtime.CurrentInstructionCount to narrow down the problem.

Whitelist

The types and classes allowed in scripts are restricted. Refer to the Scripting Whitelist to see what you are allowed to use.

Available interfaces

Possible Actions

Currently only terminal actions can be triggered inside scripts. User can access terminal system for grid on which programmable block is located and trigger any terminal action on any block at grid.

Block Classes (Action List)

Same block class for different SubTypeID

Some blocks have the same parent (e.g. <TypeId> in cubeblocks.sbc) and differs only by subtype (e.g. <SubtypeId>). This means there is no distinction between these blocks in code.

Example of these blocks is the Cargo Container: there are 3 types of cargo containers in the game: small, medium and large. These three types differ only by the Subtype and Type is the same for them e.g. large cargo container id is:

<Id>
  <TypeId>CargoContainer</TypeId>
  <SubtypeId>LargeBlockLargeContainer</SubtypeId>
</Id>

Medium is:

<Id>
  <TypeId>CargoContainer</TypeId>
  <SubtypeId>SmallBlockMediumContainer</SubtypeId>
</Id>

And small is:

<Id>
  <TypeId>CargoContainer</TypeId>
  <SubtypeId>LargeBlockSmallContainer</SubtypeId>
</Id>

In this case there is only one class IMyCargoContainer for all types of cargo containers.

Example programs

Hello world

The standard Hello World program in Space Engineers can be written as such:

public void Main()
{
   Echo ("Hello, world!");
}

If this program is entered into a programmable block and run, it will result in "Hello, world!" being displayed in the programmable block's interface on the lower right hand side of the screen.

Getting your position

This program will show the current GPS coordinates of your programming block's position in the world.

public void Main()
{
    var pos = Me.GetPosition();
    Echo (pos.ToString());
}


Checking a sensor

It's easy to get a sensor to open a door or trigger some other action even without any programming if you just place that action in the sensor's "Setup actions" list. However, triggering an action when a sensor does not detect something is more difficult, and cannot be done with timer blocks. This program will automatically check a sensor every 10 ticks (working out to about 6 times per second) and close a door if the sensor does not detect anything. This can easily be applied to other purposes, like turning off drills when asteroids are not in sensor range.

List<MyDetectedEntityInfo> entity_list = new List<MyDetectedEntityInfo>(); 
public Program()
{
    Runtime.UpdateFrequency = UpdateFrequency.Update10;
    //This makes the program automatically run every 10 ticks.
}
public void Main()
{
    var door_sensor = GridTerminalSystem.GetBlockWithName("Door Sensor 1") as IMySensorBlock;
    door_sensor.DetectedEntities (entity_list);
    if (entity_list.Count == 0)
    {
        var door = GridTerminalSystem.GetBlockWithName("Door 1") as IMyDoor;
        door.ApplyAction ("Open_Off");
    }
}

For this script to work, the sensor must be named "Door Sensor 1" and the door must be named "Door 1". If you configure the sensor to open the door, the door will automatically open when the player enters the sensor range and close when the player leaves the sensor range.

Firing Thrusters

// ship remote control or cockpit
IMyShipController myRemote;
// List of thrusters
List<IMyThrust> myThrusters;
// ship velocity
Vector3D velocity { get { return myRemote.GetShipVelocities().LinearVelocity; } }
// ship center of mass (so rotation doesn't make us change position)
Vector3D position { get { return myRemote.CenterOfMass; } }
// ship gravity, including any artificial gravity fields
Vector3D gravity { get { return myRemote.GetTotalGravity(); } }
// physical mass includes multipliers etc.
double mass { get {return myRemote.CalculateShipMass().PhysicalMass; } }
public void Move(double speed, Vector3D targetPos)
{
  // get a vector from out current position to our desired position
  // use ClampToSphere so we aren't constantly at full thrust like the stock autopilot
  //Vector3D desiredVelocity = Vector3D.ClampToSphere(targetPos - position, 1) * speed;
  // get a vector from our current velocity to our desired velocity
  //Vector3D travelVec = desiredVelocity - velocity;
  // apply the thrust to these thrusters
  ApplyThrust(myThrusters, Vector3D.Zero /* travelVec */);
}
public void ApplyThrust(List<IMyThrust thrusters, Vector3D move) {
  move += -gravity;
  move *= mass;
  double totalThrust = 0;
  
  // this can be optimized later. There are faster ways. 
  foreach(var thruster in thrusters)
    totalThrust += Math.Max(0, Vector3D.Dot(thruster.WorldMatrix.Backward, move));

  foreach(var thruster in thrusters) {
    // Thrust override is using MaxThrust so we need to convert to that
    var comp = thruster.MaxThrust / thruster.MaxEffectiveThrust;
    // calculate how much this thrust helps with the total thrust
    var part = thruster.MaxEffectiveThrust / totalThrust;
    // Dot product with the travel direction of the thruster, not the flame direction
    var thrust = Vector3D.Dot(thruster.WorldMatrix.Backward, move);
    // set the thrust override based on all the parameters
    thruster.ThrustOverride = (float)(thrust > 0 ? thrust * part * comp : 0.001);
  }
}

Compilation errors

This is a list (in progress) of known compilation errors and what causes them.

  • Method name expected: The compiler found parentheses when it wasn't expecting them. You could be missing a method name before the parentheses, or you might be inappropriately using parentheses instead of square or curly brackets, depending on what you're trying to do.

See also

  • MyGridTerminalSystem - Methods for getting object references to your various ship components.
  • Programming Guide/Action List - Actions you can apply to objects via the Object.ApplyAction method. Also includes some of the object properties. Data appears incomplete as of March 19th, 2018.

External links