Space Engineers

Space Engineers

Not enough ratings
USAP - Universal Ship Assistant Program - Complete Guide
By SJ_Omega
A complete guide detailing the separate "Mini-scripts" included in USAP, as well as user commands and custom data parameters.

Script Link:
https://steamcommunity.com/sharedfiles/filedetails/?id=2922104789
   
Award
Favorite
Favorited
Unfavorite
COMMANDS (Overview)


List of all USAP commands that can be run from the terminal or mapped to a hotbar. For a more detailed explanation of each command, see the specific section they belong to.

INVENTORY
  • UNLOAD
  • RELOAD
  • REFUEL
  • RESUPPLY
  • SET_LOAD_COUNT <count>
  • RESET_LOAD_COUNT

CONSTRUCTION PROFILES
  • NEW_PROFILE <profile name>;<source block name>
  • SELECT_PROFILE <profile name>
  • UPDATE_PROFILES

TAG EDITOR
  • ADD_PREFIX <tag>
  • ADD_SUFFIX <tag>
  • DELETE_PREFIX <tag>
  • DELETE_SUFFIX <tag>
  • REPLACE_PREFIX <old tag> <new tag>
  • REPLACE_SUFFIX <old tag> <new tag>
  • SWAP_TO_PREFIX <tag>
  • SWAP_TO_SUFFIX <tag>

CRUISE CONTROL
  • CRUISE_ON
  • CRUISE_OFF
  • TOGGLE_CRUISE
  • THROTTLE_UP <velocity>
  • THROTTLE_DOWN <velocity>

LANDING GEAR
  • GEAR_DOWN
  • GEAR_UP
  • TOGGLE_GEAR
  • GEAR_TIMER // call from LG timer
  • TIMER_LOCK // simple version of Gear_Timer (non-cyclical)
  • SWAP_GEAR_DIRECTION
  • ON_RETRACT <behavior> // "AUTOLOCK", "TURNOFF", or default
  • CLEAR_GEAR_DATA
  • LOCK
  • UNLOCK
  • SWITCH_LOCK

BROADCAST SCREEN MIRRORING
  • NEXT_CHANNEL <receiver #> // Receiver # is optional. Will default to first Receiver in ship.
  • LAST_CHANNEL <receiver #> // Receiver # is optional. Will default to first Receiver in ship.
  • NEXT_SUBCHANNEL <receiver #> // Receiver # is optional. Will default to first Receiver in ship.
  • LAST_SUBCHANNEL <receiver #> // Receiver # is optional. Will default to first Receiver in ship.

MISC
  • TRIGGER_<Key> // Key specified in Custom Data. Default "DOOR".
  • SET_GRID_ID
  • REFRESH
PREFIX / SUFFIX TAG EDITING


The following functions allow you to add, remove, and edit your own ship-tags at the beginning or end of every terminal block in your ship or station. This will allow you to more easily distinguish blocks from a grid when it is docked or connected to another grid.

COMMANDS
  • ADD_PREFIX
    Adds a prefix tag to every terminal block.
    • Requires the desired tag as an argument
    • Example: ADD_PREFIX ABC
    • Example would add tag ABC to the beginning of each terminal block name.

  • ADD_SUFFIX
    Adds a suffix tag to every terminal block.
    • Requires the desired tag as an argument
    • Example: ADD_SUFFIX XYZ
    • Example would add tag XYZ to the ending of each terminal block name.

  • DELETE_PREFIX
    Deletes the specified prefix from the beginning of all terminal block names.
    • Requires the tag to be deleted as an argument.
    • Example: DELETE_PREFIX ABC
    • Example would remove the tag ABC from the beginning of all terminal block names.

  • DELETE_SUFFIX
    Deletes the specified suffix from the end of all terminal block names.
    • Requires the tag to be deleted as an argument.
    • Example: DELETE_SUFFIX XYZ
    • Example would remove the tag XYZ from the end of all terminal block names.

  • REPLACE_SUFFIX
    Deletes the old suffix on all terminal blocks and replaces it with the new suffix
    • Requires the old suffix followed by the new suffix as arguments.
    • Example: REPLACE_SUFFIX XYZ UVW
    • Example would replace all suffixes XYZ with UVW
    • Blocks without the old suffix will still have the new suffix added.

  • REPLACE_PREFIX
    Deletes the old prefix from all terminal block names and replaces it with the new prefix.
    • Requires the old prefix followed by the new prefix as arguments.
    • Example: REPLACE_PREFIX ABC DEF
    • Example would replace all prefixes ABC with DEF

  • SWAP_TO_PREFIX
    Will delete the specified tag from the end of all terminal blocks and add it to the beginning of the block name.
    • Blocks that don't have a suffix will still have the specified tag added as a prefix.
    • Example: SWAP_TO_PREFIX XYZ
    • Example would move the tag XYZ from the end of each terminal block to the beginning.

  • SWAP_TO_SUFFIX
    • Will delete the specified tag from the beginning of all terminal blocks and add it to the end of the block name.
    • Blocks that don't have a prefix will still have the specified tag added as a suffix.
    • Example: SWAP_TO_SUFFIX ABC
    • Example would move the tag ABC from the beginning of each terminal block to the end.

