Overview

The FlightPlatform by H3BO3 is a modular and adaptable flying vehicle system for any VTOL airship.

The Flight Platform heavily utilizes indirectly-bound Dynamic Variables (abbr. dynvars) for modularity and ease of user customization. As part of the base package, it features a controller-agnostic Physical Input System module and a physically-simulated Main Flight Loop module. It has an optional Effects category with an installed Velocity Dynvar module to support velocity-based effects like sounds and engine thrust vectors, as well as simple speed readouts.

The default Main Flight Loop module has a large number of settings to simulate and enable physical antigravity flight, such as two pseudo-aerodynamics algorithms, thrust and drag simulation, speed + angle based roll clamping for visually-consistent hovering, aircraft-style automatic rotation centering when near-level, and arbitrary directional thrust input. The resulting calculations are used to apply force to a CharacterController component on the aircraft root, which provides basic collision and efficient physical simulation.

The default Physical Input System features a two-orientation grab-latching rotation-based joystick that can be used with the desired hand, and the control layout will flip as needed. The attitude indicator and rotation feedback UI follow the head for superior aircraft forward-targeting. All major controls have been consolidated to standard controller inputs. Also featured is a directional force input controller available when the landing gear is down.

Instructions

On the Aircraft kit root, adjust the SingleShapeCharacterControllerManager DefaultHeight to be roughly the height of your intended aircraft model, with landing gear extended (if applicable).
If you have player colliders on your aircraft model, switch the CharacterCollider field to false for now.
Parent the aircraft model under AircraftModel. Remove or disable the Grabbable component on your model, if applicable.
Reset the position and rotation of your now-parented model. Be sure the model is facing forward, along the Z axis of the aircraft kit root.
Continue to move your model around with the devtip until its center of rotation lines up approximately with the position of the aircraft kit root.
Now you need to balance the height - Enter the seat of the aircraft kit. The plane should fall under gravity, let it settle on the ground and then exit. From there, balance the DefaultHeight of the SingleShapeCharacterControllerManager and the Y position of your aircraft model until your landing gear (or whatever part of your aircraft you want) is resting on the ground visually and your aircraft's center of rotation is acceptably close to the aircraft kit's root.
1. Every time you change the DefaultHeight of the SingleShapeCharacterControllerManager you will need to enter the seat again to make the collider rest on the ground at the correct height.
2. You can enter a numerical value into the field on the right of the DefaultHeight slider, if it doesn't have the range you need.
3. Optionally, you can delete the SingleShapeCharacterControllerManager and adjust the CapsuleCollider properties directly, or replace it with whatever primitive collider type you want.
Move the _DriverAnchor slot in the aircraft kit to wherever you want the pilot to sit. Do NOT change its rotation. You can remove or deactivate the default seat visuals under SeatVisual as desired.
For each of your intended player colliders on the ship (if applicable) add a DynamicValueVariableDriver<bool> bound to the DisableForPilot dynvar. Drop the CharacterCollider field into the Target of the dynvar driver.

Notices

DO NOT duplicate or parent more than one module of a particular type at a time into the dynvar space of an aircraft. The default Physical Input System has several dynamic references for ease of code reading that WILL break if this happens, due to all references being synchronized to the same value instead of staying relative to their hierarchy. If you want to replace a module, delete the old one, then install the new one from a non-duplicated source.
A known issue when upgrading modules through the process above is the module not binding automatically into the dynvar space. This can be resolved by duplicating the aircraft and using the new copy, saving + respawning the aircraft, or saving + reloading the world the aircraft is in.
Since all dynvars in the system are indirectly bound, be cautious when working with multiple modules or moving them around. It is recommended to work in an environment with no other indirectly-bound dynvar spaces in the world hierarchy.

Root Variables

EngineStarted [bool] Indicates if the engine is started. If this is false, but there is a pilot in the seat, the aircraft will fall under gravity. This can be used for certain effects, like enabling glowing engines, sounds, and particles. It is heavily used internally to filter values and inputs.

NoPilot [bool] Goes true if no pilot is in the seat. This is useful for certain systems, such as setting the aircraft to grabbable when there is no pilot. The inverse is used for disabling the CharacterController when there is no pilot, so the ship cannot be physically grabbed by its inherent capsule collider.

DisableForPilot [bool] This will be false ONLY for the active pilot. Use this to drive the CharacterCollider states of your primary ship colliders, to avoid the pilot-simulated CharacterController from surfing upwards on them.

Outputs

The system mostly operates on dynvar driving to pass crucial information between modules. All modules can be modified or even replaced, as long as they provide the right outputs for the other module(s) to read from. This is the section you need to read if you want to create or modify the modules.

Input System

The Input System module provides these outputs as driven dynvars:

Roll [float] Signed + Normalized roll value.
-1 = Roll Right (CW) 1 = Roll Left (CCW)

Pitch [float] Signed + Normalized pitch value.
-1 = Pitch Up 1 = Pitch Down

