Difference between revisions of "Programmable Block"

From Space Engineers Wiki
Jump to: navigation, search
(saved draft - moved entire section from programming guide, added some information.)
m (categories)
 
(14 intermediate revisions by 6 users not shown)
Line 1: Line 1:
{{itembox
+
{{SimpleItembox|Mod:Vanilla/CubeBlock/LargeProgrammableBlock|Size||Mass||Integrity||BuildTimeSeconds||IsAirTight||ResourceSinkGroup||PCU}}
| item = Programmable Block
+
{{SimpleItembox|Mod:Vanilla/CubeBlock/SmallProgrammableBlock|Size||Mass||Integrity||BuildTimeSeconds||IsAirTight||ResourceSinkGroup||PCU}}
| description = Block That Executes Code
+
{{CategorizeComponents|Mod:Vanilla/CubeBlock/LargeProgrammableBlock}}
| tool = no
 
| largeship = yes
 
| smallship = yes
 
| component = no
 
| rawmaterial = no
 
| material = no
 
 
 
| spowerconsumption = 0.0005
 
| sbuildtime = 20
 
| scomponentstructure = 2
 
| scomponent1 = Steel Plate
 
| scomponent1amt = 1
 
| scomponent2 =  Computer
 
| scomponent2amt = 2
 
| scomponent3 = Display
 
| scomponent3amt = 1
 
| scomponent4 = Motor
 
| scomponent4amt = 1
 
| scomponent5 = Large Steel Tube
 
| scomponent5amt = 2
 
| scomponent6 = Construction Component
 
| scomponent6amt = 2
 
| scomponent7 = Steel Plate
 
| scomponent7amt = 2
 
| swidth = 1
 
| sheight = 1
 
| sdepth = 1
 
 
 
| lpowerconsumption = 0.0005
 
| lbuildtime = 20
 
| lcomponentstructure = 2
 
| lcomponent1 = Steel Plate
 
| lcomponent1amt = 10
 
| lcomponent2 = Computer
 
| lcomponent2amt = 2
 
| lcomponent3 = Display
 
| lcomponent3amt = 1
 
| lcomponent4 = Motor
 
| lcomponent4amt = 1
 
| lcomponent5 = Large Steel Tube
 
| lcomponent5amt = 2
 
| lcomponent5 = Construction Component
 
| lcomponent5amt = 4
 
| lcomponent6 = Steel Plate
 
| lcomponent6amt = 11
 
| lwidth = 1
 
| lheight = 1
 
| ldepth = 1
 
 
 
| version = 01.106
 
}}
 
  
 
== Overview ==
 
== Overview ==
Line 60: Line 9:
 
Programmable Block scripts run in a single update (single frame) and any that take too long to complete are aborted. This means it is impossible for a single run of the script to 'wait' on any event. If you want your script to run when something happens, you need to either find a way of getting another block to trigger it at the right time (an 'interrupt-driven' approach via eg. a sensor block), or modify your script to check for a precondition and set up a timer to run it regularly (a 'polling' approach). Depending on what your script is doing, one approach may be the preferred or even the only way to do it.
 
Programmable Block scripts run in a single update (single frame) and any that take too long to complete are aborted. This means it is impossible for a single run of the script to 'wait' on any event. If you want your script to run when something happens, you need to either find a way of getting another block to trigger it at the right time (an 'interrupt-driven' approach via eg. a sensor block), or modify your script to check for a precondition and set up a timer to run it regularly (a 'polling' approach). Depending on what your script is doing, one approach may be the preferred or even the only way to do it.
  
