SAMv2 - a script for Space Engineers

https://steamhost.cn/steamcommunity_com/sharedfiles/filedetails/?id=1653875433

• Have your ship autonomously and automatically fly between any multiple Connectors in the Star System, without having to worry about recording waypoints.
  
• Turn your ships into autonomous navigation vessels. Without a need for a cockpit, just tell it where you want to go, and it goes, with or without you as a passenger.
  
• Automate cargo runs with ease. In the plannet and in Between planets.
  
• Worried about mountains and collisions? Worried about your Remote Controller getting stuck? Don't worry anymore.

Ships Require:

• Remote Controller - Add one anywhere in the ship.
  
• Camera - Ideally 3, one facing UP, FRONT & DOWN. Avoid that they are obstructed by other blocks in the ship.
  
• Programmable block - Add one to your ship, add this script to it.
  
• Connector - At least one.

Ships can Additionally have:

• LCD Panel - At leat one. Add a wide second one for having a Syslog.
  
• Antenna - Important as this allows the ship to learn about Connectors in other grids.
  
• Cockpit - Used for the LCD Panels.
  
• Batteries - If you want to make sure batteries are charged before navigating to the next dock.
  
• Cargo Containers - If you want to make sure Cargo Containers are loaded or unloaded before navigating to the next dock.

Stations Require:

• Programmable block - Add one to the grid.
  
• Connector - At least one.
  
• Antenna - Important as this allows the Station to advertise its connectors to other grids. However this block does not need to be tagged. Make sure it has enable broadcast set.

SAMv2 supports two methods for tagging a block. SAM will first check Custom Data, and then the Block Name. It does not need to use both at the same time. Either one will work.
Only blocks on the same construct will be considered (connected by pistons or rotors, but not connectors).

This allows tagging the block using the block name. Example for an LCD Pannel:


This allows the blocks to be tagged without polluting the block name, good for antennas. Example, add the following to the Custom Data of an LCD pannel:


Notes for the use of Custom Data with other scripts
SAMv2 scans every line in Custom Data and checks if there is a SAM.something. If there is, it uses it. It leaves everything else untouched.

Tag all required blocks above with SAM. More specifically:
For Station Programmable blocks

• add the tag "advertise". Example: [SAM ADVERTISE]
  
• override the grid name (no spaces). Example: [SAM ADVERTISE Name=NewGridName]

For Station Connectors:

• override the block name (no spaces). Example: [SAM Name=NewConnectorName]

For Ships Wide LCD Pannels:

• add the tag "log" for seeing the Syslog. Example: [SAM LOG]

Additionally, For Ships Programmable blocks use tag LIST or LOOP:

• [SAM LIST] - Hops dock to dock in the list till the end.
  
• [SAM LOOP] - Hops dock to dock in the list till the end then starts over.
  
• [SAM] - Navigation needs to be manually started for every dock in the list.
  
• [SAM LIST Wait=20] - Also works for LOOP, overrides the 10 second wait times between docks.

IMPORTANT: SAMv2 *does not* by itself load, unload or charge anything. It needs an external system to do it. SAMv2 only monitors for full, empty, charged or uncharged blocks.

While in LIST or LOOP modes, it is possible to tell a dock to wait to cargo to be Loaded or Unloaded or Batteries to be Charged before moving to the next dock. This can be done with the "select" button in the NAV screen.

The respective Cargo Containers and or Batteries need to be tagged with [SAM].

Hydrogen tanks by default are "Charged", all they need is to have the [SAM] tag too. If there is a mix of Hydrogen tanks and Batteries tagged, then "Charge" will wait for all the batteries to be charged and all the tanks to be filled.

If you want to haul hydrogen, you can tag the Hydrogen tanks with [SAM CARGO] and it will be considered cargo instead.

It is also possible to define what Empty and Full means for Batteries, Tanks and Cargo Containers. The following Tag means to consider empty whenever the charge or fill is bellow 10%, and to consider full whenever the charge or fill is above 90% of the battery max charge, Cargo max volume or tank max volume:

Also for Batteries and Tanks, use the following tag to force the batteries to recharge and tanks to stockpile. Note that Hydrogen Tanks with the CARGO tag will stockpile automatically;

Issue the following commands to the Programmable Block:

• PREV - Previous item.
  
• NEXT - Next item.
  
• SELECT
  
  • Select the existing item (for Configuration screen).
    
  • Changes wait mode (Charge,Load,Unload) (for Navigation screen).
• SCREEN - Changes back and forth between Navigation and Configuration screens.

• ADD ORBIT - Adds the GPS position in Orbit right above the ship.
  
• ADD <GPS> - Adds the GPS position as an entry. Uses the GPS name as the entry name.
  
• ADD [STANCE] <Name> - Adds the present ship position or connected dock as an entry.
  • If ship is connected to a dock it will add the new dock use <Name> to override the dock name;
    
  • <Name> is optional - adds a name;
    
  • STANCE is optional - when adding the current position it also adds the current orientation (ignored when adding a dock);
• REMOVE - Removes entries added with the ADD command and old docks that have stopped being advertised (have a ? before them)

• START - Starts navigation to the selected dock in the Navigation screen.
  
• START PREV - Selects the previous dock in the Navigation screen and Starts navigation.
  
• START NEXT - Selects the next dock in the Navigation screen and Starts navigation.
  
• START (GPS Coordinate) - Starts navigation to the GPS coordinate copied from the GPS screen.
  
• STOP - Immediately stops navigation.
  
• TOGGLE - Toggle between START/STOP.
  