Yaw [float] Signed + Normalized yaw value.
-1 = Yaw Left 1 = Yaw Right

Boost [float] Normalized boost value.
0 = No boost 1 = Full boost

Brake [float] Normalized brake value.
0 = No brake 1 = Full brake

Throttle [float] Normalized throttle value. This is derived from the controller input, and does not apply force directly - It will be multiplied by MaxThrottle.
0 = No throttle 1 = Full throttle

MaxThrottle [float] Normalized maximum throttle value. This is typically derived from a physical throttle control which can be manipulated to change throttle control sensitivity. It will be multiplied by Throttle. Break the drive and set it to 1 if not needed, then the Throttle input will cover the full range of thrust.
0 = No thrust possible 1 = Max thrust possible

Input System Optional Outputs

Present on the default input system.

StrafeRoll [float] (OPTIONAL) This is an internally-handled value on the default input system module to pass rolling rotation from the AuxThrustController submodule to the pack that handles the ship rotation drive. It causes the sideways tilt seen when strafing a hovering VTOL in order to direct its engines to provide sideways thrust, similar to a helicopter.

AuxGlobalForceVector [float3] (OPTIONAL) Signed global-space force vector. This is output by the AuxThrustController submodule to provide arbitrary directional thrust to the ship. Used for strafing, vertical, and reverse thrust. Very useful for precise parking.

Main Flight Loop

Present on the default flight loop.

RollClampingActive [bool] (OPTIONAL) This is an internally-handled, local-to-pilot boolean to indicate when the roll clamping system in the PrimaryFlightLoop is active.

Settings

These settings dynvars are utilized by the indicated default module. All settings should be positive values unless stated otherwise. This is where you learn how to tune your aircraft to best suit its purpose and flight style.

InputSystem_Physical

Core Variables

PrimaryHand [chirality] This indicates which hand the current/last pilot grabbed the rotation controller with. It is used to switch layouts of controls and feedback to opposite sides.

InHoverMode [bool] This variable is utilized closely with the MainFlightLoop and will add additional drag, and make the AuxThrustController controls active. It is also good for landing gear deployment visuals.

Settings

UseHeadOffset [bool] Indicates if the control interfaces should dynamically set themselves to a set offset from the pilot's head, as defined by the local transform of _ControlsRoot > HeadOffsetRef If this is set false, you can move _ControlsRoot > ControlsSelectionPosHolder to your desired location.

RotationControllerDeadzone [float] Degrees. Indicates the start of the degree range the rotation controller must be rotated past before Pitch or Yaw is applied.

RotationControllerMaxAngle [float] Degrees. Indicates the end of the degree range the rotation controller will use for Pitch or Yaw input.

RotationControllerRollDeadzone [float] Degrees. Indicates the start of the degree range the rotation controller must be rotated past before Roll is applied.

RotationControllerRollMaxAngle [float] Degrees. Indicates the end of the degree range the rotation controller will use for Roll input.

ThrottleDeadzone [float] Normalized. Indicates the start of the range the trigger must be pressed to so thrust is engaged.

UIHeadFollow [bool] Indicates if the _FlightUIRoot displays should dynamically position themselves in front of the pilot's line of sight. Recommended to be true since this improves forward-targeting significantly. This uses the local transform of _FlightUIRoot > FlightUIHeadOffsetRef. If the ref is adjusted, it is only recommended to adjust the Z value, otherwise the UI will be off-center. Set this to false if you want to set the transform of _FlightUIRoot > FlightUIHolder manually, such as with a small cockpit or somewhere the HUD is already established.

ExponentialRotationMapping [bool] Indicates if the rotation controller should square the normalized rotation input values after all deadzones are applied. This is recommended to be true so microadjustments to rotation are easier to perform, and large rotations will be executed very quickly when needed.

RotationControllerAngleOffset [floatQ] Degrees. Applies the specified rotation offset to the rotation controller before all deadzones. This will not affect the visual model, but it will affect the internal calculations. Recommended for personal fine tuning, to help the joystick and center position feel more comfortable in your hand. This rotation will currently NOT be mirrored between left or right hands, so it is recommended to only adjust the pitch offset (X value) for now.

AuxThrustController

Present on the AuxThrustController submodule. This module is only active in Hover Mode (Landing Gear Down).

MaxAuxThrust [float] Indicates the maximum thrust magnitude that the AuxThrustController can feed into the MainFlightLoop. This is a direct force input, and the speed and acceleration it applies will be dependent on the various drag influences in the MainFlightLoop.

AuxControlDragRange [float] Indicates the maximum length that the pilot can drag the thrust vectoring control. Higher value = More precision, but a wider sphere, so the control range might be difficult to use practically with space limitations. It is recommended to adjust the visuals to compensate if this value is adjusted.

MainFlightLoop

The MainFlightLoop settings are split into three subcategories.

SimulationInputs

