search

m4v / RCSBuildAid

Kerbal Space Program plugin for RCS thruster placement
GNU Lesser General Public License v3.0
34 stars 25 forks source link

readme

= RCS Build Aid Plugin: Documentation Elián Hanisch lambdae2@gmail.com v1.0.4, December 2020: :imagesdir: doc

This is a plugin for https://www.kerbalspaceprogram.com[Kerbal Space Program] and is an aid tool for balancing RCS thrusters around the center of mass while building a rocket, and a bit more.

image::intro.jpg[width="600",align="center"]

== Requirements

=== Supported mods

== Features

== Installation

=== Files

The files that you should have after installing RCS Build Aid in GameData/RCSBuildAid are:

== User interface

This section explains all the readouts and overlays of the plugin, if you don't have time for that you can skip to <> for some use cases.

=== Activating the plugin

This plugin can only be used while in VAB (Vehicular Assembly Building) or in SPH (Space Plane Hangar). RCS Build Aid is enabled by clicking in the application launcher button image:button.jpg[20,20] at the bottom of the screen. Once enabled, you should see its main window. You can also enable it by pressing the key 5, see <> if you want to change the keyboard shortcut.

NOTE: If you have blizzy78's toolbar installed, then you can disable the application launcher button or blizzy78's toolbar from the <> menu.

=== Editor overlays

image::overlays.jpg[width="300",role="right"]

The editor overlays are the markers and arrows over you vessel. With them you can see the effects of forces on your vessel and balance it at glance without needing to look at the numbers.

==== Forces

Forces are displayed as arrows, there are several types:

Part forces:: Forces or thrust exerted by parts, they are colored cyan for RCS and yellow for engines. They point towards the exhaust's direction so technically these arrows are the inverse of the actual force.

Thrust or translation force:: Colored in green, represents the translation motion of your vessel, essentially the total thrust applied to the vessel. A small green triangle near the tip of the arrow indicates where it should be pointing ideally.

Torque force:: Colored in red, represents the resulting torque the thrusters are exerting into the vessel. Like in the translation force, a small red triangle would be indicating the ideal direction.

Angular acceleration:: The angular acceleration is represented by a red circular arrow, its purpose is to indicate how fast a vessel will rotate under the effect of current torque. If there's torque but the circular arrow is small or not visible it means that the vessel is massive enough for not be significantly affected.

Drag force:: Colored in cyan, only seen in parachute mode. Shows the drag force of the vessel falling vertically at terminal velocity.

==== Markers

CoM:: The Center of Mass marker, colored yellow. This is the same as the stock CoM.

DCoM:: The Dry Center of Mass marker, colored red, indicates the center of mass for your vessel without resources. Which resources to remove when the vessel is "dry" can be configured from the <>.

ACoM:: This is the Average Center of Mass marker, colored orange, shows the middle point between the CoM and DCoM. Is enabled from the <>.

Both translation and torque forces are referenced to one of these markers, you select which one from the main window. Checking how forces change depending of where your CoM is will help you to understand how to balance best your vessel. For example, for a vessel that docks with almost no fuel it would be best to balance RCS around the DCoM and ignore the CoM marker. If you want your vessel to be balanced in most situations you need to build your vessel in a way that keeps both CoM and DCoM as close as possible, or if you can't achieve this, balancing around the ACoM marker would be the best compromise.

[[CoD]] CoD:: The Center of Drag, only enabled while in <> mode. Don't confuse this marker with stock's Center of Pressure (CoP).

=== Main window

image::main_window.jpg[role="right"]

RCS Build Aid's window have several sections showing some information and options.

==== Mode section

The topmost part of the main window is the mode section. Allows switching modes and shows information relevant to the active mode, see <>.

==== Vessel mass

Shows some information regarding the mass of the vessel.

Wet Mass:: Total mass of the fully fueled vessel.

Dry Mass/Fuel Mass:: Mass of the vessel without fuel or the mass of the fuel, click in label to toggle. They both depend of the resource settings, see below.

