Off-rails craft gains orbital energy in proportion to the physics step (sim speed x frame time): IntegrateVelocityVerlet takes gravity one step behind

Maxi

Member
Messages
214
Reaction score
166
(Bug found by me, analyzed by claude, post written by claude, verified by me)

Game Version
v2026.11.16.5901, only Core loaded. First seen on v2026.11.10.5801; the code involved is the same in both builds.

Operating System
Windows 10 Pro. Hardware does not matter: the error is in the simulation code and shows the same way in a headless run.

What Happened
A craft that is off rails gains orbital energy all the time, also when it only coasts. The gain points prograde and grows linearly with the physics step, so it is 4x larger at 4x sim speed, and larger at a low frame rate. In a circular orbit:
Code
dv/dt = dt * (mu / r^3) * v      (about 0.18 mm/s per second at dt = 1/60 s, 207 km Earth orbit)
per orbit: dv = 2 * pi * g * dt   (0.96 m/s per orbit at dt = 1/60 s)
Measured on 5901, stock craft in a circular 207 km orbit, coasting, held off rails with the stock "Force Off Rails" flag:
  • 60 s at dt = 1/60 s (1x): +0.01090 m/s
  • 60 s at dt = 2/60 s (2x): +0.02180 m/s
  • 60 s at dt = 4/60 s (4x): +0.04359 m/s
  • one orbit at dt = 10/60 s (10x): semi-major axis +16.26 km, apoapsis and periapsis both about 16 km higher
With the engine burning the part of the velocity change that is neither thrust nor two-body gravity is again exactly this lag. So every burn ends with a little more speed than it added, and every craft that stays off rails (Force Off Rails, a moving part, a commanded engine or thruster) slowly raises its orbit, faster at higher sim speed.

What Was Expected
A coasting craft keeps its orbital energy on and off rails at any sim speed, and a burn changes the orbit by the delta-v the engine gave, independent of sim speed and frame rate.

Reproduction Steps
  1. New game, default craft in its 207 km Earth orbit. The mods console command shows only Core.
  2. Console: physics (or View > Debug > Show Physics Debug), tick "Force Off Rails".
  3. Note apoapsis and periapsis.
  4. simspeed 10 and let one orbit pass (about 9 minutes real time).
  5. Apoapsis and periapsis are both about 16 km higher (at 60 fps). At 1x one orbit gains about 1.6 km.
  6. Untick "Force Off Rails": the orbit stays constant again.
Reproduction Rate
Always, to all printed digits.

Additional Info
Measured in a headless run with only Core and a small read-only plug-in that sets PhysicsBubble._forceOffRails and steps the normal solver (no patch on the physics path). Per frame it takes the velocity change from GetStatesCci minus thrust delta-v minus the two-body gravity trapezoid; that residual equals the sum of -dt^2 * dg/dt (0.01090, 0.02180, 0.04358 m/s against 0.01090, 0.02180, 0.04360 m/s expected, cosine 1.0000). With the fix below and nothing else changed: energy gain 0.00000 m/s, and the 10x orbit keeps its semi-major axis to 0.1 m. A model outside the game with the same statement order gives the same numbers, and zero with the fix.

Technical analysis (decompiled 5901)
PhysicsStates.IntegrateVelocityVerlet, translational part (abbreviated):
Code
disturbances[0] = ComputeDerivatives(..., Origin.PositionBub, Origin.VelocityBub, ...);          // a0
Kinematic.PositionPhys += dt * (Kinematic.VelocityPhys + 0.5 * dt * a0);
Kinematic.VelocityPhys += dt * a0;
RecomputePositionalEnvironmentValues();   // Origin is still the origin of the step START
disturbances[1] = ComputeDerivatives(..., nextOrigin.PositionBub, nextOrigin.VelocityBub, ...);  // a1
Kinematic.VelocityPhys += 0.5 * dt * (a1 - a0);
  • RecomputePositionalEnvironmentValues computes Environment.GravitationBub at Origin.PositionBub + the new relative position. Origin has not moved yet, so the point lags the craft by v * dt (about 130 m at 1x, 520 m at 4x).
  • In a CCI bubble ComputeDerivatives uses that value for the craft and subtracts the origin gravity at the correct nextOrigin.PositionBub, so a1 has the craft gravity of one step earlier.
  • VehicleUpdateState.UpdateToPropagatedOrigin then sets Origin = nextOrigin without recomputing the environment, so the next a0 lags too.
  • Each step adds about -dt^2 * dg/dt, in a circular orbit +dt^2 * (mu / r^3) * v along the velocity: the measured size and direction.
PhysicsStates.IntegrateRk8 does not have this error: it sets the propagated origin before RecomputePositionalEnvironmentValues (Origin = nextOrigin; RecomputePositionalEnvironmentValues(); Origin = origin;).

The step: Universe.GetJobSimStep gives frame time x sim speed; PhysicsBubble.FullPhysicsStepUntil splits it only at a flight computer wake (at most 10 Hz, only on request), a kFS tick or the ComputeTimestep cap; SelectIntegrationMethod uses Verlet up to 2 s. So the Verlet step is 1/60 s at 1x, 1/15 s at 4x (60 fps), and up to 2 s at high warp (about 97 m/s per low Earth orbit at 100x).

Suggested fix
In IntegrateVelocityVerlet, compute the environment after the position update with the origin of the step end, as IntegrateRk8 does:
Code
BubbleOrigin startOrigin = Origin;
Origin = nextOrigin;
RecomputePositionalEnvironmentValues();
Origin = startOrigin;
disturbances[1] = ComputeDerivatives(..., nextOrigin.PositionBub, nextOrigin.VelocityBub, ...);
The step-end environment is also the next a0, so both halves are right. This is the change tested above.

Impact on burns (measured on 5801)
A 3128.2 m/s trans-lunar injection from the default 207 km orbit, flown by stock AUTO, ended with DeltaVAccumCci equal to the target within 0.001 m/s, but the flown orbit had more energy than planned. The lag part summed over the burn was +0.035 m/s at 1x and +0.150 m/s at 4x (expected from -dt^2 * dg/dt: 0.038 and 0.151 m/s, cosine 0.991 and 0.999). At about 2300 km of Luna periapsis per m/s, the planned 99.3 km periapsis came out at -15 to -74 km at 1x and -269 to -297 km at 4x in four runs, so a transfer planned to pass Luna at 100 km impacts.

Related threads
Same symptom, closed by fixing the trigger that kept the craft off rails; the integrator error itself is still in 5901:
 
Upvote 1
Back
Top