Quick Start

Setting up an aircraft with NWH Aerodynamics.

Note: Import and examine demo scenes for quickest start. This guide covers manual setup.

Samples can be imported from the Samples tab in the Package Manager under In Project (left sidebar) > NWH Aerodynamics > Samples

Aircraft Model Requirements

Warning: Ensure your aircraft model has Unity-correct rotation and pivot points. The model should use Z - Forward, Y - Up, and X - Right axes. If your model has incorrect rotation and/or pivot points, you may need to adjust it in your 3D software before importing.

Warning: Maintain an aircraft scale of [1,1,1]. Adjust the scale using model import settings in Unity or 3D software prior to setup.

Model Structure: Ideally, your aircraft model should have separated meshes for:

  • Fuselage
  • Wings (left and right)
  • Horizontal stabilizers/tail planes
  • Vertical stabilizer/rudder
  • Control surfaces (ailerons, elevators, rudder, flaps)
  • Landing gear wheels
  • Propellers (if applicable)

Physics Settings

  • Set Fixed Timestep (Edit > Project Settings > Time) to 0.01 (100Hz) or lower. Higher speeds need lower timestep for stable control surfaces.
  • Uses SI units (kg, m, N).

Warning: Large maps (> ~4000 units) require floating origin. See this floating origin guide for implementation details.

Manual Setup

No automatic setup wizard. Follow these steps to create a flyable aircraft.

Step 1: Rigidbody

  1. Add your aircraft model to the scene
  2. Add a Rigidbody component to the aircraft root object
  3. Set the mass to a realistic value (e.g., 1200 for light aircraft like Cessna 172, 5000+ for jets)
  4. Disable Use Gravity temporarily during setup to prevent the aircraft from falling
  5. Add colliders to the aircraft body (use primitive colliders or a simplified mesh collider)

Step 2: AircraftController

  1. Add AircraftController component to the aircraft root (where the Rigidbody is)
  2. The AircraftController will automatically add required child components:
    • AircraftInputManager - handles user input
    • AircraftFuelManager - manages fuel consumption
    • Other optional components can be added via the Components tab

Step 3: Airfoils (Wings and Stabilizers)

Lifting surfaces that generate aerodynamic forces. Typical setup:

  • 2x Wings (left and right)
  • 2x Horizontal stabilizers/tail planes (left and right)
  • 1x Vertical stabilizer/fin

For each wing/stabilizer GameObject:

  1. Add Airfoil component to the wing GameObject
  2. The Airfoil will attempt to auto-fit to your mesh
  3. Verify the airfoil shape matches your wing using the ABCD corner handles (blue-red movement handles)
  4. Check that AirfoilSection orientations are correct:
    • Blue (forward) should point toward incoming air
    • Red (right) should align with the wing span
    • Green (up) should point up from the wing surface
    • If green points down, click the Flip button
  5. Adjust slicing planes (red dashed lines) if needed - more sections = higher accuracy but more cost
  6. Press Slice to generate sections
  7. Assign an AirfoilProfile (default profiles are provided in Resources)

Mirroring: For symmetrical surfaces (left/right wings), set up one side completely, then:

  1. Assign the opposite wing GameObject to Mirroring Target
  2. Press Mirror to copy the setup

Airfoil after slicing, showing sections (green lines).

Step 4: Control Surfaces

Movable airfoils attached to fixed surfaces:

  • Ailerons: Wings, control roll
  • Elevators: Horizontal stabilizers, control pitch
  • Rudder: Vertical stabilizer, controls yaw
  • Flaps: Wings, increase lift/drag for takeoff/landing

For each control surface (example: aileron):

  1. Select the aileron GameObject (separate from the wing mesh)
  2. Add Airfoil component and tick Is Control Surface
  3. The airfoil gizmo will turn red
  4. Add the appropriate control surface component:
    • AileronControlSurface for ailerons
    • ElevatorControlSurface for elevators
    • RudderControlSurface for rudder
    • FlapControlSurface for flaps
  5. Adjust the deflection range (e.g., ±25° for ailerons)
  6. Select the parent wing/stabilizer airfoil
  7. At the bottom of the parent airfoil inspector, add the control surface to the list
  8. Adjust parent airfoil slicing planes to align with control surface edges (use red arrow handles)
  9. Yellow line gizmos indicate paired sections between parent and control surface

Control surface airfoil (red) attached to wing airfoil (blue).

Step 5: Landing Gear

For each landing gear wheel:

  1. Create a WheelCollider following Unity's official WheelCollider guide
  2. Position the WheelCollider at the wheel location
  3. Add LandingGear component to a parent GameObject (or directly on the WheelCollider object)
  4. Assign fields:
    • WheelCollider - the Unity WheelCollider component
    • Wheel - the visual wheel model Transform
    • Position - wheel location (Front, Left, Right, etc.)
    • maxSteerAngle - steering angle for nose wheel (e.g., 45°), 0 for non-steerable wheels
  5. Configure WheelCollider friction:
    • Forward/Sideways Friction > Stiffness: 1.0-2.0 for wheels
    • Adjust spring/damper to suit aircraft weight

