Difference between revisions of "Programming Guide"

From Space Engineers Wiki
Jump to: navigation, search
(Variables life)
(Compiling)
Line 19: Line 19:
  
 
=== 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 ===

Revision as of 00:48, 31 October 2016

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.

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.

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.