==== Resource settings

Shows a list of resources currently in your vessel, displaying the total mass or the total amount of each (click in the Mass label to change the reading).

The DCoM position and the vessel's dry mass is calculated based on the selected resources here, disabled resources will be seen as "dry" and enabled ones will be seen as full. For example, in the image above the DCoM marker will be at the center of mass of the vessel when the Oxidizer and LiquidFuel tanks are empty but MonoPropellant tanks are full.

NOTE: Fuel from tanks where the fuel flow is blocked won't be removed from the DCoM.

==== Marker settings

Options to show, hide or change the size of the CoM markers. See <> for a description of each.

==== Collapsing the main window

If the main window is bothering but you need RCS Build Aid to be active you can collapse it by clicking the small button at the end of title bar, right of the s settings button.

Alternatively, any sections can be collapsed by clicking in their title button.

==== Settings

image::settings.jpg[role="right"]

You can open the settings menu from the small s button in the title bar of RCS Build Aid window.

Use application launcher:: Disable/Enable RCS Build Aid's button in the application launcher. If blizzy's toolbar isn't installed this option is not possible to disable and is greyed out.

Use blizzy's toolbar:: Disable/Enable RCS Build Aid's button in blizzy's toolbar. If blizzy's toolbar isn't installed this option is greyed out.

Show in Actions Screen:: Don't hide RCS Build Aid when switching to the action groups screen in the editor.

Show in Crew Screen:: Don't hide RCS Build Aid when switching to the crew screen in the editor. Mostly to see the effects of mass changes when adding kerbals to the vessel.

Show in Cargo Screen:: Don't hide RCS Build Aid when switching to the cargo screen in the editor. Mostly to see the effects of mass changes when adding cargo.

Marker autoscaling:: The CoM markers will change size depending of the camera distance (if you get the camera closer to your vessel the markers will shrink).

Massless resources:: If enabled show massless resources like ElectricCharge in the <>. Has no use other than for seeing total amounts.

RCS TWR readout:: If enabled will show the TWR (Thrust to Weight Ratio) of RCS.

DCoM offset readout:: If enabled will show the distance between CoM and DCoM markers in the mass section.

GUI scale:: This setting is for increasing the size of the GUI, for high resolution monitors.

Shortcut:: Enable RCS Build Aid with a keyboard shortcut, key 5 by default. You might assign any key but no key combinations. Pressing ESC disables it.

=== Modes

The topmost button in the main window is for select the working mode, each having a different purpose. Currently the modes available are:

==== Translation

For balancing translation movement.

image::translation_mode.jpg[align="center"]

This mode will activate RCS and show how they will fire for a given direction of motion. The green arrow will show the resulting thrust, thus the actual motion and any imbalances will be reflected in the torque.

Reference:: Active center of mass of the vessel, clicking the button will cycle between the active markers.

Direction:: Current movement direction, click to change or use the <>.

Torque:: Total torque magnitude.

Thrust:: Total thrust magnitude.

ΔV:: Available delta velocity from RCS at current direction.

NOTE: The ΔV readout has some issues and will not show for all RCS, see <>.

Burn time:: Time RCS will last until running out of fuel at current direction.

NOTE: The burn time readout has the same issues of the ΔV readout, see <>.

Body:: If the TWR readout is enabled, this will show the selected celestial body for TWR calculations, click to change.

TWR:: Thrust to weight ratio, this depends of the selected celestial body and is always calculated for gravity at sea level. This readout needs to be enabled from the <> menu.

NOTE: Because RCS thrust is always calculated at vacuum this readout is just for atmosphereless bodies.

==== Attitude

For balancing rotation movement.

image::attitude_mode.jpg[align="center"]

This mode will activate RCS and show how they will fire for a given rotation. The red arrow will show the resulting torque and any imbalances will be reflected in the thrust force. This is with RCS only, as if reaction wheels were disabled.

Reference:: Active center of mass of the vessel, clicking the button will cycle between the active markers.

