Rhys Davis Games Portfolio
Space Engineers: Hangar Manager Script V2
20/07/2024 | Mod
C# / Personal Project
This script can be found on Github here.
​
A simple in-game script for the game Space Engineers, which manages & automates the functions of vehicle hangars on a large ship / station. The player can import this script into their game through the use of a programmable block.
Two versions were created, V2 is the main script to use in your save file, whereas V1 is merely to show progression from V1 to V2.​
​
Background​
​
In the game Space Engineers, one of the blocks featured is called the “programmable block”, which allows the player to create, compile and run C# scripts to work on their creations. These scripts can help automate functions such as automating an airlock system, or monitoring a ship’s current inventory/ammo count. Integration with the Steam Workshop (and Mod.io) means players can download these scripts straight into the programmable block without the need for programming knowledge.
​​
Glossary of terminology to understand:
​
'Grid'
A constructed entity that holds the blocks of a structure. Forms include small grids, large grids, and station grids. In the grid menu, it will list all functional items on the grid.
​
'Block Group'
Combining several individual entities into one manageable entity in the grid system. A block group is typically used to combine multiple instances of the same type into one group to manage functionality (i.e room lights), or group multiple, separate components into one group for larger system operability. (these group types typically have less functionality as-is, as not every functional block shares the same functions.
​
'Custom Data'
A text field as part of a functional block in which the user can input custom text. This field is typically used in scripts to either accept player’s inputted data, or to present script information to the player.
​​
During a multiplayer session with friends, we were attempting to automate our hangar door to automatically open/close when the player was entering or leaving the space station in a ship. We envisioned using lights to inform the player from a distance if that current hangar was occupied with a ship or if it was vacant - red meaning occupied, green meaning available. The door needed to open when the player was entering or leaving the hangar, and close when the player had landed or left.
The proposed solution must incorporate the functionality of the status lights, warning beacons, the door itself, and sensors to detect the player ship. I understood early on that the integrated system needed to know the current ‘state’ of the hangar to know what to do with all the subsystems. In the end, I took it upon myself to create a solution through the use of a C# script using the programmable block.
​​
V1 - Single Hangar Support
​
Between sessions, I managed to create a script to manage the hangar door we currently had and its subsystems. Two sensors were used to determine the players position to the hangar; one was positioned so its bounds covered the area both outside and inside the hangar door and the other, smaller sensor was used to cover the area just above the landing pad. The smaller sensor area overlapped the larger sensor area. With the two sensors positioned as described, 3 states could be measured, no ship present, ship is entering/leaving, and ship has landed. Additionally, instead of two separate groups of coloured lights toggled on/off, one set of lights was used instead, and their colour would be controlled through the script. The warning beacons were also incorporated to only enable when the ship was entering or leaving.
V1 required the user to edit the script and change the string variables to the display name of the blocks
Each subsystem was grouped together into their own block groups and in the script, string variables were used to allow the user to insert the name of the subsystem group, for example, “Hangar01_lights” was a blockGroup which contained each ‘interiorLight’ block. In total, 5 public variable names were used to allow complete functionality for the door to work.
However, while this script did fulfil our initial requirements, this was not practical for long-term functionality and it wasn’t user-friendly. The script is only able to manage one hangar's worth of subsystems, which means that the player would need one programmable block for each hangar they wish to manage. Additionally, requiring the user to edit the script itself to insert the variable names is non-intuitive and poses a risk in breaking script functionality.
​
A second, more advanced revision was needed, and a list of features was created as a checklist:
-
To manage multiple hangars through one programmable block
-
Check 4 states instead of 3 - empty, entering, landed, leaving.
-
Identify the current ship that is in the hangar by name of grid.
-
Allow use for “custom data” field for user input
-
Auto adjust custom data field to add/remove # of hangars.
-
Save/load custom data field to withstand world restart
-
-
Performance in mind!
​​
V2 - Multiple Hangar Support & Improvements
The main improvement over the first iteration was the support for multiple hangars. One programmable block can store and manage numerous hangar instances through the use of Object-oriented programming principles.
​​
Hangar Class
A hangar class was created to define what a hangar is, to store hangar specific variables such as the hangar ID and current state, and to house hangar functionality including open/close doors and set light colours. These classes could be instances based on how many hangars the end user wishes to manage. A list was then used to contain all hangar instances.
​
For simplicity, the player is no longer required to manually insert the subsystem group name into each variable. Not only was this impractical, the player could accidentally edit the wrong line of code, potentially breaking the script. Instead, The user must combine all subsystem groups into one hangar group, and insert the name of the hangar group instead - drastically reducing the number of variable names from 5+ per hangar to one. Within the hangar class construction, this group is divided up and sorted by block type - all the doors get separated into their own door list, status lights into an interior lights list and so forth.
A cross section of a hangar with a door and landing area. The green squares are the locations of the sensor blocks and the grey boxes are the bounds of the two sensors
The hangar sensors are also featured in this hangarGroup list, but how does the script know which sensor is the hangar area sensor, and which is the landing pad sensor? One way would be to check the name of the sensor, requiring the player to rename the sensor to “hangarSensor” and “landingPadSensor”. However, this would not be ideal as the user could misspell the sensor name, or even write the sensor name in a different language. A different approach was needed. As the sensor covering the hangar would be the larger of the two sensors, comparing the volume of both sensor’s detection area can tell us which sensor is which - regardless of name.
​​
Hangar Class
​While the original script could identify three possible states the hangar could be in (empty, coming or going, and landed) the idea of identifying four states would make the script more versatile. If the player wishes for a certain function to run only when the player is leaving the hangar such as triggering the beacon lights for example, they now can.
A preview of an available hangar, the player can enter this hangar using a ship
An enumeration value was created to store the state of the current hangar, and four values were added - isEmpty, shipEntering, shipLanded, shipLeaving. Within the hangar class, the current state was stored as a variable. When the GetCurrentStatus function is called, it checks the conditions of the two hangar sensors and the previous state value, and sets the correct value. For instance, to move between states, the prerequisite conditions must be met - to move into the ‘isLeaving’ state, the landing pad sensor must return false, and the hangar state must be set to ‘shipLanded’. A similar approach was used to detect if the player is entering the hangar.
The ReturnHangarStatus function returns a string value to be used in the status window of the programmable block, or when implemented, used on an external display. A switch is used on the current hangar state to concatenate a string to return the current state of the hangar, and the name of the ship that is interacting with it.
​​
Performance Management​
Performance was even considered when creating V2. Checking the current hangar’s status by polling the sensors on every tick is unnecessary and overkill, so in the original version, the update frequency was reduced from every tick, to every 100 ticks. However, when adding multiple hangars to manage, the script doesn’t update fast enough - if the user had 10 hangars to manage, and the update was every 100 ticks, the worst case scenario would be a hangar taking ~16 seconds to cycle back around and check for an update.
You can either check every hangar’s status all at once, or split them up and check them individually. Checking them all at once could be problematic if the player is managing hundreds of hangars, which could result in micro stutters on the tick that the operation performs on. On the other hand, checking them one-by-one on each tick would result in a significant delay between hangar checks as it needs time to loop back around so the solution lies somewhere in between.
The new script was changed to update every 10 ticks as for now, this is the best of both worlds - a responsive but non-intensive system. A future goal would be to divide up the amount of hangars into manageable sub groups based on how many are entered, and perform the status check on groups at a time. For instance, if the player had 100 hangars, the script could check 10 at a time, that way, there wouldn’t be a noticeable delay between iterations, but many can be checked. Larger lists will naturally require a greater compute time, but by dividing it up, both the tick compute cost and loop time will be reduced to coincide with one another.
​​
Custom Data​
To allow players to add hangars to the system, changes were made to the initial script to allow the use of the custom data field in the programmable block. On first compilation, the script will prompt the player to set the number of hangars that should be managed by changing a data value in the custom data field, and after recompiling, will create a list of editable text entries that the player can use to add in the name of the hangar group.
By using the "Custom Data" screen, the player can insert the name of the hangar group they want to manage - separating user input from the script itself.
Conveniently, the data entered into the custom data field is saved server-side, and will auto update when changes are made to the custom data. A function was created that would process the config changes every time the script was initialised. It starts by clearing the data of the config from before, then reading the custom data field to set new values. By saving and loading a script config, it makes the script more versatile for use in multiplayer or on public servers as the data is synchronised between all clients.
​​​
Error Checking​
Error checking and exception handling are vital in scripts where the end user is supposed to have some input in how the script works. As a developer, it is part of the job to understand error messages, but to everyone else, an error message can be confusing and frustrating. Outputting an error message in a clear and concise way can help the end user in fixing a problem that they might have caused.
An example of error handling where the user misspelt their hangar group name. This message will appear within the programming block interface when the user attempts to compile the script
In regards to the hangar script, each critical component was checked to ensure that it was set correctly. For example, the hangar name is important as without the correct name, the script can’t instantiate a hangar. If the player has incorrectly entered their hangar group name, an error message will be displayed on the programmable block interface that informs the player which hangar name is wrong. Additionally, only two sensors are allowed to be used in the hangar group. Any more/less and the sensor identification system wouldn’t work properly, so if there is an incorrect number found in the block group, the user will be notified. Unlike the hangar group name and sensors, other variables such as the doors, status lights, and warning lights are not critical to the functionality of the script. If the player hasn’t inserted any warning lights into their hangar group, they will just be ignored.
​​​
Scalability​
In terms of scalability, the script should work on a variety of different block types. The in-game “Airtight Hangar Door” blocks extend from the “door” class, meaning any door block should work with the script. If the player wants to create a micro-hangar for drones using regular passageway doors, they can.
​
Additionally, modded blocks should also work, so long as they too extend from the same classes. In fact, in testing, a modded sensor block was used which detected a much larger area, as well as a larger hangar door as we had planned on creating a larger hangar for our main largeGrid ship.​
​​​
Potential Changes & Future Development​
There were some changes that were not critical to the core functionality of the script that would be nice to add. For instance, allowing the player to easily customise the status light colours instead of them being red/orange/green would allow them to create a colour theme that matches their creation’s aesthetics. While the player can edit the script to add in their specific colours, the aforementioned issues with script editing are still present. Additionally, the idea of outputting all the hangar statuses to an external display/control seat screen was raised, allowing for the creation of a control hub room to monitor each hangar - which would be useful in larger station designs.
