@typeonce/ritmo-browser 0.22.0 → 0.24.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/src/Pointer.ts CHANGED
@@ -9,9 +9,10 @@
9
9
  * as one device for `lastUsed` and `available`). Games that aim with the
10
10
  * mouse read `position`. The module owns the browser plumbing:
11
11
  * element-relative coordinates, press/release edges that survive clicks
12
- * shorter than one frame, pointer capture so a release outside the element
13
- * is still seen, suppressing the context menu, clearing buttons on window
14
- * blur, and listener cleanup. It does not know about the ECS;
12
+ * shorter than one frame, buttons pressed and released while another is
13
+ * held (which browsers report as pointer moves), pointer capture so a
14
+ * release outside the element is still seen, suppressing the context menu,
15
+ * clearing buttons on window blur, and listener cleanup. It does not know about the ECS;
15
16
  * `InputCapture.system(...)` copies snapshots into a resource.
16
17
  *
17
18
  * Positions are in CSS pixels relative to the element's top-left corner.
@@ -97,6 +98,14 @@ export const wheelStep = 100
97
98
 
98
99
  const buttonOf = (code: number): Button | undefined => physicalButtons[code]
99
100
 
101
+ /**
102
+ * Each physical button's bit in `PointerEvent.buttons`, in `PointerEvent.button`
103
+ * order: the two encodings swap the middle and secondary buttons.
104
+ */
105
+ const buttonBits = [1, 4, 2, 8, 16] as const
106
+
107
+ const bitOf = (code: number): number => buttonBits[code] ?? 0
108
+
100
109
  const buttonSet: ReadonlySet<string> = new Set(buttonNames)
101
110
 
102
111
  /** Whether `name` is a pointer button, for validating stored bindings. */
@@ -190,7 +199,7 @@ export interface Actions<B extends Bindings> extends System.Consumes<"snapshot">
190
199
  * the pointer was made with.
191
200
  */
192
201
  rebind<const R extends Rebinding<B>>(bindings: R & OnlyActionsOf<R, B>): void
193
- /** Removes the event listeners. */
202
+ /** Removes the event listeners and releases the pointer capture, if taken. */
194
203
  dispose(): void
195
204
  }
196
205
 
