Skip to content

Zoom towards the cursor when using the mouse-wheel or pinch-gestures - #914

Open
driftfox wants to merge 3 commits into
BlueMap-Minecraft:masterfrom
driftfox:feature/zoom-to-cursor-328
Open

driftfox wants to merge 3 commits into
BlueMap-Minecraft:masterfrom
driftfox:feature/zoom-to-cursor-328

Conversation

@driftfox

@driftfox driftfox commented Nov 20, 2026 •

Copy link
Copy Markdown

Summary

Closes #328.

Scroll-wheel zoom (including trackpad scroll) and pinch zoom keep the point under the cursor, or between the fingers, in place. This works for zooming in and out, in the 3D and flat views. Leaflet (OpenStreetMap, Dynmap), Mapbox GL and MapLibre all do this by default.

These still zoom to the centre: the +/- buttons, keyboard zoom, zooming while following a player, and wheel zoom while the camera is rotated or tilted with the mouse (right-drag, or Alt/Ctrl+left-drag).

 MapControls.update()
   move, follow player
+  offset = getZoomAnchorOffset()
+    ray through the cursor ∩ horizontal plane at
+      3D below distance 500: height of the terrain under the cursor
+                             (looked up when the zoom starts or the cursor moves)
+      otherwise:             height of the target
+    minus target
   mouseZoom / keyZoom / touchZoom
   softClamp(distance)
+  if offset: target += (1 - newDistance / oldDistance) * offset
   rotate, tilt, target height (unchanged)

Moving the target this way scales the camera around the point under the cursor without changing its orientation, so that point stays under the cursor.

New webapp.conf option, following the same path as min-zoom-distance:

zoom-to-cursor: true  →  WebappConfig  →  settings.json "zoomToCursor"  →  BlueMapApp  →  MapControls.zoomToCursor

Set it to false for the old centred zoom.

Docs: BlueMap-Minecraft/BlueMapWiki#187

Changes after the feedback on Discord

The second and third commits answer the two points from Discord:

  • Zooming while rotating: while the camera is rotated or tilted with the mouse, including the turn that continues after letting go, the wheel zoom goes to the centre.
  • Mountains and camera height: I first tried pausing the target-height following while zooming. That made it worse. The zoom point came from a plane at the target height, so with the cursor on a mountain the ray hit that plane behind the mountain, and with a fixed height the zoom flew towards it. Following the terrain had partly hidden this, because it lifts the plane as the target approaches, but then the point under the cursor drifted. Now:
    • The target height follows the terrain as before.
    • The zoom point is the real terrain under the cursor:
      • Map.raycastTerrain() raytraces the hires tiles.
      • For the lowres tiles, whose heights only exist in the shader, it samples heights along the ray through lowresTerrainHeightAt(), which is split out of terrainHeightAt() unchanged.
      • The point is only looked up when the zoom starts or the cursor moves.
    • This only applies below a distance of 500. Above that, the target height is faded to 0 and doesn't change while zooming, so the plane at the target height is exact there.

Evidence

  • Before: scrolling with the cursor on a landmark near a corner zooms toward the screen centre, so the landmark moves toward the edge and off screen.
    After: the landmark stays under the cursor while zooming in and out.

  • Before (first commit): with the cursor on a mountain face, the zoom headed for the ground behind the mountain.
    After: it heads for the mountain face.

  • Tested in a browser over several rounds on a server with existing 5.29 maps, using this branch's CLI build, side by side with the earlier builds:

    • wheel zoom in and out at the corners, edges and centre, in 3D and flat
    • zooming at mountains, cliffs and valleys
    • zooming into the min/max distance limits, and a view tilted close to the horizon
    • wheel zoom during and just after a right-drag
    • the +/- buttons, keyboard zoom, and following a player
    • touch pinch
    • zoom-to-cursor: false, which gives the old behaviour
  • A numeric check with the real CombinedCamera and the pose code from ControlsManager.updateCamera(): on flat terrain, the point under the cursor stays fixed (error < 1e-6 NDC) in perspective at several tilts and in the flat view.

  • A frame-by-frame simulation with a mountain, using the real MapHeightControls (terrain following and distance fade) and Map.raycastTerrain(). It covers far and close zooms, flat ground, near and on a mountain, and zooming out. The table shows the worst drift of the point under the cursor on screen (NDC; 2 = the full screen width):

    First commit (plane at target height) Now
    Zoom in, below 500 blocks 0.8 to off screen 0.1 to 0.4
    Zoom in, far out 0.000 0.000
    Zoom out 0.07 to 0.08 0.01 to 0.04
  • npm run build, eslint, spotlessCheck and :cli:release pass.

Merge Danger

Door: two-way

The change only touches the web app's map controls and Map (one new method, plus one split out of terrainHeightAt()), and adds one config option that defaults on. Reverting restores centred zoom.

Blast Radius: small

  • Zoom behaviour changes for every viewer after updating. That's intended; servers can set zoom-to-cursor: false to keep the old behaviour.
  • Performance: one terrain lookup when a zoom starts and when the cursor or pinch centre moves. It's a hires raycast like a map click, or up to 72 lowres height reads.
  • Known limitations:
    • Zooming out in a tilted 3D view can drift slightly, because the tilt is flattened as the distance grows.
    • Below 500 blocks, the point under the cursor can still drift a little over uneven terrain, because the target height keeps following the terrain under the moving target.
    • With the cursor near the horizon, the point is far away, so the target can move a long way in one step. That step is limited to 8 × the distance, the same as before.

I wrote this with help from an AI coding assistant. I reviewed and tested it myself.

…loses BlueMap-Minecraft#328

Adds a webapp.conf setting "zoom-to-cursor" (default: true) to switch back to zooming towards the center of the screen.
The zoom-buttons, keyboard-zoom and zooming while following a player still zoom towards the center.
…e mouse

While the camera is rotated or tilted with the mouse (including the movement that continues after releasing the button),
the mouse-wheel zoom goes towards the center of the screen.
Close up in the perspective view (below a distance of 500, where the target height follows the terrain), the point to
zoom towards is now found at the height of the terrain under the cursor, instead of on the plane at the height of the
camera-target. With the cursor on e.g. a mountain, that point was behind the mountain, so the zoom headed past it.
The hires-tiles are ray-traced and the lowres-tiles are sampled along the ray, only when the zoom starts or the cursor
moves.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Zooming with scroll should centre on the pointer location not the map centre

1 participant