ThrottleMaxForce [float] Indicates the maximum thrust that can be applied when Throttle and MaxThrottle are both at 1.

BoostMaxForce [float] Indicates the maximum thrust that can be applied by the Boost value when at 1. This value is exponentially related with Throttle and MaxThrottle, meaning that the higher the total throttle, the more boost force will be applied.

BaseDrag [float] The base drag of the aircraft. This is the primary limiter of maximum forward speed. There are multiple other drag influences that are summed with this value.

BrakeMaxDrag [float] Indicates the maximum drag that Brake at 1 can apply.

MaxAerodynamicDrag [float] Indicates the maximum drag that facing 90 degrees from your current velocity vector will apply.

RetrogradeAeroDragMultiplier [float] Normalized. Indicates the proportion of MaxAerodynamicDrag that facing 180 degrees from your current velocity vector will apply.

PitchSpeed [float] Degrees per second. How fast the aircraft pitches up and down.

YawSpeed [float] Degrees per second. How fast the aircraft yaws left and right. NOTE: This yaw has a penalty applied to it by default as per OffAxisYawMultiplier in the Penalties settings. This is to support future features such as cockpit gimbaling.

RollSpeed [float] Degrees per second. How fast the aircraft rolls left and right.

AeroLiftSpeedThreshold [float] Meters per second. How fast the aircraft must be going before aerodynamic pitch lift begins to apply.

AeroLiftForceMultiplier [float] For every meter per second of speed above AeroLiftSpeedThreshold, this value is multiplied by that speed and a proportion given by the pitch angle of the aircraft relative to its current velocity vector up to AeroLiftMaxAngle. This simulates wing lift during pitching, both up and down. This is why it is more efficient to roll first, and then turn by pitching. Increase this value to get tighter high-speed turns.

AeroLiftMaxAngle [float] Degrees. Indicates the maximum angle difference between facing and velocity vectors that will be used to apply maximum aerodynamic lift force.

AeroLiftForceMax [float] Clamps the maximum aerodynamic lift force possible. Raise this and AeroLiftForceMultiplier if you have an extremely-high-speed aircraft that needs to turn well.

RotationInputs

RollReturnToCenterThreshold [float] Degrees. If the absolute roll of the aircraft is within this threshold it will slowly rotate back to level based on RollReturnToCenterRate.

RollReturnToCenterRate [float] Degrees per second (Proportionally adjusted for subtlety).

PitchReturnToCenterThreshold [float] Degrees. If the absolute pitch of the aircraft is within this threshold it will slowly rotate back to level based on PitchReturnToCenterRate.

PitchReturnToCenterRate [float] Degrees per second (Proportionally adjusted for subtlety).

RollClampRate [float] Degrees per second (Proportionally adjusted). How fast the aircraft will rotate back within its clamped range when Roll Clamping is active.

ZeroSpeedMaxRoll [float] Degrees. How much the aircraft can roll when at 0 speed. NOTE: This value will always apply when Hover Mode is enabled (Landing gear is down).

MaxRollSpeedThreshold [float] Meters per second. How fast the aircraft must be going before rolling to MaxAbsoluteSpeedRoll is allowed.

MaxRollAtSpeedThreshold [float] Degrees. How much the aircraft can roll at the MaxRollSpeedThreshold. Maximum allowed roll is mapped between ZeroSpeedMaxRoll and MaxRollAtSpeedThreshold based on the aircraft speed and MaxRollSpeedThreshold. Once the threshold is crossed the aircraft can roll to the value defined by MaxAbsoluteSpeedRoll.

MaxAbsoluteSpeedRoll [float] Degrees. Indicates the maximum absolute roll the aircraft can perform once all speed thresholds are crossed. Set to 180 or higher to allow 360 rolling.

FullRollPitchThreshold [float] Degrees. If the aircraft pitch is greater than this threshold and at a speed above MaxRollSpeedThreshold, 360 rolling is allowed, regardless of MaxAbsoluteSpeedRoll. Set to 90 or greater to disable (May lead to unstable rolling behavior).

EngineOffRollReturnToCenterRate [float] Degrees per second. If the engines are turned off, the aircraft will reorient to level at this speed.

EngineOffPitchReturnToCenterRate [float] Degrees per second. If the engines are turned off, the aircraft will reorient to level at this speed.

MaxStrafeRoll [float] Degrees. This is the maximum tilt the aircraft will go to while strafing if using the AuxThrustController sideways.

Penalties

OffAxisYawMultiplier [float] Normalized. If the aircraft is not tilted towards the yaw vector, this penalty will be applied to straight yaw. This penalty is currently always applied since there is no separation of cockpit and aircraft, and since turning aircraft is done with a combination of roll, pitch, and yaw, it is realistic. This setting will be more useful once a flight loop that supports cockpit gimbaling is added.

HoverModeDragAdd [float] The amount of drag added when Hover Mode is enabled (Landing gear is down).