*Since [[Update 01.067]] each programmable block has a maximum limit of '''50,000''' characters for any in-game script.  
+
*Since [[Update_01.067#Hotfix_01.067.007|Update 01.067 Hotfix 007]] each programmable block has a maximum limit of '''100,000''' characters for any in-game script.  
  
 
=== GUI Overview ===
 
=== GUI Overview ===
Line 76: Line 25:
  
 
==== Editor ====
 
==== Editor ====
 
+
{| style="width: 80%;"
 +
|
 
[[File:Steamworkshop webupload previewfile 360966557 preview (1).jpg|500px]]
 
[[File:Steamworkshop webupload previewfile 360966557 preview (1).jpg|500px]]
  
Code editor contains these buttons:
+
|Code editor contains these buttons:
''Help'' – it will open the help guide inside the game.
+
* ''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.
+
* ''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 & 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.
+
* ''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.
+
* ''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
+
* ''Line counter'' – it shows current line number and total number of lines in code
 
+
|}
 
==== Browse Workshop ====
 
==== Browse Workshop ====
 
+
{| style="width: 80%;"
 +
|
 
[[File:Browse workshop.jpg|200px]]
 
[[File:Browse workshop.jpg|200px]]
 
+
|This screen is similar to blueprint screen and contains these buttons :
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
''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)
''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
''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.
''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.
''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…
''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.
''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
''Refresh Scripts'' – will reload the local and subscribed script list
+
|}
 
 
 
==== Details (local script) ====
 
==== Details (local script) ====
 
+
{| style="width: 80%;"
 +
|
 
[[File:Details (local script).jpg|500px]]
 
[[File:Details (local script).jpg|500px]]
 
+
|This screen will show up when you press details for local script and contains the following buttons:
This screen will show up when you press details for local script and contains the following buttons:
+
* ''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.
''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.
''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.
''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.
''Browse Workshop'' – it will open the workshop screen to browse and subscribe scripts.
+
* ''Close'' – it will close the screen
''Close'' – it will close the screen  
+
|}
 
 
 
==== Details (workshop script) ====
 
==== Details (workshop script) ====
  
 
This screen will show up when you press details for script from workshop and it contains these buttons:
 
This screen will show up when you press details for script from workshop and it contains these buttons:
Open in Workshop – it will open the current script workshop page.
+
* ''Open in Workshop'' – it will open the current script workshop page.
Close – it will close the screen
+
* ''Close'' – it will close the screen
Programming Guide
 
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.
 
  
 
== Media ==
 
== Media ==
 +
[[File:Programmable_Block_ProgramBlock01.jpg|none|400px]]
  
 
== Tips ==
 
== Tips ==
  
 
== Known Issues ==
 
== Known Issues ==
*'''Foreach not working at 64- bit''': - Problem:
+
*'''Foreach not working at 64- bit''':
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.
+
''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. <br/>''Workaround'' - All our interfaces used in in-game scripting are using lists as collections. Please use For loop for iteration across these lists
Workaround:
 
All our interfaces used in in-game scripting are using lists as collections. Please use For loop for iteration across these lists
 
  
*'''Lambda functions not working''' - Problem:
+
*'''Lambda functions not working'''
Currently lambda functions are not supported, if you use them in script, exception will be thrown and script will not run.
+
''Problem'':
Workaround:
+
Currently lambda functions are not supported, if you use them in script, exception will be thrown and script will not run.<br/>''Workaround'' -
 
Please use method instead of lambda function if possible.
 
Please use method instead of lambda function if possible.
  
*'''User defined variables are not saved''' - Problem:
+
* '''User defined static variables and methods not working'''
None of the user defined variables inside script are saved, therefore after loading game they are reset to their default values.
+
''Problem'' -
Workaround:
+
Currently using user defined static members or methods will cause script to throw exception and the script will not run.<br/>''Workaround'' -
 +
Please don’t define static methods or variables.
 +
 
 +
*'''User defined variables are not saved'''
 +
''Problem'' -
 +
None of the user defined variables inside script are saved, therefore after loading game they are reset to their default values.<br/>''Workaround'' -
 
We added string variable called "Storage" that will be loaded and saved when the block is loaded and saved.
 
We added string variable called "Storage" that will be loaded and saved when the block is loaded and saved.
 
  
 
== See Also ==
 
== See Also ==
 
* [[Programming Guide]]
 
* [[Programming Guide]]
 +
* [[Programming_Guide/Action_List|Action List]]
 +
* [[Programming_Guide/API_List|API List]]
  
 
== Programming ==
 
== Programming ==
 
* [[Programming_Guide/Action_List#Programmable_block|Action List - Programmable block]]
 
* [[Programming_Guide/Action_List#Programmable_block|Action List - Programmable block]]
 +
 +
== External links ==
 +
* Programmable block [https://github.com/malware-dev/MDK-SE/wiki/Quick-Introduction-to-Space-Engineers-Ingame-Scripts coding guide] - Malware's coding guide
  
 
== Update History ==
 
== Update History ==
 +
<div style="-webkit-border-image: none;-webkit-box-shadow: rgba(0, 0, 0, 0.046875) 0px 1px 1px 0px inset;background-color: #eeeeee;border-bottom-color: #AFAFAF;border-bottom-left-radius: 3px;border-bottom-right-radius: 3px;border-bottom-style: solid;border-bottom-width: 1px;border-left-color: #AFAFAF;border-left-style: solid;border-left-width: 1px;border-right-color: #AFAFAF;border-right-style: solid;border-right-width: 1px;border-top-color: #AFAFAF;border-top-left-radius: 3px;border-top-right-radius: 3px;border-top-style: solid;border-top-width: 1px;box-shadow: rgba(0, 0, 0, 0.046875) 0px 1px 1px 0px inset;color: #333;display: block;font-family: 'Helvetica Neue', Helvetica, Arial, sans-serif;font-size: 1em;height: auto;line-height: 20px;margin-bottom: 5px;margin-left: 8px;margin-right: 8px;margin-top: 0px;min-height: 20px;padding-bottom: 4px;padding-left: 4px;padding-right: 4px;padding-top: 4px;width: auto;">
 +
{| class="wikitable" style="width: 100%"
 +
|style="text-align: left;width: 8%"| [[Update 01.063]] ||style="padding-left: 10px;padding-right: 10px;"|
 +
* Programmable Block Introduced
 +
|}
 +
 +
</div>
 +
[[Category:Functional Blocks]]

Latest revision as of 22:37, 18 May 2020

Programmable Block Icon.png
Large Ship / Station
Programmable block
Large Ship Icon.png

ComponentsRequired

 Functional 

 Hack 

Dimensions (W,H,L)1,1,1
Mass534.4 kg
534,400 g
534,400,000 mg
0.534 t
Integrity2,387
Build time20 s
Is AirtightNo
Power Consumer GroupUtility
PCU Cost100
BrowseLast edit: 2020-04-13
Programmable Block Icon.png
Small Ship
Programmable block
Small Ship Icon.png

ComponentsRequired

 Functional 

 Hack 

Dimensions (W,H,L)1,1,1
Mass138.4 kg
138,400 g
138,400,000 mg
0.138 t
Integrity427
Build time8 s
Is AirtightNo
Power Consumer GroupUtility
PCU Cost100
BrowseLast edit: 2020-04-13

Overview

A Programmable Block can be programmed to do different functions, like switching lights and controlling doors. It can also be used by entering the control panel in the Terminal. It has almost unlimited functionality.

Usage

Programmable Block scripts run in a single update (single frame) and any that take too long to complete are aborted. This means it is impossible for a single run of the script to 'wait' on any event. If you want your script to run when something happens, you need to either find a way of getting another block to trigger it at the right time (an 'interrupt-driven' approach via eg. a sensor block), or modify your script to check for a precondition and set up a timer to run it regularly (a 'polling' approach). Depending on what your script is doing, one approach may be the preferred or even the only way to do it.

  • Since Update 01.067 Hotfix 007 each programmable block has a maximum limit of 100,000 characters for any in-game script.

GUI Overview

The programmable block terminal panel screen currently contains two buttons:

Edit – it will open the editor for editing scripts and the ability to save/load scripts from and to disk. Also, you can upload your scripts to workshop and download subscribed scripts.

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.

Steamworkshop webupload previewfile 360966557 preview.jpg

Details section – In this area the script exception will be shown (if any will occur)

Editor

Steamworkshop webupload previewfile 360966557 preview (1).jpg

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

Browse workshop.jpg

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)

Details (local script).jpg

This screen will show up when you press details for local script and contains the following buttons:
  • 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)

This screen will show up when you press details for script from workshop and it contains these buttons:

  • Open in Workshop – it will open the current script workshop page.
  • Close – it will close the screen

Media

Programmable Block ProgramBlock01.jpg

Tips

Known Issues

  • Foreach not working at 64- bit:

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 - All our interfaces used in in-game scripting are using lists as collections. Please use For loop for iteration across these lists

  • Lambda functions not working

Problem: Currently lambda functions are not supported, if you use them in script, exception will be thrown and script will not run.
Workaround - Please use method instead of lambda function if possible.

  • User defined static variables and methods not working

Problem - Currently using user defined static members or methods will cause script to throw exception and the script will not run.
Workaround - Please don’t define static methods or variables.

  • User defined variables are not saved

Problem - None of the user defined variables inside script are saved, therefore after loading game they are reset to their default values.
Workaround - We added string variable called "Storage" that will be loaded and saved when the block is loaded and saved.

See Also

Programming

External links

Update History

Update 01.063
  • Programmable Block Introduced