Space Engineers

Space Engineers

Not enough ratings
ActionScript User Guide
By avaness
This guide is for the ActionScript workshop item.

If you have any suggestions or requests for either this guide or the script let me know.
   
Award
Favorite
Favorited
Unfavorite
Getting Started
To get started, the only thing that is actually required is the programmable block. Any ActionScript that you write should go into the CustomData section of the programmable block. Each script has a header and some commands separated by lines or ; characters. Everything that follows the header will be included in your script. The header should always be surrounded by # characters. The most basic header includes only the name:
#Script_Name#
You can also add a @ character to the beginning to make the script automatically start when the programming block is recompiled:
#@Script_Name#
For scripts that require input variables, you must add the name of the variable separated by commas:
#Script_Name,arg1,arg2#
A script that contains arguments cannot be automatically run using a @ character.
Once you have the header, you will need to enter the commands. Each command has certain arguments that need to follow it. Usually, it works well enough to simply separate each argument using spaces. If you need to give a command an argument that includes spaces, you can surround the argument that includes spaces with quotes. Examples:
action "Outer Door" Open prop "LCD panel" _Text "Some important text!"
Once you have an ActionScript ready, you can recompile the programmable block to make the changes appear. You can run the following commands on the programmable block:
var <script_name> <variable_name> <value> : edits the values of a running script
stop [script_name] : stops all scripts or stops the specified script
run [script_name] : starts all scripts or starts the specified script
These three commands are the only three commands that can be run on the programmable block itself via the argument box. Other commands found below are commands that can be used in the CustomData of the programmable block.
If you want to make your code more readable, you can use a single / at the beginning of the line to specify that the line is a comment and should be ignored.
action Door Open / This line will be ignored action OtherDoor Open
Block Names and Groups
It is impossible to do anything in ActionScript without being able to reference blocks. There are 2 different ways block references will appear in commands. A single block (seen as <block> on this guide) and a group of blocks (seen as <blocks> on this guide). References to a single block can be either the block name or a variable reference. Examples:
Piston *door_block
A group reference can include any number of single block, group, or variable references separated by commas. To specify a group found in the terminal, add an @ character. Variable references in block groups can also include the @ character. In addition to the group character, the ^ character can be used to select all blocks start with the name. Examples:
Piston,*door_block,@Rotors,Something^
Values, Properties, and Actions
The two most important commands are:
action <blocks> <id> prop <blocks> <id> <value>
These two commands perform the actions that you see when you add a block to the bar of your cockpit. There are many actions and properties, most of which you will find on the MDK github[github.com]. Some properties known as custom properties can not be found on that page and typically have a _ character in front of them. Custom properties that can be modified include _Sound, _Text, and _AutoPIlot. Better descriptions of these properties can be found below. If you do not wish to look up the properties you can also use the examine command with the name of an LCD and the block. The information for the block will be written to the LCD(s).
examine <blocks> <block> examine LCD "Remote Control"

Many commands have values (denoted by <value> on this guide). There are many ways to get a value, the most basic being a literal value:
42 (Number) -2.3 (Number) STRING (String) true (Boolean) 255,0,0 (Color) red (Color) GPS:SUPER_SECRET_BASE:6:6:6: (Vector)

Properties can also be used as values. These can be specified using the block name and the property id separated by a comma. A full list of custom properties not found on the MDK is below.
Examples:
<block>,<id> Piston,_Displacement Light,Color Timer,OnOff