HINTS
  • Avoid using spaces in your ship tags.
  • Ship tags are not restricted to only three letters or all caps.
  • Using prefixes as opposed to suffixes will group all of your ships blocks together alphabetically in the terminal. For this reason it is highly recommended to use prefix ship tags.
INVENTORY: AMMO LOAD-OUTS


SET UP
  1. Add a Magazine Tag to the name of any desired inventories.
  2. Run the REFRESH command.
  3. Check the Custom Data field for each of the designated inventory blocks, to ensure the Ammo Profile has loaded.
  4. Tweak the ammo amounts as desired.
  5. Run the RELOAD command while docked to an inventory that is stocked with your desired ammo types and has the Ammo Supply Tag in its name (Default: [WEP]).

MAGAZINE TAGS
Include one of the following tags in the name of an inventory block to specify what type of ammunition should be loaded to it.
  • [MAG] - Loads all ammo types to the inventory.
  • [MAG:GATLING] - Gatling Rounds
  • [MAG:MISSILE] - 200mm Missiles
  • [MAG:ARTILLERY] - Large Caliber Ammo
  • [MAG:ASSAULT] - Medium Caliber Ammo
  • [MAG:AUTO] - Auto Cannon Rounds
  • [MAG:RAIL] - Large Rail Gun Ammo
  • [MAG:MINI-RAIL] - Small Rail Gun Ammo

NOTE: Tags relevant to a specific ammo type are mainly for the ease of set-up. Once the ammo amounts have been specified in the Custom Data field, the tag can be replaced with a normal Ammo Tag ([MAG]) or left as is.

COMMANDS
  • RELOAD
    • Reloads all tagged inventories.
    • Refuels reactors tagged with the reactor tag (Default: [PWR]).
    • Restocks O2/H2 generators tagged with the ice tag (Default: [H2O]).
INVENTORY: REFUEL


Designate Reactors to be resupplied with Uranium and O2/H2 Generators to be resupplied with ice.

SET UP
  1. Add the Reactor Tag (Default: [PWR]) to the name of any desired reactors.
  2. Add the Ice Tag (Default: [H2O]) to the name of any desired O2/H2 Generators.
  3. Add the Fuel Supply Tag (Default: [SRC]) to the name of any inventories that you want to restock Uranium from. This will likely be on a different grid.
  4. Add the Ice Supply Tag (Default: [ORE]) to the name of any inventories that you want to restock ice from.
  5. Run the REFRESH command.
  6. Check tagged Reactors and O2/H2 Generators to ensure and tweak supply numbers written to Custom Data fields.

COMMANDS
  • REFUEL
    Resupplies any designated Reactors or O2/H2 Generators from designated source inventories.
INVENTORY: UNLOADING ORE


Unload mining inventories a single press of a button. Keep track of the number of loads you've deposited.

SET UP
  1. Add the Payload Tag (Default: [MIN]) to the name of any desired inventories on your ship.
  2. Add the Ore Tag (Default: [ORE]) to the name of any inventories you want to deposit ore in.
  3. Run the REFRESH command to ensure that mining inventories are recognized by the script.

