Starship troubleshooting

The ship ignores my controls in space

Cause: the ship is Floating. A ship that begins in space (spawned or parked there) has its engines cold, and input is ignored until the engines are online.

Fix: hold climb up. This runs the engine-start sequence (the door closes, On Takeoff Started fires and the engines spool, with no ascent) and the ship enters SpaceFlight. AreEnginesOnline() tells you whether the engines are online.

The ship stops descending and won’t land

Cause: while Hovering, the ship won’t descend below the hover floor, MinHoverElevation (1000 by default), on its own. Landing is a separate hold-to-commit sequence.

Fix: at the hover floor, keep holding descend. After LandHoldTime (1 s by default) the ship commits to the landing.

The ship won’t tilt, bank or turn toward where I look

Cause: the ship is Hovering. Below FlyingElevation (5000 by default) it stays level with no tilt or roll, and moves relative to the camera.

Fix: climb to FlyingElevation. In Flying the ship turns to fly where you look, with full tilt and bank. If you want that behaviour lower down, lower FlyingElevation.

The ship hovers with the gear up and the door open instead of landing

Cause: this is the Anchored state, and it is by design. When you land over water deeper than MinLandableWaterDepth (300 by default) or ground steeper than MaxLandingSlopeDeg (20 by default), the ship holds AnchorElevation over the surface instead of tipping over or sinking.

Fix: land on flatter ground or shallower water, or adjust MinLandableWaterDepth and MaxLandingSlopeDeg for your world. To leave an anchor, take off with climb up, the same as from Landed.

The ship keeps drifting after I let go of thrust

Cause: flight assist is off. With bStabilize off, flight is raw Newtonian: thrust is an impulse, velocity drifts, and turning does not redirect it.

Fix: turn bStabilize back on (the default). Thrust in Flying and SpaceFlight then works as a throttle-cruise: release to hold the current speed.

The ship slows down on its own

Cause: the approach auto-brake is shedding speed. With bApproachAutoBrake on, the ship slows for gravity fields ahead while in SpaceFlight, and eases down to hover speed before terrain while Flying. Positive throttle is ignored only while it is actively shedding speed.

Fix: this is expected, and manual braking still works while it happens. IsApproachBraking() and the On Approach Braking Changed event, both on the ship’s ShipMovement component, tell you when it is active, for example for a HUD light. ObstacleBraking sets how hard the collision brake decelerates while Flying. To turn the auto-brake off, turn off bApproachAutoBrake.

The ship slams into gravity at cruise speed

Cause: the approach auto-brake is off. Without it, nothing probes ahead for gravity fields during SpaceFlight.

Fix: turn bApproachAutoBrake back on (the default). The ship then probes ahead down its nose and arrives at MaxFlightSpeed. GravityEntryBraking sets the retro deceleration that bleeds off overspeed on gravity entry.

The engines don’t swivel

Cause: MaxPitchDeflection and MaxYawDeflection default to 0, which locks the engine. Thrust vectoring also needs bAlignToFlightIntent on.

Fix: on the engine component, keep bAlignToFlightIntent on and raise MaxPitchDeflection and/or MaxYawDeflection. Tune AlignSpeed and AlignSmoothingTime for how quickly the nozzle follows.

An engine never lights, or only burns in some flight states

Check these on the UStarshipEngineComponent:

• ActiveInStates lists the flight states the engine burns in. If it lists only some states, the engine stays off in the others. Leave it empty to burn in all states.
• bAutoPowerFromShip: with it off, the engine only changes power when you call SetPower yourself.
• The ship’s power demand is off while the ship is parked, so a self-driven engine is off too.

If the flame length doesn’t change with throttle, turn on bScaleFlamesWithPower.

The landing gear doesn’t deploy

Cause: the strut isn’t following the ship. It only follows automatically when bFollowShipGear is on and the component is on a Starship pawn.

Fix: turn on bFollowShipGear (the default) on each UStarshipLandingGearComponent on your ship Blueprint. On any other actor, or with follow off, call SetDeployed yourself.

The landing gear looks wrong

• Legs are all the same length on uneven ground: turn on bTraceForFloor (the default), so each strut line-traces its own floor.
• The gear moves out of step with the landing: set DeployDuration to match your LandingDuration (both 1.5 s by default).
• Parts are misplaced: the sleeve and foot meshes need to be upright, with height along Z. Any pivot works. The sleeve is scaled to fill SleeveDimensions, and MaxFootTravel limits how far the foot can travel down.

Things pass through the landing gear

Cause: the gear has no collision, by design. It is the look only; landing contact comes from the ship’s own ground detection.

Fix: landing contact uses a box sweep along gravity. LandDetectBounds sets its half-extent (150, 150, 50 by default), so size it to your hull’s footprint.

No prompt appears when I walk up to the ship

• The prompt appears when an on-foot player character overlaps the ship’s InteractionVolume. The volume is movable, so check that it sits where your character can reach it.
• If Auto Possess Player is set, you are already flying the ship. Leave it Disabled for the on-foot board flow.
• The prompt is raised through the Show Prompt and Clear Prompt events. BP_Starship has the included prompt widget set up.

The door stays shut in space

Cause: the landing sequence never opens the door off the ground.

Fix: stand a character in the DoorInteractionVolume at the door while the ship is in space with the door shut, and use the “Open Door” prompt. Or call SetMainDoorOpen on the server.

Passengers can’t board or leave

• Can’t board: passengers board a piloted ship, and only while a seat is free. Check HasFreeSeat() and raise MaxPassengers (4 by default) if you need more seats. BoardPassenger and UnboardPassenger run on the server.
• Can’t leave in flight: bPassengerExitRequiresLanded (on by default) keeps passengers aboard until the ship lands. Turn it off to allow mid-flight disembarking.

Other players’ ships snap between positions

Cause: ProxySmoothingSpeed is 0, which snaps to each replicated transform.

Fix: set ProxySmoothingSpeed above 0 (12 by default). Machines that are not simulating the ship then chase the replicated transform smoothly, which also keeps attached riders’ cameras steady.

The pilot HUD doesn’t appear on a client

Cause: the engine’s Possessed event only fires on the server, so a HUD added there never appears for a client who is piloting.

Fix: add the HUD in On Local Pilot Begin and remove it in On Local Pilot End. For passengers, use On Local Passenger Begin/End. These fire on the owning machine.

The ship ignores my planet’s directional gravity

Cause: by default Starship reads the engine’s world gravity. Directional gravity only comes from an external gravity subsystem, which FGravityCoreAdapter looks up by reflection when the gravity source is resolved, once, at BeginPlay. If the subsystem is absent or cannot be reflected, the ship falls back to world gravity.

Fix: check that the external gravity subsystem is present in your project. The ship resolves its gravity source once, at BeginPlay.

Still stuck?

Ask on the CodeLikeMe Discord. Include your Starship version, your Unreal Engine version and, if you can, a screenshot of the problem.