You may also use a * to specify that the value is a variable, these must be declared ahead of time using the var command. Variables can only be accessed within the script where they were declared unless you make it a global variable using a $ character. You can use any value to declare a variable, including other variables. Examples:
var <variable_name> <value> var regularVar 69 (accessed using *regularVar) var $globalVar 666 (accessed using *$globalVar)
List of Custom Properties
This list includes all custom properties. The vanilla properties can be found using the link above. Italicized elements indicate elements that can be modified. Note, you can also use an examine command (found above) to see all the actions and properties of any block.
Id
Type
Description
_Exists
Boolean
True if the block exists.
_Position
Vector
The position of the block.
_Forward
Vector
The forward direction of the block.
Sound Block
_Sound
String
The name of the sound item.
LCD Panel
_Text
String
The text of the panel. (See also lcd commands below.)
Remote Control
_AutoPilot
Boolean
Works the same as AutoPilot, use if you have issues getting the other property to function properly.
Remote Control and Cockpits
_Ship_Controlled
Boolean
True if the cockpit is controlling the ship.
_Ship_ForwardBackward
Number
The forward and backward value of the movement indicator.
_Ship_RightLeft
Number
The right and left value of the movement indicator.
_Ship_UpDown
Number
The up and down value of the movement indicator.
_Ship_Roll
Number
The value of the roll indicator.
_Ship_Yaw
Number
The yaw of the rotation indicator.
_Ship_Pitch
Number
The pitch of the rotation indicator.
_Ship_Gravity
Vector
The gravity vector at the cockpit position.
_Ship_Speed
Number
The speed of the ship.
_Ship_Velocity
Vector
The velocity of the ship.
_Ship_AngularSpeed
Number
The angular speed of the ship.
_Ship_AngularVelocity
Vector
The angular velocity of the ship.
_Ship_Altitude
Number
The distance from the surface of the planet. (or -1)
_Ship_SeaAltitude
Number
The distance from the sealevel of the planet. (or -1)
Sensor
_NumDetected
Number
The number of detected objects within sensor range.
Projector
_BlocksRemaining
Number
The number of blocks remaining. (Updates about every 100 ticks)
Turret
_HasEnemy
Boolean
True if the turret is detecting an enemy.
_EnemyPos
Boolean
The vector position of the targeted enemy, or a zero vector.
[
Rotor
_Rotor_Angle
Number
The current angle that the rotor head is in.
Piston
_Displacement
Number
The distance the piston is extended
Connector
_Connector_Connected
Boolean
True if the connector is connected.
_Connecctor_Ready
Boolean
True if the connector is ready to be connected.
_Connector_Unconnected
Boolean
True if the connector is not connected.
Door
_Door_Opening
Boolean
True if the door is opening.
_Door_Open
Boolean
True if the door is fully open.
_Door_Closing
Boolean
True if the door is closing.
_Door_Closed
Boolean
True if the door is fully closed.
Air Vent
_Vent_Pressure
Number
The amount of air in the room from 0 to 1.
Inventory Blocks
_Inv_Mass
Number
The amount of mass that the inventory currently holds.
_Inv_Volume
Number
The percentage full form 0 to 1.
Gas Containers
_Inv_Gas
Number
The percentage full from 0 to 1.
Battery
_Charge
Number
The percentage of stored charge from 0 to 1.
Conditionals
There are commands that can be used to run other commands conditionally. All of which follow the general format of two values separated by an operator. You can use the following operators: ==, !=, <, >, <=, >=. The three conditional commands are:
if <value> <operator> <value> ifany <blocks> <property> <operator> <value> ifall <blocks> <property> <operator> <value>
Conditional commands will execute all code starting at the following line and ending with an endif command. You may optionally add an else command for code that should be executed when the condition is not true. Examples:
if Door,Open == true prop Light Color red else prop Light Color white endif
As the name suggests, the ifany and ifall commands are the same as the if command except they compare the properties of all blocks in a group to a value. For the ifany command, If any of the properties match the condition, then the code in the block will be executed. The ifall command works in a similar way, except it only executes the code if all of the block properties match the condition. Examples:
ifany @Doors Open == true prop Light Color red else prop Light Color white endif
Structure and Timing
In some cases, it might be important to make your ActionScript loop. You can do this using these 3 commands:
jump <name> jumpdef <name> goto <line_number>
Using these commands is fairly straight forward. You could either use goto to jump to a specific line, or you could use jump and jumpdef together to create a loop. The line specified in the goto command is the line number starting at 0 directly below the header, including blank lines. Examples:
jumpdef loop (code to run forever) jump loop jumpdef conditionalLoop (code to run) if <value> <operator> <value> jump out endif jump conditionalLoop jumpdef out (code to run starting on line 9) goto 8

You can also use the delay command to pause execution for a specified amount of time. The argument can be specified in seconds or in ticks with a t character. Examples:
delay <seconds> delay 1.3 delay <ticks>t delay 10t

You can also pause execution based on a condition. Similar to if statements, you use a wait command with 2 values and an operator. Example:
wait <value> <operator> <value> wait Piston,_Displacement > 9

If you want to do some actions for a group of blocks, you may also use a foreach loop. Foreach loops are loops that run once for every block in the block group. They have a built-in variable that can be used inside the loop as a variable name. Similarly to jump loops, foreach loops should always have an endforeach command to mark the end of the code inside the loop. Note that this can usually be replaced with an ifany or ifall command. Examples:
foreach <variable_name> <blocks> (code to run) endforeach foreach piston @Pistons if *piston,_Displacement > 9 action *piston Retract endif endforeach

The last and the most basic execution related command is the stop command. This command immediately stops the current script and does not continue.
Methods and Functions
In your ActionScript, you can use the run and start commands to execute code from other ActionScripts you may have. Both commands operate in the same way, except when you use the start command the script will not wait for the started script to finish before moving on. If the ActionScript you are starting contains arguments in its header, you must specify these arguments after the command. After executing a run command, any specified arguments will be accessible as variables with the names as a combination of the script name and the argument name. Examples:
run <script_name> [argument1] [argument2] ... start <script_name> [argument1] [argumenet2] ... #RunExample# action @Lights OnOff_Off run 2SecondDelay action @Lights OnOff_On #BadStartExample# (This code will not work! The script does not wait for 2SecondDelay to finish before moving on!) action @Lights OnOff_Off start 2SecondDelay action @Lights OnOff_On #2SecondDelay# delay 2 #AdvancedExample# run Add 1 1 0 prop LCD _Text *Add_result #Add,num1,num2,result# var result *num1 + *num2

If you want to run another programmable block, you can also use the pb command to run a script with an argument. Examples:
pb <blocks> <value> pb "Programmable Block" Argument
Math
No scripting language would be complete without the capability to do math. In ActionScript you can use the var command to perform basic math calculations. The availible operations depends on what type of value you have. Examples:
(<vector> is a <value> of type vector)
(<number> is a <value> of type number)
(<string> is a <value> of type string)
var result <number> + <number> var result <number> - <number> var result <number> / <number> var result <number> * <number> var result <number> ^ <number> var result <number> max <value> var result <number> min <value> var result <number> abs var result <vector> * <number> var result <vector> / <number> var result <vector> + <vector> var result <vector> - <vector> var result <vector> x <vector> var result <vector> . <vector> var result <vector> X var result <vector> Y var result <vector> Z var result <string> & <string>
Controlling LCDs
The custom property _Text is not the only way to modify what is being displayed on an LCD panel. You can use the lcd commands to modify what is being displayed. There are 3 modes, write, writeline, clear. All modes operate exactly how you might expect. The write and writeline modes of the command both operate in a similar way to append a value to the end of the LCD panel. The only difference between the two is that writeline adds an extra newline character after the value. The clear mode will erase all text from the LCD panel. Examples:
lcd <blocks> write <value> lcd <blocks> writeline <value> lcd <blocks> clear #LCDExample# lcd LCD clear (The LCD is now blank) lcd LCD write "The value is: " (The LCD now displays The value is: ) lcd LCD writeline 5 lcd LCD write Done! (The LCD now displays The value is: 5
Done!
)