COMMANDS
  • UNLOAD
    Transfers ore from payload inventories to destination inventories, provided there is room and a connected conveyor path between them.

  • SET_LOAD_COUNT <value>
    • Sets the current load count to the specified <value>.
    • Example: SET_LOAD_COUNT 10
    • See section DISPLAYS for more about Load Counts.

  • RESET_LOAD_COUNT
    Sets current Load Count to 0.
INVENTORY: CONSTRUCTION PROFILES


Creates selectable Construction Profiles for easy cargo management and reload in Construction Ships. Prototype Profiles are saved to the Custom Data field of the USAP Program block.

SET UP
  1. Add Component Tag (Default: [CST]) to the name of any inventory blocks that construction parts should be loaded to.
    This can include functional blocks like Welders.

  2. Run the REFRESH command.

  3. Check and adjust Item Numbers in Custom Data of both the Inventory blocks as well as the main Program block as needed.

  4. Rename any supply inventories in bases and mother-ships with the Component Supply Tag (Default: [CMP]).

COMMANDS
  • NEW_PROFILE <profile name>;<optional block name>
    Creates a new profile of specified name.
    • An inventory block name can be entered as a second optional argument.
    • If the optional argument is entered, the new profile will be based on the current contents of that inventory block.
    • Example: NEW_PROFILE Electronics;Cargo Block 1


  • SELECT_PROFILE <profile name>
    Selects one of the listed construction profiles and syncs all tagged construction inventories with that profile.

  • UPDATE_PROFILES
    Used to sync all tagged construction inventories with manually edited profiles.

CUSTOM DATA
  • Program Block
    • Profiles - Comma separated list of stored profiles. The first entry in this list should be the currently active profile.

    • [Profile: < profile name>] - Prototype profile.
      • Amounts in prototype profiles are for the standard Large Grid - Small Cargo (15625L)
      • Amounts can be manually edited.
      • Profiles for other inventories will be adjusted based on their volume






  • Inventory Blocks
    • Sync_To_Profiles - If set to False, profile for this block will not be adjusted when profile commands are run.

    • Loadout - List of parts and amounts for each that the program will attempt to load when the RESUPPLY command is run.

NOTES
  • DEFAULT PROFILES: By default, script will load 3 default profiles: Basic, Advanced, and Armor.

  • MANUAL EDITS: Take care when manually editing a profile. The program will only be able to load as many parts as an inventory's volume will permit. Setting the quantities too high may lead to unexpected behaviors.
LANDING GEAR


Automate the set-up and operation of a retractable Landing Gear Assembly on your ship.

SET UP
  1. Build retractable Landing Gear Assembly:
    • Required Blocks: Timer Block and at least one piston, rotor, or hinge.
    • Optional Blocks: Landing Gear/Magnetic Plates, Connector, Merge Blocks, Lights
    • Ensure that assembly can run through its full set of motion without problems.

  2. Ensure that Landing Gear Assembly is in its Extended position.

  3. Rename all blocks in Landing Gear Assembly to include the Landing Gear Tag (Default: [LG]) in their name.

  4. Run REFRESH command.

  5. Select the Landing Gear Timer from the terminal and click on the Setup actions button.

  6. Drag the USAP Program block to the hotbar, and select the action Run.

  7. In the Argument field, type GEAR_TIMER, then click Confirm.

  8. Map the Landing Gear Timer to your desired action bar, with the action Trigger now.
    Triggering this timer will allow you to extend and retract your landing gear.


