Skip to content

Fix scroll speed compounding math #21453

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 3 commits into
base: main
Choose a base branch
from
+4 −1
Open

Fix scroll speed compounding math #21453

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
257e017
Fix scroll speed compounding math
alice-i-cecile Oct 8, 2025
19b935c
Deterministic math I guess
alice-i-cecile Oct 8, 2025
4f09e02
Remove unhelpful powf comment
alice-i-cecile Oct 8, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 4 additions & 1 deletion crates/bevy_camera_controller/src/free_cam.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -23,6 +23,7 @@ use bevy_input::mouse::{
};
use bevy_input::ButtonInput;
use bevy_log::info;
use bevy_math::ops::powf;
use bevy_math::{EulerRot, Quat, Vec2, Vec3};
use bevy_time::{Real, Time};
use bevy_transform::prelude::Transform;
Expand Down Expand Up @@ -193,7 +194,9 @@ pub fn run_freecam_controller(
MouseScrollUnit::Pixel => accumulated_mouse_scroll.delta.y / 16.0,
};
scroll += amount;
controller.walk_speed += scroll * controller.scroll_factor * controller.walk_speed;
// By using exponentiation we ensure that this scales up and down smoothly
// regardless of the amount of scrolling processed per frame
controller.walk_speed *= powf(1.0 + controller.scroll_factor, scroll);
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

While this is correct in being invariant under splitting of scroll between frames. I question the meaning of scroll_factor I can't make out a reasonable set of units for it.

If we treat former line 196

controller.walk_speed += scroll * controller.scroll_factor * controller.walk_speed;

As a differential equation (in the limit of infinite FPS), where scroll becomes a speed instead of a fixed amount:

d/dt [controller.walk_speed] = d/dt [scroll] * controller.scroll_factor * controller.walk_speed;

Assuming the scroll velocity to be constant, the integral of this is:

controller.walk_speed = exp(total_scroll * controller.scroll_factor) * INITIAL controller.walk_speed;

So this translates to code as:

controller.walk_speed *= exp(scroll * controller.scroll_factor);

In this case it's obvious that controller.scroll_factor has units of 1/[unit of scrolling], it might be any* number and negative scroll_factors simply invert the effect.
*IEEE754 restrictions apply

In the current code scroll factors less than -1.0 do something very weird and silly (0.0^scroll? -0.5^scroll? I don't know what floats you're getting out of that), and the inverse to scroll_factor is actually 1/(1+scroll_factor) - 1.

Suggested change
controller.walk_speed *= powf(1.0 + controller.scroll_factor, scroll);
controller.walk_speed *= exp(controller.scroll_factor * scroll);

controller.scroll_factor is thus the inverse amount of scroll needed to scale the speed by e, or simply the rate at which scroll affects the speed.

We could also do

Suggested change
controller.walk_speed *= powf(1.0 + controller.scroll_factor, scroll);
controller.walk_speed *= powf(2.0, controller.scroll_factor * scroll);

If a base 2 exponential is more intuitive, somehow. (It just scales the units on scroll_factor)

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

PS:

The two methods are equivalent, in the sense that you can convert:
controller.scroll_factor (in the suggested method)
to
exp(controller.scroll_factor) - 1.0 in the old one, I find that to be a really weird parametrisation though.

Copy link
Contributor

@BigWingBeat BigWingBeat Oct 8, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

scroll_factor is intended to be a percentage change. So with the default value of 0.1, each scroll delta increases or decreases the value by 10%. This is basically the same code I use to control a camera zooming in/out, as it's the same situation with wanting the perceived rate of change to be the same regardless of the size of the value being changed.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What is "a scroll delta" though?
Also I would argue "increases or decreases by 10%" is misleading, you may increase by 10%, but you're decreasing by 9.09...% instead.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm not sure the scroll delta can really be qualified beyond just "the number reported by the hardware". On my mouse at least, it seems to correspond to the "notches" in the scroll wheel.

Regarding the scaling factor, I did actually briefly use the form you are suggesting, but I changed it because reasoning about percentage changes was much more intuitive for me than whatever unit it is in your suggested form (As in, how easy it was to "predict" the relationship between a given value and the perceived magnitude of effect it has on the resulting scroll behaviour).

controller.run_speed = controller.walk_speed * 3.0;

// Handle key input
Expand Down