• GO (Connector Name) - Will immediately start navigating to the Connector Name. The connector name must be the one given with the TAG Name.

• CLEARSTORAGE - Clears storage, requires the program block to recompile.
  
• CLEARLOG - Clears the Log.

Use the following TAGs:

• [SAM] - Shows the selected screen (either NAV or CONF).
  
• [SAM LOG] - Shows the log.
  
• [SAM NAV] - Shows the NAV screen.
  
• [SAM CONF] - Shows the configuration screen.
  
• [SAM STAT] - A two line status useful for corner screens.
  
• [SAM OVR] - Allows you to override the font size and style.

SAMv2 can be told to ignore thrusters:

Use the following attributes to override specific values:

• [SAM Name:NewName] - Overrides the grid name.
  
• [SAM MaxSpeed:95] - Maximum speed used in NAVIGATING and CONVERGING modes.
  
• [SAM ConvergingSpeed:50] - Converging speed.
  
• [SAM DockingSpeed:2.5] - Speed during the docking/undocking procedure (before/after connector).
  
• [SAM TaxiingSpeed:10] - Speed during taxiing. Before docking, during path following.
  
• [SAM ApproachingSpeed:50] - Approaching speed.
  
• [SAM TaxiingPanelDistance:10] - When using Path-Docking, the distance from the panel.
  
• [SAM TaxiingDistance:10] - How close will the ship get before starting the docking procedure.
  
• [SAM DockDistance:5] - How close to the dock before starting the docking procedure.
  
• [SAM UndockDistance:10] - How far a distance to take after undocking before starting navigation.
  
• [SAM ApproachDistance:500] - Distance from the target at which Approaching navigation mode starts.
  
• [SAM NODAMPENERS] - SAMv2 disables dampeners after docking in order to avoid thrusters from firing while docked (happens when docked to ships). This can be disabled with PB Tag NODAMPENERS;
  
• [SAM IGNOREGRAVITY] - The ship will ignore gravity for alligning. This is usefull for rocket like ships that always face one direction regardless of gravity.

Note that during navigation the script will go through these modes:
UNDOCKING -> [TAXIING] -> [ NAVIGATING | CONVERGING ] -> APPROACHING-> [TAXIING] -> DOCKING

• NAVIGATING -> Used when obstacles are detected in the path.
  
• CONVERGING -> Used when no obstacles are detected in the path.
  
• TAXIING-> Only during Path docking.

Some modded connectors have their local space reversed from the vanilla connectors. For these use the TAG REV:

• [SAM REV] - Reverses modded copnnectors;

If you have a ship with many connectors where you use some for other ships to dock, you can define a connector that the main ship will always use for docking.

• [SAM MAIN] - Ship will always dock with this connector. Will not advertise this connector if the ship is also an advertiser.

Use the following TAGs:

• [SAM PANEL0: ] - Shows the default screen in Panel0.
  
• [SAM PANEL0: PANEL2:LOG] - Shows the default screen in Panel0 and the LOG in Panel2.
  
• [SAM PANEL0: PANEL2:LOG OVR] - Same as above and allows Overriding text format like in text panels.
  
• [SAM PANEL1:CONF ] - Shows the CONF screen in Panel1.

Notifications can be sent to timer blocks when certain actions are accomplished. Only timers in the same construct are triggered. Tag your timers with:

• [SAM DOCKED] - Starts the timer when the ship docks.
  
• [SAM UNDOCKED] - Starts the timer when the ship undocks.
  
• [SAM NAVIGATED] - Starts the timer when the ship finishes navigation (regardless of docking).
  
• [SAM STARTED] - Starts the timer when the ship starts navigation.

You can use LCD screens with an attribute named "Name" with the same value as the one your Dock has. The LCDs are sorted by distance to the Dock, and the ship will follow them all the way. This can be used to avoid colisions or when your dock is inside some building. See the video for more details.

It is possible to send commands to configure and run all SAMv2 ship provided they are connected via an antenna. See the video for an example:


The following command sends the ShipName to ConnectorNameA in GridNameA to charge its batteries and load its cargo, then go to ConnectoB to unload its cargo:

Same as above except the navigation is not started:

This starts the navigation:

• step - adds the configured docks and enables navigation to only go to the next dock;
  
• run - adds the configured docks and enables navigation to go to all the docks till the end of the list, then stop;
  
• loop - adds the configured docks and loop navigates forever;
  
• step conf - only configures the docks and the mode, does not start;
  
• run conf - only configures the docks and the mode, does not start;
  
• loop conf - only configures the docks and the mode, does not start;
  
• start - starts navigation with the existing configuration;
  
• stop - stops navigation;

• Charge
  
• Charge&Load
  
• Charge&Unload
  
• Load
  
• Unload

• {Action}[GridName]ConnectorName
  
• {Action}ConnectorName
  
• ConnectorName
  
• {Action}GPS:Name:...
  
• GPS:Name:...

Only use the GridName to disambiguate from different bases with same ConnectorName.

Use a Semicolon ";" examples:

Start navigation on ShipName1, ShipName2 and ShipName3:

Start looped navigation on ShipName1, ShipName2 and ShipName3. Each one having their own docks.

• Do you own all blocks in the grid? You should.
  
• Does your ship have enough power/hydrogen? It must.
  
• Does your ship have enough Thrust power in every direction? Including UP. It must.
  
• Do your Antennas have enough range to cover each other and are they enabled to broadcast? They should.
  
• Are all your blocks in the same construct? (adjacent to rotors or pistons but not connectors).

Things are still wrong? I suck at coding. Leave a comment with a link to the game file, perhaps I can help.