Difference between revisions of "Programming Guide"

Revision as of 16:30, 29 November 2015

Introduction

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.

Main method

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

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

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

• API List

Block Classes (Action List)

• Block 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.

Changes: Allowed namespaces

Currently you can use only the following namespaces from Modding API:
Sandbox.ModAPI.Ingame
Sandbox.ModAPI.Interfaces
Sandbox.Common.ObjectBuilders
VRageMath
VRage

You cannot use Sandbox.ModAPI namespace or any other game namespaces