Project interpolation: movement, hierarchy and teleporting
Integrate an existing game and check indirect motion, animation and history resets.
Integrate one branch at a time
First ensure physics motion is correct without smoothing. Enable the global setting, retain normal tick frequency and test one branch. Inherit takes its parent's mode; On and Off choose locally. Disabling the global system makes it inactive even with local On.
Move physics transforms and their moving parents in _PhysicsProcess. Include indirect writers: AnimationPlayer/AnimationMixer, Tween, transform tracks, camera scripts and ordinary parents can move an object whose own script does not. Select an appropriate physics processing mode for physics animation/Tween. This does not require moving network requests, UI and every game function into a physics callback.
Teleporting and instantiation
Teleport in this order: assign the final position/orientation, then call ResetPhysicsInterpolation. Resetting first retains history at the old location. After adding an instance to the tree, assign its final transform and reset the intended branch. Outside an active tree or with the system disabled, a reset is not a deferred promise to initialize future interpolation.
For CharacterBody, clear required velocities and refresh contacts through new movement. For RigidBody, use _IntegrateForces as in the reset example. ResetPhysicsInterpolation does not clear Velocity, timers or network buffers. Reset propagates a notification through descendants; independently managed resources follow their own rules.
Working teleports appear in InterpolationDemo2D, InterpolationDemo3D and both character controllers. RequestWarp applies its coordinate in the physics callback, not immediately in input handling.
Frequency and diagnostics
Temporarily lower frequency to 10–15 ticks/s to expose stepping and trails from incorrect teleporting. Restore working frequency and target FPS afterward. Low physics frequency changes contact quality; smoothing cannot recover missed checks. Record physics position and screen output separately, rather than expecting GlobalPosition to change every rendered frame.
| Symptom | Check |
|---|---|
| Remaining jitter | FPS versus ticks, global setting, branch mode, transform writes outside physics |
| Visible travel after teleport | Transform → ResetPhysicsInterpolation order, intended branch and completed tree insertion |
| Camera jitters despite smooth objects | Physical versus interpolated transform reads and accidental double smoothing |
| Off child still follows smooth parent motion | Off does not cancel inherited parent movement; inspect hierarchy/branch separation |
| Smooth image, wrong collisions | Fix frequency, filters, shapes and movement algorithm separately |
Enabled debug/settings/physics_interpolation/enable_warnings helps find unsuitable movement timing, but no warning does not prove the whole game correct. Also test pause, level changes, respawning, reparenting and multiple physics ticks per rendered frame.