Difference between revisions of "Programming Guide"

From Space Engineers Wiki
Jump to: navigation, search
(Available interfaces: - saved draft)
(Script execution)
(7 intermediate revisions by 4 users not shown)
Line 3: Line 3:
  
 
=== Editor access ===
 
=== Editor access ===
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.
+
Only one player can edit the same script at 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 ===
 
=== Main method ===
When editor is opened for first time, void Main() method is present inside code editor.
+
When the editor is opened for first time, void Main() method is present inside the 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.  
+
This is 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 Main method will be called by script.
+
Custom methods/variables can be defined and used, but only the Main method will be called without reference.
  
 
=== Variables life ===
 
=== Variables life ===
There are two types of variables for script:
+
There are two types of variables for scripting:
Local (inside the methods) – these variables will keep theirs value only during execution of method.
+
Local (inside the methods) – these variables will keep their value only during execution of a method.
Value will be “lost” when method ends.
+
Value will be “lost” when the method ends.
Global (outside the methods) - these variables will keep theirs values during lifetime of script. E.g.
+
Global (outside the methods) - these variables will keep their values during the lifetime of script. E.g.
If variable needs to keep value between separate runs of program ,it needs to be defined outside the methods.
+
If the 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.
+
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 that it store data as string between saved seasons and recompile.
  
 
=== Compiling ===
 
=== Compiling ===
When “Check code” button is pressed, code will be compiled and result of compilation will be shown.
+
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 compilation process:
+
There are two steps of the compilation process:
First code inside editor is compiled by c# compiler for language errors.
+
First the code inside editor is compiled by c# compiler for language errors.
If there is any error during compilation following dialog is shown:
+
If there are any errors during compilation the following dialog is shown:
It this case “aaa” string is placed before Main method. This is wrong language construction and compilation failed.
+
It this case “aaa” string is placed before Main method. This is the wrong language construction and the compilation failed.
In error dialog Line number error and description of the error is shown.
+
In the error dialog the 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,
+
After compilation, the code is checked for usage of disallowed namespaces and types. In case that check fails,
Following dialog is shown:
+
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”.
 
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:
+
If compilation and checks pass, a dialog is shown, confirming the checks passed, and the code is saved.
This means that code doesn’t contain any language errors or not allowed methods.
 
  
 
=== Script execution ===
 
=== Script execution ===
Line 37: Line 38:
 
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.
 +
A timer can also continuesly run the script by having a run action (you may be prompt to input an argument) and then starting/triggering itself or being started/triggered via script code (if going by the letter the timer will stop if the script crash).
  
 
=== Counting of instructions ===
 
=== Counting of instructions ===
Line 49: Line 51:
 
:* [[Programming_Guide/API_List|API List]]
 
:* [[Programming_Guide/API_List|API List]]
  
=== Block Classes ===
+
=== Block Classes (Action List) ===
 
:* [[Programming_Guide/Action_List|Block Action List]]
 
:* [[Programming_Guide/Action_List|Block Action List]]
  
Line 72: Line 74:
 
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.
  
==Changes: Allowed namespaces==
+
==Whitelist==
Currently you can use only the following namespaces from Modding API:<br />
+
The types and classes allowed in scripts are restricted. Refer to the [[Scripting Whitelist]] to see what you are allowed to use.
Sandbox.ModAPI.Ingame<br />
 
Sandbox.ModAPI.Interfaces<br />
 
Sandbox.Common.ObjectBuilders<br />
 
VRageMath<br />
 
VRage<br />
 
 
 
You cannot use Sandbox.ModAPI namespace or any other game namespaces
 
  
 
[[Category:Game Mechanics]]
 
[[Category:Game Mechanics]]

Revision as of 14:04, 6 May 2017

Introduction

Editor access

Only one player can edit the same script at 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, void Main() method is present inside the code editor. This is 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 without reference.

Variables life

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. E.g. If the 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, 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 that it store data as string between saved seasons 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

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. In case of exception during script execution, script will not run again unless User opens editor and change script. A timer can also continuesly run the script by having a run action (you may be prompt to input an argument) and then starting/triggering itself or being started/triggered via script code (if going by the letter the timer will stop if the script crash).

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.


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 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.
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:
<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.

Whitelist

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