COMMANDS
  • GEAR_TIMER - Command to run from the Landing Gear Timer's action bar.
    • Use this command so that the Landing Gear Timer will "cycle" the landing gear assembly. (Recommended)
    • For more control, use argument TIMER_LOCK.

  • TIMER_LOCK - Alternative version of GEAR_TIMER
    • Does not cycle landing gear.
    • Use this command for setting up separate GEAR_DOWN and GEAR_UP commands.

  • GEAR_DOWN - Extends the Landing Gear Assembly.

  • GEAR_UP - Retracts the Landing Gear Assembly.

  • TOGGLE_GEAR - Extends Landing Gear Assembly if retracted, and retracts it if extended.
    NOTE: It's recommended to use the GEAR_TIMER argument in the Landing Gear Timer and trigger that timer directly instead of using this command.

  • SWAP_GEAR_DIRECTION - Exchanges the Extended and Retracted states of the Landing Gear Assembly.

  • ON_RETRACT <behavior> - Sets Retracted behavior of Landing Gear Blocks and Magnetic Plates to the given argument:
    • "AUTOLOCK"
    • "TURNOFF"
    • Default (Do Nothing)

  • ON_EXTEND <behavior> - Sets Extended behavior of Landing Gear Blocks and Magnetic Plates to the given argument:
    • "AUTOLOCK"
    • Default (Do Nothing)

  • CLEAR_GEAR_DATA - Deletes Custom Data for the Timer as well as all Pistons, Hinges, and Rotors associated with the Landing Gear Assembly.
    • Used if Landing Gear parameters need to be reset for the entire Landing Gear Assembly.
    • All Custom Data for these blocks will be automatically set based on the current state of each block when the script is recompiled, the save game is reloaded, or the REFRESH command is run.

  • LOCK - Attempts to lock all Landing Gear Blocks, Magnetic Plates or Connectors associated with the Landing Gear Assembly.

  • UNLOCK - Unlocks all Landing Gear Blocks, Magnetic Plates and Connectors as well as deactivating all Merge Blocks associated with the Landing Gear Assembly.

  • SWITCH_LOCK - If any Landing Gear Blocks, Magnetic Plates or Connectors are locked, this will lock them. Otherwise it will attempt to lock them.

CUSTOM DATA
Custom Data settings are auto populated on set-up based on the state of the blocks in the Landing Gear Assembly. They can also be manually edited as needed.

  • Timer
    • Extended - Whether the Landing Gear Assembly is Extended/Extending or Retracted/Retracting.

    • Extension Delay - Time between when the Landing Gear Assembly begins extending and when it should be fully extended.

    • Retraction Delay - Time between when the Landing Gear Assembly begins retracting and when it should be fully retracted.




  • Rotors/Hinges/Pistons
    • Extend To Positive - True if positive velocity coincides with extension of the Landing Gear Assembly.

    • Extend Velocity - In m/s for Pistons and deg/s for Rotors and Hinges.

    • Extend Velocity - In m/s for Pistons and deg/s for Rotors and Hinges.

    • Off When Stationary - When True, the block will power off at the end of Extension/Retraction. If Braking Torque is 0, the block may be free to move.



  • Landing Gear/Magnetic Plates
    • On Retract - "AutoLock", "TurnOff", or Default (blank).

    • On Extend - "AutoLock" or Default (blank).












  • Merge Blocks
    • Disable On Extend - Power the block OFF when the Landing Gear Assembly begins to extend.
    • Disable On Retract - Power the block OFF when the Landing Gear Assembly begins to retract.
    • Enable When Stopped - Power the block ON when the Landing Gear Assembly finishes extending or retracting.







  • Lights
    • Color on Extend - RGB light color when the Landing Gear Assembly is extended.

    • Color on Retract - RGB light color when the Landing Gear Assembly is retracted.

    Hint: Setting the light color to 0,0,0 (black) will effectively disable the light, without having to power it off.
CRUISE CONTROL


Set a target forward velocity that the ship will automatically try to match. Good for saving fuel when leaving a planet.

SET UP
  1. In the terminal, create a group of all of the thrusters that you want to be part of the Cruise Control.
    • These thrusters should all be pushing in the same direction that the Reference Cockpit is facing.
    • Thrusters can be of different types and sizes.

  2. Copy the thruster group name and paste it after the equals sign after for parameter Cruise Thrusters in the Custom Data field of the Program Block.

  3. Copy the block name of you reference control block (i.e. Cockpit, Seat, Remote Block), and paste it after the equals sign for parameter Cockpit in the Custom Data field of the Program Block.


COMMANDS
  • CRUISE_ON - Enables Cruise Control


  • CRUISE_OFF - Disables Cruise Control

  • TOGGLE_CRUISE - Toggles Cruise Control. IF throttle is at 0 and Cruise Control is Toggled On, Throttle will be set to Max Speed.

  • THROTTLE_UP <velocity> - Increase the target velocity in Meters/Second by the specified amount, up to the maximum velocity. If Cruise Control was off, it will be toggled on.

  • THROTTLE_DOWN <velocity> - Decreases the target velocity in Meters/Second by the specified amount. If target velocity hits 0, Cruise Control will be disengaged.


