PointerDrag

PointerDrag

Grab things with the mouse and slide them in the plane that faces the camera.

What it does

The pointer is a ray from the camera through the cursor. Hover tests it against an invisible sphere round each enabled draggable, and the nearest hit wins. A press grabs the hovered entity. Each frame after that, the entity moves to where the ray crosses the plane through it that faces the camera, keeping its grab offset and staying inside its box. Under a camera that looks straight down an axis, that plane is exactly two world axes: X and Z from the top, X and Y from the side.

The System listens for pointer events on the render canvas, because Babylon swallows mousedown there. The handlers only store the latest pointer state, and the System does all the work in its own update, so it is the one writer of a dragged entity's position. A mesh moved from a DOM handler would land between frames and race every other system.

A click is worked out from the pointer stream, not taken from the browser: a primary press and release that never strayed more than 6 CSS pixels and grabbed nothing. The grab is noted on the press, so a hole that leaves play while held (the player presses R) does not turn the release into a click on the space it left.

Use it in a scene

{
  "Camera": {
    "tags": ["camera"],
    "components": {
      "AxisViewCamera": { "view": "top", "size": [72, 32, 32], "fov": 0.6 }
    }
  },
  "Hole": {
    "tags": ["blackhole"],
    "components": {
      "MeshPrimitive": { "primitive": "sphere", "diameter": 1 },
      "PointerDrag": { "pickRadius": 2.6, "min": [-33, -14, -14], "max": [33, 14, 14] }
    }
  }
}

The box keeps a hole a few units inside SpaceGolf's field, which runs 36 each way on X and 16 on Y and Z.

Props

• pickRadius (number, default 1.5) — radius of the sphere the pointer has to hit to grab the entity.
• enabled (boolean, default true) — whether it can be grabbed right now. Hover skips it when false.
• min (vec3, default [-1e6, -1e6, -1e6]) — lower corner of the box it may be dragged within.
• max (vec3, default [1e6, 1e6, 1e6]) — upper corner of that box.

Events

Emits:

• pointerdrag.hover.changed { entityId } when the draggable under the pointer changes, with null for none.
• pointerdrag.started / pointerdrag.moved / pointerdrag.ended { entityId, x, y, z } through a drag, with the entity's position. A pointer held still sends no moved.
• pointerdrag.wheel { entityId, delta } for a turn over the hovered or held entity, in whole notches of 90 pixels. +1 is away from you. A black hole reads it as mass. A turn over empty space is dropped and the page scrolls.
• pointerdrag.context { entityId } for a right-click on a draggable, which also blocks the browser menu there.
• pointerdrag.empty.clicked { x, y, z } for a click on empty space, at the spot where the ray crosses the plane through the world origin.

Listens:

• camera.active.changed { handle } for the camera to cast rays from. AxisViewCamera sends it.
• arccamera.created { handle } as a fallback. An announced active camera wins.

Dependencies

MeshPrimitive. The position lives there: the System reads it to pick and writes it to drag. The scene also needs a camera that announces itself.

Notes

• Make pickRadius generous. Under a narrow camera a small target is a few pixels across, and a missed grab is the worst thing a drag tool can do.
• Empty clicks land on a plane through the world origin, so centre the play field there. In a top view a click lands at height 0, in a side view at depth 0.
• The drag plane is set at the press and kept until release, so a view switched mid-drag still drags along the old plane.
• A pool blueprint (an entity carrying Pool) is never offered to the pointer. An entity that leaves play mid-drag still gets pointerdrag.ended.
• Rays start on the camera's near plane and use the pointer's place in the canvas's CSS box, so they land true at any pixel ratio.