Optional rigging and retractable gear: See LandingGear documentation for advanced setup.

Step 6: Propulsion

Aircraft need an engine and a propulsor (propeller or jet) for thrust.

Engine Setup:

  1. Create an empty GameObject under the aircraft (e.g., "Engine")
  2. Add an engine component:
    • PistonEngine - for propeller aircraft (Cessna, Piper, etc.)
    • TurbineEngine - for jets and turboprops
  3. Configure engine parameters:
    • Max Power - maximum power output (e.g., 120000W for Cessna 172)
    • Max RPM - maximum engine RPM (e.g., 2700 for piston engines, 30000+ for turbines)
    • Stall RPM - idle RPM below which engine stalls (e.g., 600)
    • Inertia - higher = slower to spin up (e.g., 0.5 for pistons, 5.0+ for jets)

Propulsor Setup:

  1. Create an empty GameObject for the propulsor (e.g., "Propeller" or "Jet")
  2. Add a propulsor component:
    • PropellerPropulsor - for propeller-driven aircraft
    • JetPropulsor - for jet engines
  3. Configure propulsor:
    • Thrust Point - where thrust is applied (move the GameObject to position this)
    • Thrust Direction - forward direction (usually Z-axis of the GameObject)
    • Inertia - propeller/turbine spinning inertia (e.g., 0.5)
    • For PropellerPropulsor: Set bladeCount, bladeWidth, diameter, airfoilProfile
    • For JetPropulsor: Set maxThrust in Newtons (e.g., 50000N)
  4. Link engine to propulsor:
    • Select the engine component
    • In Propulsion > Propulsors, add the propulsor component

Propulsor thrust point (red sphere) and thrust direction (red line).

Step 7: Center of Mass

Critical for stable flight:

  1. Add VariableCenterOfMass component to aircraft root
  2. Position slightly forward of wing center (10-30% of wing chord)
  3. Typical inertia for light aircraft: [2000, 5000, 7000]
  4. Too far forward = nose-heavy
  5. Too far back = tail-heavy, unstable

Note: For Unity 2023 and newer, you can adjust center of mass directly on the Rigidbody component instead of using VariableCenterOfMass.

Step 8: Input

NWH Aerodynamics uses the AircraftInputManager which is automatically added when you add AircraftController.

Default controls:

  • Pitch: W/S or Arrow Up/Down
  • Roll: A/D or Arrow Left/Right
  • Yaw: Q/E
  • Throttle: Left Shift / Left Ctrl
  • Brakes: B or Space

To customize input:

  1. Select the GameObject with AircraftInputManager
  2. The input manager uses InputSystem
  3. Assign input actions to customize controls

See Input documentation for detailed input setup.

Step 9: Test Flight

  1. Re-enable Use Gravity on the Rigidbody
  2. Position the aircraft on the ground or slightly above it
  3. Press Play
  4. Increase throttle (Left Shift)
  5. Steer with nose wheel (A/D) if on the ground
  6. Pull back on pitch (S) to take off
  7. Control the aircraft with pitch/roll/yaw inputs

If the aircraft doesn't fly:

  • Check that all airfoils are sliced and have AirfoilProfiles assigned
  • Verify control surfaces are attached to parent airfoils
  • Ensure engine is linked to propulsor
  • Check center of mass is not too far back
  • Increase throttle to maximum for testing
  • Verify Fixed Timestep is set to 0.01 or lower

Fine-Tuning

Stability

  • Aircraft pitches up uncontrollably: Center of mass too far back, move it forward
  • Aircraft pitches down: Center of mass too far forward, move it back
  • Aircraft rolls/yaws unexpectedly: Check control surface deflections are not inverted
  • Jittery controls at high speed: Reduce Fixed Timestep to 0.005 (200Hz)

Performance

  • Not enough lift: Increase wing area, add more airfoil sections, or use higher-lift AirfoilProfile
  • Not enough thrust: Increase engine Max Power or propulsor thrust
  • Stalls easily: Ensure wings have sufficient area and appropriate AirfoilProfile (higher lift coefficient)

Control Surfaces

  • Too sensitive: Reduce control surface deflection range (e.g., ±15° instead of ±25°)
  • Not responsive enough: Increase deflection range or increase control surface area

Assembly Definitions

Uses .asmdef files.

  • With assembly definitions: Add reference to NWH.Aerodynamics.AircraftController in your .asmdef
  • Without assembly definitions: Remove all .asmdef files after import

Next Steps

Common Issues

  • Falls through terrain: Check WheelColliders, terrain collider, starting position
  • Control surfaces don't move: Verify components attached, AircraftInputManager present, surfaces added to parent airfoil list, input bindings configured
  • Engine doesn't start: Increase throttle, check engine-propulsor link, verify Stall RPM, try disabling stalling
  • Flips on takeoff: Center of mass too high/far back, landing gear too narrow, excessive engine torque