@@ -203,7 +212,17 @@ export interface PointerEventLike {
203
212
  /** Raw motion since the previous event; events without it count as 0. */
204
213
  readonly movementX?: number
205
214
  readonly movementY?: number
215
+ /** The button that changed: 0 primary, 1 middle, 2 secondary, 3 back, 4 forward. */
206
216
  readonly button: number
217
+ /**
218
+ * Every button down after this event, as a bitmask: 1 primary, 2
219
+ * secondary, 4 middle, 8 back, 16 forward. Browsers send `pointerdown`
220
+ * only for the first button down and `pointerup` only for the last one up;
221
+ * the buttons in between arrive as `pointermove`, so the module holds what
222
+ * this reports on every down, up, and move. Events without it are read by
223
+ * `button` alone, which misses those.
224
+ */
225
+ readonly buttons?: number
207
226
  readonly pointerId: number
208
227
  /** `"mouse"`, `"pen"`, or `"touch"`; events without it count as mouse. */
209
228
  readonly pointerType?: string
@@ -363,7 +382,8 @@ const tracker = <B extends Bindings>(initial: B, start: Position) => {
363
382
  * Starts tracking the pointer over `target` with `bindings`, until
364
383
  * `dispose()`. `blurHost` (usually `window`) releases held buttons when the
365
384
  * page loses focus; a cancelled pointer and leaving the pointer lock release
366
- * them too. Use `Touch.actions` for on-screen touch controls.
385
+ * them too. Each of these, the last button coming up, and `dispose()` also
386
+ * release the pointer capture the first press took. Use `Touch.actions` for on-screen touch controls.
367
387
  */
368
388
  export const actions = <const B extends Bindings>(
369
389
  target: PointerTarget,
@@ -379,6 +399,64 @@ export const actions = <const B extends Bindings>(
379
399
  const state = tracker(bindings, { x: 0, y: 0 })
380
400
  let over = false
381
401
  const isLocked = (): boolean => lock !== undefined && lock.pointerLockElement === target
402
+ const awaitingLock = (): boolean => lock !== undefined && !isLocked()
403
+ // Buttons that went down while the pointer was not locked, ignored until they
404
+ // come up: the click that locks is not a press, even once the lock is taken.
405
+ let ignored = 0
406
+ // The pointer id capture was taken for, until it is released.
407
+ let captured: number | null = null
408
+
409
+ const capture = (pointerId: number): void => {
410
+ captured = pointerId
411
+ target.setPointerCapture?.(pointerId)
412
+ }
413
+
414
+ const release = (): void => {
415
+ if (captured === null) return
416
+ const pointerId = captured
417
+ captured = null
418
+ // Browsers throw for a pointer that is no longer active (after a cancel) or not captured.
419
+ try {
420
+ target.releasePointerCapture?.(pointerId)
421
+ } catch {
422
+ // The capture is already gone.
423
+ }
424
+ }
425
+
426
+ // A blur, a cancelled pointer, and leaving the lock let go of every button and of the capture.
427
+ const letGo = (): void => {
428
+ state.buttons.upAll()
429
+ release()
430
+ }
431
+
432
+ const heldMask = (): number => {
433
+ let mask = 0
434
+ for (let code = 0; code < physicalButtons.length; code++) {
435
+ if (state.buttons.held.has(physicalButtons[code]!)) mask |= buttonBits[code]!
436
+ }
437
+ return mask
438
+ }
439
+
440
+ /**
441
+ * Holds exactly the buttons of `mask` (a `buttons` bitmask), pressing and
442
+ * releasing those that changed, and captures the pointer while any is held.
443
+ */
444
+ const hold = (mask: number, pointerId: number, unlocked: boolean): void => {
445
+ const wasHeld = state.buttons.held.size > 0
446
+ ignored &= mask
447
+ for (let code = 0; code < physicalButtons.length; code++) {
448
+ const button = physicalButtons[code]!
449
+ const bit = buttonBits[code]!
450
+ if ((mask & bit) === 0) state.buttons.up(button)
451
+ else if ((ignored & bit) === 0 && !state.buttons.held.has(button)) {
452
+ if (unlocked) ignored |= bit
453
+ else state.buttons.down(button)
454
+ }
455
+ }
456
+ const isHeld = state.buttons.held.size > 0
457
+ if (!wasHeld && isHeld) capture(pointerId)
458
+ else if (wasHeld && !isHeld) release()
459
+ }
382
460
 
383
461
  const locate = (event: PointerEventLike): void => {
384
462
  const rect = target.getBoundingClientRect()
@@ -391,30 +469,30 @@ export const actions = <const B extends Bindings>(
391
469
  locate(event)
392
470
  over = true
393
471
  const button = buttonOf(event.button)
394
- if (button === undefined) return
395
- event.preventDefault()
396
- if (lock !== undefined && !isLocked()) {
472
+ const unlocked = awaitingLock()
473
+ if (button !== undefined) {
474
+ event.preventDefault()
397
475
  // The click that locks is not a press: "click to resume" does not also fire.
398
- target.requestPointerLock?.()
399
- return
476
+ if (unlocked) target.requestPointerLock?.()
400
477
  }
401
- target.setPointerCapture?.(event.pointerId)
402
- state.buttons.down(button)
478
+ if (event.buttons !== undefined) hold(event.buttons, event.pointerId, unlocked)
479
+ else if (button !== undefined && !unlocked) hold(heldMask() | bitOf(event.button), event.pointerId, false)
403
480
  }
404
481
 
405
482
  const onUp = (event: PointerEventLike): void => {
406
483
  if (!tracked(event)) return
407
484
  locate(event)
408
485
  const button = buttonOf(event.button)
409
- if (button === undefined || !state.buttons.held.has(button)) return
410
- state.buttons.up(button)
411
- if (state.buttons.held.size === 0) target.releasePointerCapture?.(event.pointerId)
486
+ if (event.buttons !== undefined) hold(event.buttons, event.pointerId, awaitingLock())
487
+ else if (button !== undefined && state.buttons.held.has(button)) hold(heldMask() & ~bitOf(event.button), event.pointerId, false)
412
488
  }
413
489
 
414
490
  const onMove = (event: PointerEventLike): void => {
415
491
  if (!tracked(event)) return
416
492
  locate(event)
417
493
  over = true
494
+ // A button pressed or released while another is held arrives as a move.
495
+ if (event.buttons !== undefined) hold(event.buttons, event.pointerId, awaitingLock())
418
496
  }
419
497
 
420
498
  const onLeave = (event: PointerEventLike): void => {
@@ -422,7 +500,7 @@ export const actions = <const B extends Bindings>(
422
500
  }
423
501
 
424
502
  const onCancel = (event: PointerEventLike): void => {
425
- if (tracked(event)) state.buttons.upAll()
503
+ if (tracked(event)) letGo()
426
504
  }
427
505
 
428
506
  const onContextMenu = (event: { preventDefault(): void }): void => {
@@ -437,7 +515,7 @@ export const actions = <const B extends Bindings>(
437
515
 
438
516
  // Leaving the lock (Escape) releases what was held, like a blur.
439
517
  const onLockChange = (): void => {
440
- if (!isLocked()) state.buttons.upAll()
518
+ if (!isLocked()) letGo()
441
519
  }
442
520
 
443
521
  target.addEventListener("pointerdown", onDown)
@@ -448,7 +526,7 @@ export const actions = <const B extends Bindings>(
448
526
  target.addEventListener("pointercancel", onCancel)
449
527
  target.addEventListener("contextmenu", onContextMenu)
450
528
  target.addEventListener("wheel", onWheel, { passive: false })
451
- blurHost.addEventListener("blur", state.buttons.upAll)
529
+ blurHost.addEventListener("blur", letGo)
452
530
  lock?.addEventListener("pointerlockchange", onLockChange)
453
531
 
454
532
  return {
@@ -466,8 +544,9 @@ export const actions = <const B extends Bindings>(
466
544
  target.removeEventListener("pointercancel", onCancel)
467
545
  target.removeEventListener("contextmenu", onContextMenu)
468
546
  target.removeEventListener("wheel", onWheel)
469
- blurHost.removeEventListener("blur", state.buttons.upAll)
547
+ blurHost.removeEventListener("blur", letGo)
470
548
  lock?.removeEventListener("pointerlockchange", onLockChange)
549
+ release()
471
550
  }
472
551
  }
473
552
  }