BlyxDocumentation
Browse chapters
Documentation / Framework projects

Kestrel · Replay a bouncing ball across a stalled frame

Run a bounded number of simulation ticks per rendered frame, carry fractional frame time and interpolate a moving object between updates.

The developer problem

Rendering at a changing frame rate can change simulation speed. A long pause can also produce a burst of catch-up work. Godot’s physics interpolation guide explains the separate clocks. Kestrel makes the carry, interpolation fraction and discarded time visible to the application.

Run the project locally

Feed the same five frame times into a fixed-step ball simulation. One 100 ms stall exceeds the catch-up limit. The replay reports positions and the number of milliseconds discarded. Install Blyx 0.2.1, Rust and a host linker, then run these commands.

git clone --depth 1 --branch v0.1.0 https://github.com/Rahulchaube1/blyx-kestrel.git
cd blyx-kestrel
blyxc native-run project.blyx

Use the API

Use whole milliseconds from 0 to 1,000,000,000, a positive step and a remainder smaller than that step. max_steps is 1–1,000,000. The clock returns an empty vector for invalid input. A frame cap discards whole ticks only. The simulation takes frame durations from the caller so a replay needs no wall clock.

FunctionBehavior
ke_clock(carry, elapsed, step, max_steps)Return [updates, remainder_ms, discarded_ms, interpolation_fraction]. Feed remainder_ms into the next frame.
ke_lerp(previous, current, fraction)Interpolate a render position between the last two simulated positions.
ke_bounce(position, velocity, dt, low, high)Advance one object on a bounded 1D track. The result holds position and velocity, including repeated wall crossings.

Verify a change

Run the package checks from its release directory. Compare the browser example with its expected output, then change the input in the exercise below.

blyxc native-run tests.blyx

Try the program

Output Ready
Expected output
3
5
20
0.5
Open in the full playground →

Practice

Increase the catch-up limit from three ticks to five. What happens to the carry?

Hint

Change only the worked example’s input. The API table describes the output.

Worked solution

All five whole ticks run; the remaining five milliseconds still set the render fraction to 0.5.

Find

50.0, 10.0, 3

Replace with

50.0, 10.0, 5

Output after the change

5
5
0
0.5