Skip to content

A fast 2D and 3D game engine — TypeScript SDK, C++/WebAssembly core, visual editor. Ship one project to web, desktop, WeChat MiniGames, playable ads, and native Android / iOS.

fix(ui): integrate inertial scroll distance across frame rates

yhhe0d2d03b454f
diff --git a/CHANGELOG.md b/CHANGELOG.md
index acc5540e1..f1d78344b 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -16,6 +16,8 @@ published separately; it ships inside the editor.
### Fixed
+- **Inertial scrolling travels consistently across frame rates.** Coast displacement integrates the exponentially decaying velocity instead of using its initial value for the whole frame. Frames that cross the stopping threshold integrate only the remaining motion, so a slow frame no longer extends a fling. Constant-speed and immediate-stop settings remain finite.
+
- **WASM video progress reaches the decoded endpoint.** Playback ending after a seek or a large update no longer leaves the clock at its previous position. The decoder derives the final duration from the last frame, and the SDK refreshes it before notifying end-of-playback listeners. Looping and seeking back to the beginning retain their normal clocks.
- **Single-timestamp MPEG videos report duration and support seeking.** Videos whose frames fit in one PES packet no longer report a zero duration or seek only to the first frame. The decoder counts picture headers without decoding frames at startup and uses frame-based seeking when packet timestamps cannot describe the timeline. Timestamp-based seeking remains in use for other streams.
diff --git a/sdk/src/ui/collection/kinetic-scroll.ts b/sdk/src/ui/collection/kinetic-scroll.ts
index b488bf4ef..a4859351e 100644
--- a/sdk/src/ui/collection/kinetic-scroll.ts
+++ b/sdk/src/ui/collection/kinetic-scroll.ts
@@ -18,14 +18,14 @@ export interface KineticScrollOptions {
}
export class KineticScroll {
- private readonly decelerationRate_: number;
+ private readonly decayLog_: number;
private readonly restVelocity_: number;
private readonly sampleRate_: number;
private velocity_: Vec2 = { x: 0, y: 0 };
private dragging_ = false;
constructor(opts: KineticScrollOptions = {}) {
- this.decelerationRate_ = opts.decelerationRate ?? 0.135;
+ this.decayLog_ = Math.log(opts.decelerationRate ?? 0.135);
this.restVelocity_ = opts.restVelocity ?? 4;
this.sampleRate_ = opts.sampleRate ?? 12;
}
@@ -81,12 +81,20 @@ export class KineticScroll {
* the velocity. Zero vector when not coasting.
*/
tick(dt: number): Vec2 {
- if (!this.isCoasting() || dt <= 0) return { x: 0, y: 0 };
- const delta = { x: this.velocity_.x * dt, y: this.velocity_.y * dt };
- const decay = Math.pow(this.decelerationRate_, dt);
+ if (this.dragging_ || dt <= 0) return { x: 0, y: 0 };
+ const speed = Math.hypot(this.velocity_.x, this.velocity_.y);
+ if (!(speed > this.restVelocity_)) return { x: 0, y: 0 };
+ const exponent = this.decayLog_ * dt;
+ const decay = Math.exp(exponent);
+ const atRest = speed * decay <= this.restVelocity_;
+ const movingTime = atRest && this.restVelocity_ > 0 && this.decayLog_ < 0
+ ? Math.min(dt, Math.log(this.restVelocity_ / speed) / this.decayLog_) : dt;
+ const integratedTime = this.decayLog_ === -Infinity ? 0
+ : this.decayLog_ === 0 ? movingTime : Math.expm1(this.decayLog_ * movingTime) / this.decayLog_;
+ const delta = { x: this.velocity_.x * integratedTime, y: this.velocity_.y * integratedTime };
this.velocity_.x *= decay;
this.velocity_.y *= decay;
- if (!this.isCoasting()) this.velocity_ = { x: 0, y: 0 };
+ if (atRest) this.velocity_ = { x: 0, y: 0 };
return delta;
}
}
diff --git a/sdk/tests/ui-kinetic-scroll.test.ts b/sdk/tests/ui-kinetic-scroll.test.ts
index af6afc0a5..09149b814 100644
--- a/sdk/tests/ui-kinetic-scroll.test.ts
+++ b/sdk/tests/ui-kinetic-scroll.test.ts
@@ -28,6 +28,37 @@ describe('ScrollContainer drag options', () => {
describe('KineticScroll', () => {
const dt = 1 / 60;
+ it('travels the same distance over one second at different frame rates', () => {
+ const distances = [15, 30, 60, 120].map(fps => {
+ const k = new KineticScroll({ restVelocity: 0 }); k.beginDrag();
+ for (let i = 0; i < 60; i++) k.sample({ x: 0, y: 10 }, dt);
+ k.endDrag();
+ let distance = 0;
+ for (let i = 0; i < fps; i++) distance += k.tick(1 / fps).y;
+ return distance;
+ });
+ for (const distance of distances) expect(distance).toBeCloseTo(distances[0], 8);
+ });
+
+ it('stops at the same position even when a long frame crosses the rest threshold', () => {
+ const distances = [1, 15, 30, 60, 120].map(fps => {
+ const k = new KineticScroll(); k.beginDrag();
+ for (let i = 0; i < 60; i++) k.sample({ x: 0, y: 10 }, dt);
+ k.endDrag(); let distance = 0;
+ for (let n = 0; n < fps * 10 && k.isCoasting(); n++) distance += k.tick(1 / fps).y;
+ expect(k.isCoasting()).toBe(false); return distance;
+ });
+ for (const distance of distances) expect(distance).toBeCloseTo(distances[0], 8);
+ });
+
+ it('handles constant speed and immediate deceleration without nonfinite offsets', () => {
+ for (const rate of [0, 1]) {
+ const k = new KineticScroll({ decelerationRate: rate }); k.beginDrag();
+ k.sample({ x: 0, y: 10 }, dt); k.endDrag(); const speed = k.getVelocity().y;
+ expect(k.tick(1).y).toBeCloseTo(rate === 0 ? 0 : speed);
+ }
+ });
+
it('starts at rest: no drag, no coast, zero velocity', () => {
const k = new KineticScroll();
expect(k.isDragging()).toBe(false);
@@ -72,7 +103,7 @@ describe('KineticScroll', () => {
expect(k.tick(dt)).toEqual({ x: 0, y: 0 }); // held drag never coasts
});
- it('release coasts: tick returns v·dt and decays to rest', () => {
+ it('release coasts: tick integrates the decaying velocity to rest', () => {
const k = new KineticScroll();
k.beginDrag();
for (let i = 0; i < 30; i++) k.sample({ x: 0, y: 10 }, dt);
diff --git a/tools/releaseNotes.mjs b/tools/releaseNotes.mjs
index 612c02f02..f541a943d 100644
--- a/tools/releaseNotes.mjs
+++ b/tools/releaseNotes.mjs
@@ -28,6 +28,8 @@ export const NOTES_FLOOR = 'v0.65.0';
* the reader recognises anyway.
*/
export const NOTED = {
+ 'fix(ui): integrate inertial scroll distance across frame rates':
+ { note: 'Inertial scrolling travels consistently across frame rates.' },
'fix(video): synchronize the decoded endpoint before playback ends':
{ note: 'WASM video progress reaches the decoded endpoint.' },
'fix(video): support duration and seeking for single-timestamp streams':