CUSTOM DATA


  • Cruise Thrusters - Name of the Group of (forward pushing) thrusters to be used for Cruise Control
  • Cockpit - Forward facing cockpit used as a reference for cruise control. Can be a remote block.
  • Cruise Gains - Vector of the (Proportional, Integral, Derivative) gains for the cruise control. Individual values can be decimal or whole numbers. Tweak these values if you need to smooth out the behavior of the controller. Note: the P-Gain is automatically adjusted when the cruise control is started, according to available thrust and ship mass. Changing this value will adjust the factor by which this value is adjusted.
  • Max Speed - Maximum speed (m/s) that cruise control is allowed to throttle up to. Can be set higher in modded worlds.
  • Safety Height - Height (in meters) below which cruise control will disengage if the ship is aimed at 45° or more in the direction of the ground.
  • Zero-G Disable - If true, cruise control will disengage when the ship leaves planet gravity.
DISPLAYS


Display vital data relevant to mini-scripts being used on the grid. Data should only be visible for the parts of the script that are being used.

SET UP
  1. Set up any of the following USAP Mini-Scripts:
    • Cruise Control
    • Landing Gear
    • Construction Profiles
    • Mining Inventories

  2. Add the Display Tag (Default: USAP Display) to the name of any LCD block that you wish to display script data.
    • This is compatible with any block that has at least one LCD surface.

  3. Run the REFRESH command.

  4. Edit the Custom Data of the display block to change which screen the Display is shown on, or disable any of the data outputs, then run the REFRESH command again.

CUSTOM DATA
Display parameters will only display for Mini-Scripts that have already been set up on the grid. For example, if construction profiles have been set up, then the "Show Active Profile" parameter should appear in the custom Data of any tagged Display blocks.






  • Any Display Block
    Set any of the following parameters to True if you want them to be displayed or False if you don't want them to be displayed.
    • Show Load Count - (Mining) Displays the number of times the mining payload has been successfully unloaded.

    • Active Profile - (Construction) Displays the currently active Construction Profile.

    • Show Landing Gear - Displays if the Landing Gear Assembly is currently extended or retracted.
    • Show Parking Status - Indicates if any of the Landing Gear blocks or Magnetic Plates associated with the Landing Gear Assembly has successfully locked.

    • Show Target Speed - (Cruise Control) Shows the Target Reference Speed that the Cruise Control will attempt to match.
    • Show Throttle Level - (Cruise Control) Shows the current Throttle Output of the Cruise Control. If Cruise Control is disengaged, it will display "Off".

  • Display Blocks with Multiple Screens
    • Show on Screen <number> - If set to True, the screen with matching number will be used as a USAP display.
      • The Main Screen is always screen 0.
      • If you don't want a screen to be used, make sure that it is set to False.
      • More than one screen can be used on the same block.
TIMER TRIGGERS


Triggers remote timers on a grid that you are docked or merged with.




SET UP
  1. Add Trigger_<name>= as a parameter under the [USAP Triggers] header in the Custom Data field of the Program Block.
    • <name> is your own custom trigger name.
    • Avoid including spaces in your trigger name.
    • Example: Trigger_Ramp=

  2. Add a short phrase after the equals sign, that all timers you want to trigger have in their name.
    • It does not need to be the entire block name.
    • It should be specific enough that it won't trigger random timers.
    • BAD: Trigger_Ramp=Timer
    • GOOD: Trigger_Ramp=Ramp Timer

  3. Rename timers you want to trigger on other grids to include the short phrase from the previous step.
    • Example: Bay 1 Ramp Timer

  4. Dock or merge your ship to a grid with a renamed timer, and run the Program Block with the Trigger Parameter as an argument.
    • Example: Trigger_Ramp

CUSTOM DATA
  • Program Block
    • Ref_Distance - Distance in meters the script will search for an appropriately named timer.
    • Reference - Name of block that the Reference Distance is measured from.

MISCELLANEOUS