Rotation:: Current rotation, click to change or use the <>.

Torque:: Total torque magnitude.

Thrust:: Total thrust magnitude.

==== Engines

For balancing engine's thrust.

image::engines_mode.jpg[align="center"]

This mode will activate the rocket engines of the bottommost stage, showing the resultant thrust and imbalances as torque. This mode also has a <> section.

NOTE: Only the engines of the bottommost or first stage will activate, if you need to see the engines of an upper stage then you can temporally detach the stages below.

Reference:: Active center of mass of the vessel, clicking the button will cycle between the active markers.

Torque:: Total torque magnitude.

Thrust:: Total thrust magnitude, there's a label Vac/ASL to toggle between thrust at vacuum or at sea level of the selected celestial body.

Body:: The selected celestial body for TWR calculations, click to change.

TWR:: Thrust to weight ratio, this depends of the selected celestial body and is always calculated for gravity at sea level.

===== Gimbals

The gimbals section allows checking the attitude authority of rockets with gimbals and RCS if wanted. Using the attitude <> will activate it automatically and closing this section will reset gimbals.

Rotation:: Current rotation, click to change or use the <>.

Include RCS:: If checked RCS will be enabled for rotation.

==== Parachutes

For balancing parachutes an achieving that perfectly level and slow descent.

image::parachutes_mode.jpg[align="center"]

This mode activates the center of drag (CoD) marker and the drag force. It assumes that the vessel is falling vertically at the current attitude and imbalances will be seen as torque.

Reference:: Active center of mass of the vessel, clicking the button will cycle between the active markers.

Vt:: Terminal velocity of the vessel for the selected celestial body at the selected touchdown altitude.

Body:: The selected celestial body for Vt calculations, click to change.

Touchdown:: Expected touchdown altitude, clicking in the number will enable a selection slider. This setting allows to change the altitude for terminal velocity calculations, ideally you want to set this at the altitude you expect to hit the ground.

=== Keyboard shortcuts

You can change the active direction or rotation by using the buttons in the main window, or alternatively with the same keys used in game for translating your vessel.

The default keybindings in KSP are the hnjkli keys:

[cols="1s,6d,6d"] |=== |Key |Direction |Rotation

|H |Set direction to moving forward |Set rotation to roll left

|N |Set direction to moving backward |Set rotation to roll right

|L |Set direction to moving right |Set rotation to yaw right

|J |Set direction to moving left |Set rotation to yaw left

|I |Set direction to moving down |Set rotation to pitch down

|K |Set direction to moving up |Set rotation to pitch up |===

NOTE: Using the keys when no mode is enabled will automatically enable translation or the last used mode. Setting the same direction twice disables current mode.

== Applications

=== Balancing RCS

The main purpose of this plugin. Having balanced RCS means that when you're translating your vessel won't rotate and when you are rotating it won't translate, this is important for easy docking. This depends of the position of your CoM and the placement of your RCS thrusters. There are two main modes for balancing RCS, <> and <> modes.

Lets see for example the stock Two-Stage Lander:

image::rcs_01.jpg[align="center"]

This lander can ascend to orbit from most atmosphereless bodies (except for Tylo) and is meant to dock to a return stage in orbit... but doesn't have any RCS so it'll be difficult to dock, lets fix that. Since the first stage is meant to be left behind we put them aside so we can work with upper stage that will be the one docking.

image::rcs_02.jpg[align="center"]

Lets use 4 quad RCS at the top and 4 single RCS near the bottom, since we don't know how much fuel there will be at the time of docking we'll balance around the ACoM which is a good compromise. We'll adjust the RCS position until the torque is minimized (the move tool is good for this). Notice that we can't completely cancel the torque out, this is because the two antennas at the top, their position and mass differences put the vessel's CoM slightly off of the longitudinal axis so this vessel won't be possible to balance perfectly without rethinking the antennas position or using counterweights. We won't do that though, never let perfection get in the way of good enough.