Controlling AutoPilot
If you wish to use ActionScript to control the movement of a ship, there are a few commands that you can use, the most basic being the rc command. The rc command has 4 types: add, set, clear, and mode. The add, set, and clear types can be used to manipulate the waypoint list. The mode type can be used to change the mode of the remote control block between oneway, patrol, and circle. Examples:
rc <block> mode oneway|patrol|circle rc RC mode oneway rc <block> add|set <value> rc RC add "GPS:Super Secret Base:94:56:648:" rc <block> clear rc RC clear

If you wish to simply point the ship in a direction, you can use the orient command to control the gyros. This command uses 3 arguments by default: a block to use a reference, a vector to orient with, and the maximum number of seconds to try to orient. You can also specify the 4th argument after the reference to only use certain gyros. Examples:
orient <block> <value> <value> orient "Remote Control" *direction 30 orient <block> <blocks> <value> <value> orient "Remote Control" @Gyros *direction 10
Antenna Communication
The last and most advanced feature of ActionScript is antenna communication. The basis of antenna communication is the transmit command. This command will modify the specified global variable on any ActionScript programmable blocks that are connected (via antenna or on the same grid). Examples:
transmit <value> <value> transmit "Remote Control",_Position help (The $help variable on the other programmable block will now be set to the Remote Control's position.)
Tip: If you want to use this to execute code on another programmable block, you can use a looping ActionScript that monitors changes to the target global variable.
Raycasting
ActionScript contains commands that can be used to do basic raycasts. You can raycast towards a position, or you can use a distance. There are two raycast commands with straight forward parameters. The raycastc command is just like the raycast command, but the raycastc command will return the center of the object hit instead of the exact position that was hit. Before you use any raycast command, make sure to enable raycasting and wait for the distance you want to be available.
Example:
raycast <block> distance <distance> <variable> raycast <block> position <position> <variable> raycastc <block> distance <distance> <variable> raycastc <block> position <position> <variable> #Raycast# prop Camera _Raycast_Enabled true wait Camera,_Raycast_Availibility >= 500 raycast Camera distance 500 result lcd LCD writeline *result
Mod APIs
ActionScript has support for the mod Hud Alert API. The command sendmsgvia can be used to interface with this mod. Simply use the 3 options to specify a target and include the text, the font, and the duration of the message.
Examples:
sendmsgvia seats <msg> <font> <seconds> sendmsgvia seat <cockpit> <msg> <font> <seconds> sendmsgvia antenna <antenna> <msg> <font> <seconds> sendmsgvia seats "Enemy detected!" Red 10

ActionScript also has support for the Control Module mod. All input types can be accessed as global variables. Simply use the format of $cm.<control> Most are boolean values, but some can be accessed as numbers or vectors. See the Control Module documentation for more information on the types of controls.
Example:
if *$cm.c.strafeleft == true (Do a thing... ) endif
Events
Events can be used in place of loops or wait statements to start scripts when a property or value becomes true. Simply use the event command to register an event and the delevent command to delete an event.
Examples:
event <key> <value> <operator> <value> <scriptname> [argument1] [argument2] ... delevent <key> event door Door,_Door_Open == true lots_of_code delevent door
Common Exceptions
If there is an error in your script, the programmable block may crash and display an error. Here are some common errors and the possible causes:
  • KeyNotFoundException: You tried using a variable that does not exist, or you tried using a variable before it was given a value.
  • NullReferenceException: Commands the require only a single block may display this error when the block specifed is not found. If you look at the error closely, you may be able to see references to the command that caused the error. (Look for things like TerminalLcdFunction or TerminalProperty) Tip: You can use the <block>,_Exists property to check if a block exists before running a command, _Exists wont display a NullReferenceException.
  • ArgumentOutOfRangeException: You may have specified the incorrect number of arguments for a command.
If you still have trouble finding the issue, or believe that it is an issue with the programmable block, feel free to send me your script and I will take a look.
Notepad++
You can use notepad++ to edit actionscript. To enable formatting, simply import the xml file below. To import the file, navigate to Language > Define your language... > Import, then open the xml file. After importing, you may change any of the fonts/colors/styles. By default, the files associated with SE Actionscript are .acs files, and any files opened with a .acs extension will default to SE Actionscript. You can also simply select SE Actionscript from the Languages menu any time.
XML File[drive.google.com]
45 Comments
BustyCatbot 11 Apr, 2024 @ 8:32pm 
Is it possible to read the power usage of a block?
-_Tyger_- 28 Jul, 2023 @ 6:54am 
I'm trying to write a script to lower my suspension and then lock the landing gear. Are there any sample scripts that do something similar I could use?
GOGA 4 Mar, 2023 @ 9:02pm 
How to involve steamapi in your game on flash cs6? input codes in first frame or how?
Luziferius 16 Sep, 2022 @ 7:31pm 
Hi,
I don't really understand how to put a global varible which is a name of a group in a foreach loop
maybe I'm thinking too complex for this!?
avaness  [author] 23 Aug, 2022 @ 7:38pm 
No plans to change anything in the script at the moment
EdTheRabbit 17 Aug, 2022 @ 9:11am 
Thanks! so:
var result "my text here" & *$globalvariable & "further text here"

Also, do you have any trigonometry functions in the script, as I've found myself wanting to use them for precise positioning of some mechanical stuff?
avaness  [author] 17 Aug, 2022 @ 5:53am 
You can build a string with "&" operator and send the variable as the argument to the pb command
EdTheRabbit 16 Aug, 2022 @ 8:41am 
When using a script to launch another programable block with the command : pb "programmable block" arguments, is there an easy way to have the arguments include variables?

I'm trying to work this with the LAMP script by Whiplash for control over specific homing missiles - I'd normally send the following argument to the lamp pb:
"fire --count x --range y z"
I'd like to be able to generate a string so I can insert the variables x, y and z into the argument so I don't have to do repeated calls to the LAMP pb within an overly large script.

Anyway you can help on how to do this please?
GuantanaMo 25 Jul, 2021 @ 12:22pm 
Suggestion: Some sort of wildcard character to choose blocks that contain a certain word.
Rubezagel 22 Jul, 2021 @ 5:55am 
@avaness:
Easy automation requires the argmuent "codesource(codename)", where codesource is a block with the easy automation pseudocode in its custom data, and codename is the name of a specific section of the pseudocode. In Actionscript I am running:
pb "pb_easyautomation" "codesource(codename)"

But it doesn't matter really, it doesn't seem to be a syntax thing or anything like that. There are mutliple error messages that easyautomation would send when a bracket is missing or codesource/codename aren't found. The error I am getting is specific to the argument missing completely.

Other progammable blocks will receive the whole argument just fine, just not easyautomation for some reason. And like I said, once control module is removed from the world (or from actionscripts internal code), everything works as expected. It's a really weird bug.

Got a testworld with everything set up for testing, can send it to you later.