COMMANDS
  • SET_GRID_ID
    • Sets the Grid identifier in all blocks used by the script.
    • Grid ID helps the script to distinguish between blocks from this grid and another grid, even when connected with a Merge Block.
    • Takes an optional argument to specify your own Grid ID or name.
    • Example: SET_GRID_ID Good Ship Lollypop
    • Without an argument, grid's in-game ID number will be assigned (recommended).
    • Supported by other LFS scripts, including Planet Map 3D!
    • Avoid running this command when connected to other grids.
    • It may be good to set the ID number when pasting the ship in creative, or after building from a projector.

  • REFRESH
    • Rebuilds the script.
    • Run after adding blocks to the script or editing their Custom Data field.

BROADCAST SCREEN MIRRORING


Allows you to send and receive LCD text to and from separate grids. Works for multi-screen blocks. An individual screen can be either a Broadcaster or a Receiver.



SETUP
After setting up USAP in the programmable block, rename any blocks with LCDs that you want to use as a broadcaster or receiver to include the tag "[Comms]" in the block name.

BROADCASTER SETUP
In the Custom Data of any block with screens you want to broadcast, update the "Screen Channel" parameter to BROADCAST:<Channel Name>




Example:
Screen Channel=BROADCAST:Super Secret Channel


The <Channel Name> is a custom text string, and can be anything you want. Any RECEIVERS listening on that same channel will receive the text that is written to this screen. A default channel should already be set in this block when it's originally added to the script. WARNING: Channel Names are case sensitive!

RECEIVER SETUP
In the Custom Data of any block with screens you want to receive broadcast messages, update the "Screen Channel" parameter to LISTEN:<Channel Name>

Example:
Screen Channel=LISTEN:Super Secret Channel


Note: When a block is renamed with the tag "[Comms]", the first screen in that block will default to BROADCAST behavior. These can be reconfigured to LISTEN behavior. Alternatively, you can use the tag "[Comms-RCV]", and the first screen in the block will default to LISTEN behavior.

At first, the screen may show grey text saying that it's disconnected, loading, or searching. Once it receives a message, the text color should change to the color specified in Custom Data.




Any grids with screens listening on Super Secret Channel should will be updated as the Broadcaster LCD continues to broadcast. If the Broadcaster LCD stops broadcasting, or goes out of range, the Receivers listening on that channel will display the grey Disconnected text, as well as a warning symbol.

RECEIVER COMMANDS
Receivers can be tuned to a list of channels found in the Custom Data of the USAP Program Block.

In order to cycle through the channels you can run one of the following commands from the USAP Program Block, or map the command to your hotbar.

NEXT_CHANNEL <optional screen ID>
Cycles the receiver to the next channel in the list.
Example: NEXT_CHANNEL 1
Cycles receiver #1 to the next channel

LAST_CHANNEL <optional screen ID>
Cycles the receiver to the previous channel in the list.
Example:LAST_CHANNEL 3
Cycles receiver #3

SUB-CHANNELS
If multiple grids are broadcasting on the same channel, broadcast receivers can cycle between all the grids broadcasting on that channel with the following commands:

NEXT_SUBCHANNEL <optional screen ID>
Cycles the receiver to the next grid broadcasting on the currently selected channel.
Example:NEXT_SUBCHANNEL 2
Cycles receiver #2 to the next grid broadcasting on receiver #2's current broadcast channel.

LAST_SUBCHANNEL <optional screen ID>
Cycles the receiver to the next grid broadcasting on the currently selected channel.
Example:NEXT_SUBCHANNEL 6
Cycles receiver #6 to the previous grid broadcasting on receiver #6's current broadcast channel.

If no Screen ID is provided USAP will default to the receiver with the lowest ID number. This is useful for grids with only one receiver. If the grid has multiple receivers, the screen ID will appear in parentheses in the upper left of the screen.



ADDING CHANNELS
The channels that USAP listens on can be updated in the Custom Data of the USAP Program Block with the parameter Receiver Channels. This is a multi-line parameter. As such each value needs to follow a pipe-symbol "|" on a new line.

By default USAP will populate the channel list as follows

Receiver Channels=
|USAP Channel 0
|USAP Channel 1
|USAP Channel 2


These values can be removed, changed, updated, etc. More channels can be added, etc;