image::rcs_03.jpg[align="center"]

We can check the balance in other directions and verify that's good enough.

image::rcs_04.jpg[align="center"]

Lets switch to attitude mode and check the attitude balance, there's some translation but not much. Since there's more than enough reaction wheels the best thing to do would be to enable advanced tweakables and disable RCS's actuation for pitch, yaw and roll. That way we won't have to worry about balancing RCS for attitude change.

image::rcs_05.jpg[align="center"]

Put back the first stage and done, ready to dock.

=== RCS TWR

If you need to know if your RCSs are enough to lift your vessel against gravity there's a RCS TWR readout (needs to enabled from <>).

image::rcs_twr.jpg[align="center"]

This rover can jump even in Tylo.

=== Engines' thrust

Engines mode lets you check the engines' thrust and its effects, useful for making VTOLs and making sure engines are centered with respect of the CoM in spaceplanes.

For example in stock's Aeris 4A:

image::engines_01.jpg[align="center"]

The air breathing engines look fine, remember tha only the engines ahead in the stage sequence become active. If you need to check the engines of other stage you can temporally move the stage below like in the image below.

image::engines_02.jpg[align="center"]

=== Airplane stability

For an airplane to be stable its CoM needs to be slightly ahead of the center of pressure (CoP), but the CoM can move as you burn fuel and the plane can become unstable. For avoid this you can verify that both the CoM and DCoM are ahead of the CoP, like in the image below.

image::plane_stability.jpg[align="center"]

=== Markers size

When working with small crafts the stock CoM marker can be too big, RCS Build Aid will scale it if you "zoom in" with the camera or adjust it manually.

image::marker_size.jpg[align="center"]

=== Parachutes

Placing parachutes isn't a problem most of the time, however for crafts that aren't symmetrical along the axis of descent it can be tricky to get the craft land in the correct direction. Also you will want to have enough parachutes so the touchdown speed isn't too high, and is hard to known before hand how many in bodies with low density atmospheres like Duna.

If for example, you want to add parachutes to a spaceplane as a safety precaution,

image::chutes_01.jpg[align="center"]

here with 2 parachutes the plane with reach "sea level" nose first at approximately 15 m/s. If we want to touchdown with our gear and at 10 m/s we can add 4 more and balance them around the CoM (or the ACoM if you want), like this:

image::chutes_02.jpg[align="center"]

You can select other celestial body or the touchdown altitude, like if you're expecting to land in the mountains of Eve.

By using this tool you should be able to soft land with parachutes every time everywhere.

image::chutes_03.jpg[align="center"]

Most of the time. The author is not liable for any damages.

== Incompatible plugins

This plugin will work only with parts using stock modules, such as ModuleRCS or ModuleEngine. Modded parts that use other modules will not be detected by RCS Build Aid.

== Known issues

== Compiling

=== Make

This plugin is developed in a Linux environment, so it uses make for compiling. Before running make, you need to create an environment variable pointing to your KSP installation:

export KSPDIR=/home/user/KSP make

=== Libraries

While not necessary for compiling, when using an IDE (MonoDevelop, Rider, etc) the project files picks its references for a local directory to avoid commiting the absolute path of library files into the repository. So if you want this project to find its references without changing any project files you have create a local directory named Libraries and copy (or symlink)the directory Managed from a KSP install and Toolbar.dll from blizzy78's toolbar mod (if you wish to compile RCSBuildAidToolbar.dll).

Libraries\ Managed -> ${KSP_DIR}/KSP_Data/Managed Toolbar.dll -> ${KSP_DIR}/GameData/000_Toolbar/Toolbar.dll

== Reporting Bugs

You can report bugs or issues directly to https://github.com/m4v/RCSBuildAid/issues[GitHub].

== Links

== License

This plugin is distributed under the terms of the LGPLv3.

This program is free software: you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.

You should have received a copy of the GNU Lesser General Public License along with this program. If not, see http://www.gnu.org/licenses/.