@typeonce/ritmo-browser 0.14.0 → 0.16.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.
Files changed (47) hide show
  1. package/CHANGELOG.md +119 -1
  2. package/README.md +17 -1
  3. package/dist/BrowserTickSource.d.ts +9 -1
  4. package/dist/BrowserTickSource.d.ts.map +1 -1
  5. package/dist/BrowserTickSource.js +9 -1
  6. package/dist/BrowserTickSource.js.map +1 -1
  7. package/dist/BrowserVisibility.d.ts +36 -0
  8. package/dist/BrowserVisibility.d.ts.map +1 -0
  9. package/dist/BrowserVisibility.js +37 -0
  10. package/dist/BrowserVisibility.js.map +1 -0
  11. package/dist/Controls.d.ts +61 -7
  12. package/dist/Controls.d.ts.map +1 -1
  13. package/dist/Controls.js +78 -2
  14. package/dist/Controls.js.map +1 -1
  15. package/dist/Gamepad.d.ts +7 -0
  16. package/dist/Gamepad.d.ts.map +1 -1
  17. package/dist/Gamepad.js +4 -0
  18. package/dist/Gamepad.js.map +1 -1
  19. package/dist/InputCapture.d.ts +35 -3
  20. package/dist/InputCapture.d.ts.map +1 -1
  21. package/dist/InputCapture.js.map +1 -1
  22. package/dist/Keyboard.d.ts +10 -0
  23. package/dist/Keyboard.d.ts.map +1 -1
  24. package/dist/Keyboard.js +6 -0
  25. package/dist/Keyboard.js.map +1 -1
  26. package/dist/Pointer.d.ts +14 -0
  27. package/dist/Pointer.d.ts.map +1 -1
  28. package/dist/Pointer.js +5 -0
  29. package/dist/Pointer.js.map +1 -1
  30. package/dist/Touch.d.ts +27 -9
  31. package/dist/Touch.d.ts.map +1 -1
  32. package/dist/Touch.js +1 -0
  33. package/dist/Touch.js.map +1 -1
  34. package/dist/index.d.ts +3 -1
  35. package/dist/index.d.ts.map +1 -1
  36. package/dist/index.js +3 -1
  37. package/dist/index.js.map +1 -1
  38. package/package.json +2 -2
  39. package/src/BrowserTickSource.ts +9 -1
  40. package/src/BrowserVisibility.ts +47 -0
  41. package/src/Controls.ts +137 -8
  42. package/src/Gamepad.ts +7 -0
  43. package/src/InputCapture.ts +36 -3
  44. package/src/Keyboard.ts +10 -0
  45. package/src/Pointer.ts +14 -0
  46. package/src/Touch.ts +31 -13
  47. package/src/index.ts +3 -1
package/src/Controls.ts CHANGED
@@ -31,6 +31,13 @@
31
31
  * devices inside the `merge(...)` call, so nothing else takes their
32
32
  * snapshots. A game with one device captures that device directly instead.
33
33
  *
34
+ * Declare the input service as `InputCapture.SourceOf<...>` the merge (its
35
+ * `snapshot()` only), and keep the merge in the host to rebind and dispose
36
+ * it. The snapshot is plain data, so the same descriptor replays
37
+ * (`playback.source(ControlsInput)`) and fuzzes: `Fuzz.input(ControlsInput,
38
+ * { generate: (random) => Actions.random(random, devices), neutral:
39
+ * Actions.idle(devices) })`.
40
+ *
34
41
  * A merge is one player on every device. For local multiplayer, where each
35
42
  * device belongs to the player who joined with it, declare
36
43
  * `Controls.players(Actions, { slots, join, leave })` and capture its
@@ -41,6 +48,9 @@
41
48
  *
42
49
  * @example
43
50
  * ```ts
51
+ * declare const walk: (direction: Controls.Vector) => void
52
+ * declare const jump: () => void
53
+ * // ---cut---
44
54
  * const Actions = Controls.actions({ buttons: ["jump", "pause"], vectors: ["move"] })
45
55
  *
46
56
  * const keyBindings = {
@@ -60,8 +70,10 @@
60
70
  * readonly gamepad: Gamepad.Actions<typeof padBindings>
61
71
  * }) => Actions.merge(devices)
62
72
  *
63
- * const ControlsInput = Descriptor.Service<ReturnType<typeof makeControls>>()("Game/Controls")
73
+ * // Only the snapshot: a replay or the fuzzer provides it in place of the devices.
74
+ * const ControlsInput = Descriptor.Service<InputCapture.SourceOf<ReturnType<typeof makeControls>>>()("Game/Controls")
64
75
  * const Input = Descriptor.TransientResource<InputCapture.SnapshotOf<typeof ControlsInput>>()("Game/Input")
76
+ * const Game = Schema.bind(Schema.fragment({ resources: { Input } }))
65
77
  * const CaptureInput = InputCapture.system(Game, { name: "Game/CaptureInput", source: ControlsInput, resource: Input })
66
78
  *
67
79
  * const runtime = Game.Runtime.make({
@@ -72,11 +84,13 @@
72
84
  * resources: { Input: Actions.idle({ keyboard: Keyboard.idle(keyBindings), gamepad: Gamepad.idle(padBindings) }) }
73
85
  * }).value
74
86
  *
75
- * // In a system:
76
- * const input = resources.input.get()
77
- * walk(input.vectors.move) // length at most 1: keys, d-pad, or stick
78
- * if (input.actions.jump.pressed) jump()
79
- * const prompt = input.lastUsed === "gamepad" ? "Ⓐ" : "Space"
87
+ * // Every other system reads the captured resource:
88
+ * const Walk = Game.System("Game/Walk", { resources: { input: Game.System.readResource(Input) } }, ({ resources }) => {
89
+ * const input = resources.input.get()
90
+ * walk(input.vectors.move) // length at most 1: keys, d-pad, or stick
91
+ * if (input.actions.jump.pressed) jump()
92
+ * const prompt = input.lastUsed === "gamepad" ? "Ⓐ" : "Space"
93
+ * })
80
94
  * ```
81
95
  */
82
96
  import type * as System from "@typeonce/ritmo/System"
@@ -332,8 +346,67 @@ export interface ActionSet<A extends string, V extends string = never> {
332
346
  * (`Keyboard.idle(...)`, ...) under its device name.
333
347
  */
334
348
  idle<const Devices extends Readonly<Record<string, DeviceSnapshot<string, string>>>>(devices: Devices): Snapshot<A, V, Devices, never>
349
+ /**
350
+ * A merged snapshot with every action drawn from `random`, for fuzzing the
351
+ * input source (`Fuzz.input`'s `generate`, which hands over the
352
+ * generator). Each button is in a state a merge can report (idle, held,
353
+ * just pressed, tapped, or just released) and each vector is zero, one of
354
+ * the eight directions, or a tilt shorter than 1. Device data stays as
355
+ * given (pass the same idle snapshots as to {@link idle}), every action is
356
+ * available, and no device is last used. Use {@link idle} for the input of
357
+ * a player who does nothing.
358
+ */
359
+ random<const Devices extends Readonly<Record<string, DeviceSnapshot<string, string>>>>(
360
+ random: Draw,
361
+ devices: Devices
362
+ ): Snapshot<A, V, Devices, never>
335
363
  }
336
364
 
365
+ /** A generator `random` draws from: `Random` from `@typeonce/ritmo`, as `Fuzz.input`'s `generate` hands it over. */
366
+ export interface Draw {
367
+ /** Uniform in [0, 1). */
368
+ next(): number
369
+ }
370
+
371
+ /** The button states a merge can report, `idle` first. */
372
+ const buttonStates: ReadonlyArray<ActionState> = [
373
+ { held: false, pressed: false, released: false },
374
+ { held: true, pressed: false, released: false },
375
+ { held: true, pressed: true, released: false },
376
+ { held: false, pressed: true, released: true },
377
+ { held: false, pressed: false, released: true }
378
+ ]
379
+
380
+ /** Idle half the time, otherwise one of the other states a merge reports. */
381
+ const randomButton = (random: Draw): ActionState =>
382
+ random.next() < 0.5 ? buttonStates[0]! : buttonStates[1 + Math.floor(random.next() * 4)]!
383
+
384
+ const diagonal = Math.SQRT1_2
385
+
386
+ /** The eight directions a d-pad or keys report, each of length 1. */
387
+ const directions: ReadonlyArray<Vector> = [
388
+ { x: 1, y: 0 }, { x: -1, y: 0 }, { x: 0, y: 1 }, { x: 0, y: -1 },
389
+ { x: diagonal, y: diagonal }, { x: -diagonal, y: diagonal }, { x: diagonal, y: -diagonal }, { x: -diagonal, y: -diagonal }
390
+ ]
391
+
392
+ /** Zero, a full direction, or a stick's tilt shorter than 1, a third of the time each. */
393
+ const randomVector = (random: Draw): Vector => {
394
+ const kind = Math.floor(random.next() * 3)
395
+ if (kind === 0) return zero
396
+ if (kind === 1) return directions[Math.floor(random.next() * directions.length)]!
397
+ const x = random.next() * 2 - 1
398
+ const y = random.next() * 2 - 1
399
+ const length = Math.sqrt(x * x + y * y)
400
+ if (length === 0) return zero
401
+ const tilt = random.next()
402
+ return { x: (x / length) * tilt, y: (y / length) * tilt }
403
+ }
404
+
405
+ const randomInput = (random: Draw, buttons: ReadonlyArray<string>, vectors: ReadonlyArray<string>) => ({
406
+ actions: Object.fromEntries(buttons.map((name) => [name, randomButton(random)])),
407
+ vectors: Object.fromEntries(vectors.map((name) => [name, randomVector(random)]))
408
+ })
409
+
337
410
  const idleState: ActionState = { held: false, pressed: false, released: false }
338
411
 
339
412
  const isLacking = (entry: unknown): entry is Lacking<Unit | Pads, string> => (entry as Partial<Lacking<Unit, string>>)._tag === "Lacking"
@@ -447,7 +520,17 @@ export const actions = <const Buttons extends readonly [string, ...Array<string>
447
520
  available: everyAvailable() as Snapshot<A, V, never>["available"],
448
521
  devices,
449
522
  lastUsed: null
450
- })
523
+ }),
524
+ random: (random, devices) => {
525
+ const input = randomInput(random, list, vectorList)
526
+ return {
527
+ actions: input.actions as Snapshot<A, V, never>["actions"],
528
+ vectors: input.vectors as Snapshot<A, V, never>["vectors"],
529
+ available: everyAvailable() as Snapshot<A, V, never>["available"],
530
+ devices,
531
+ lastUsed: null
532
+ }
533
+ }
451
534
  }
452
535
  }
453
536
 
@@ -573,6 +656,21 @@ export interface PlayerSet<A extends string, V extends string, S extends string,
573
656
  * `Gamepad.idle(...)` for pads) under its pool name.
574
657
  */
575
658
  idle<const Devices extends Readonly<Record<string, DeviceSnapshot<string, string>>>>(devices: Devices): PlayersSnapshot<A, V, S, Devices>
659
+ /**
660
+ * Every player's input for one fuzzed frame (`Fuzz.input`'s `generate`,
661
+ * which hands over the generator and the frame). The slots in `seats`
662
+ * are held through the named pool device from the first frame, as
663
+ * `pool.seat` in setup does: frame 1 reports their `event: "joined"`
664
+ * with idle input, and every later frame draws their actions as the
665
+ * action set's `random` does. The other slots stay empty and joining
666
+ * stays closed. Pass each device's idle snapshot under its pool name, as
667
+ * to {@link idle}; use {@link idle} for the neutral input.
668
+ */
669
+ random<const Devices extends Readonly<Record<string, DeviceSnapshot<string, string>>>>(
670
+ random: Draw,
671
+ frame: number,
672
+ options: { readonly devices: Devices; readonly seats: { readonly [K in S]?: keyof Devices & string } }
673
+ ): PlayersSnapshot<A, V, S, Devices>
576
674
  }
577
675
 
578
676
  /** Rejects a slot named like the snapshot's own field. */
@@ -602,15 +700,23 @@ type NoAnyAction<A extends string> = [A & "any"] extends [never] ? unknown : "an
602
700
  *
603
701
  * @example
604
702
  * ```ts
703
+ * const Actions = Controls.actions({ buttons: ["join", "back", "jump"], vectors: ["move"] })
704
+ * const leftKeys = { move: Keyboard.vector({ up: ["w"], down: ["s"], left: ["a"], right: ["d"] }), join: [" "], back: ["q"], jump: [" "] } as const
705
+ * const rightKeys = { move: Keyboard.vector({ up: ["ArrowUp"], down: ["ArrowDown"], left: ["ArrowLeft"], right: ["ArrowRight"] }), join: ["Enter"], back: ["Backspace"], jump: ["Enter"] } as const
706
+ * const padBindings = { move: Gamepad.vector({ stick: "left" }), join: ["south"], back: ["east"], jump: ["south"] } as const
707
+ * // The captured resource, as a system reads it (`resources.input.get()`):
708
+ * declare const input: InputCapture.SnapshotOf<typeof PlayersInput>
709
+ * declare const spawnSecondPlayer: () => void
710
+ * // ---cut---
605
711
  * const Players = Controls.players(Actions, { slots: ["p1", "p2"], join: "join", leave: "back" })
606
712
  * const makePlayers = (devices: {
607
713
  * readonly left: Keyboard.Actions<typeof leftKeys>
608
714
  * readonly right: Keyboard.Actions<typeof rightKeys>
609
715
  * readonly pads: Gamepad.Pads<typeof padBindings>
610
716
  * }) => Players.pool(devices)
717
+ * const PlayersInput = Descriptor.Service<InputCapture.SourceOf<ReturnType<typeof makePlayers>>>()("Game/Players")
611
718
  *
612
719
  * // In a system:
613
- * const input = resources.input.get()
614
720
  * if (input.p2.event === "joined") spawnSecondPlayer()
615
721
  * const move = input.p2.vectors.move
616
722
  * ```
@@ -640,6 +746,29 @@ export const players = <
640
746
  return {
641
747
  slots,
642
748
  idle: () => ({ joining: false, ...Object.fromEntries(slots.map((slot) => [slot, empty(null)])) }) as never,
749
+ random: (random, frame, { devices, seats }) => {
750
+ const seated: Readonly<Record<string, string | undefined>> = seats
751
+ const result: Record<string, unknown> = { joining: false }
752
+ for (const slot of slots) {
753
+ const device = seated[slot]
754
+ if (device === undefined) {
755
+ result[slot] = empty(null)
756
+ continue
757
+ }
758
+ const joined = frame <= 1
759
+ result[slot] = {
760
+ ...idleInput(),
761
+ ...(joined ? {} : randomInput(random, buttons, vectors)),
762
+ joined: true,
763
+ device,
764
+ connected: true,
765
+ event: joined ? "joined" : null,
766
+ devices: { [device]: devices[device] }
767
+ }
768
+ }
769
+ // The checked signature carries the slot and device types; every slot is filled above.
770
+ return result as never
771
+ },
643
772
  pool(devices) {
644
773
  const entries = Object.entries(devices as Readonly<Record<string, PoolEntry>>).map(([name, entry]) => {
645
774
  const unit = isLacking(entry) ? entry.device : entry
package/src/Gamepad.ts CHANGED
@@ -34,6 +34,9 @@
34
34
  *
35
35
  * @example
36
36
  * ```ts
37
+ * declare const move: (direction: Controls.Vector) => void
38
+ * declare const attack: () => void
39
+ * // ---cut---
37
40
  * const pad = Gamepad.actions(window, {
38
41
  * move: Gamepad.vector({ stick: "left", up: ["dpadUp"], down: ["dpadDown"], left: ["dpadLeft"], right: ["dpadRight"] }),
39
42
  * attack: ["west"],
@@ -740,6 +743,10 @@ export type InvalidRebinding = ButtonsInternal.InvalidRebinding
740
743
  *
741
744
  * @example
742
745
  * ```ts
746
+ * const bindings = { move: Gamepad.vector({ stick: "left" }), jump: ["south"] } as const
747
+ * const pad = Gamepad.actions(window, bindings)
748
+ * declare const stored: string
749
+ * // ---cut---
743
750
  * const saved = Gamepad.parseRebinding(bindings, JSON.parse(stored))
744
751
  * if (saved.ok) pad.rebind(saved.value)
745
752
  * ```
@@ -25,6 +25,11 @@
25
25
  * `Game.System.service` (to rebind it, say) cannot call `snapshot()`.
26
26
  * Capture each source once and read the resource everywhere else.
27
27
  *
28
+ * Declare the source service as {@link SourceOf} the device (only its
29
+ * `snapshot()`), not as the device: the same descriptor then takes the live
30
+ * device in the page, a scripted one in tests, and the recorded or fuzzed
31
+ * input of `@typeonce/ritmo-devtools`' `Replay` and `Fuzz`.
32
+ *
28
33
  * @module InputCapture
29
34
  * @docGroup browser
30
35
  *
@@ -32,11 +37,15 @@
32
37
  * ```ts
33
38
  * const bindings = { left: ["ArrowLeft", "a"], right: ["ArrowRight", "d"], jump: [" "] } as const
34
39
  *
35
- * const KeyboardInput = Descriptor.Service<Keyboard.Actions<typeof bindings>>()("Game/Keyboard")
36
- * const Input = Descriptor.TransientResource<Keyboard.Snapshot<typeof bindings>>()("Game/Input")
40
+ * const KeyboardInput = Descriptor.Service<InputCapture.SourceOf<Keyboard.Actions<typeof bindings>>>()("Game/Keyboard")
41
+ * const Input = Descriptor.TransientResource<InputCapture.SnapshotOf<typeof KeyboardInput>>()("Game/Input")
42
+ * const Game = Schema.bind(Schema.fragment({ resources: { Input } }))
37
43
  *
38
44
  * const CaptureInput = InputCapture.system(Game, { name: "Game/CaptureInput", source: KeyboardInput, resource: Input })
39
- * const update = Game.Schedule(CaptureInput, Move, Jump)
45
+ * const Jump = Game.System("Game/Jump", { resources: { input: Game.System.readResource(Input) } }, ({ resources }) => {
46
+ * if (resources.input.get().actions.jump.pressed) console.log("jump")
47
+ * })
48
+ * const update = Game.Schedule(CaptureInput, Jump)
40
49
  *
41
50
  * const runtime = Game.Runtime.make({
42
51
  * services: Game.Runtime.services(Game.Runtime.service(KeyboardInput, Keyboard.actions(window, bindings))),
@@ -58,6 +67,30 @@ export interface Source<Value> extends System.Consumes<"snapshot"> {
58
67
  readonly snapshot: () => Value
59
68
  }
60
69
 
70
+ /**
71
+ * The input service a game declares: the `snapshot()` of a device, a
72
+ * `Controls` merge, or a `Controls.players` pool, without its `rebind` and
73
+ * `dispose`. Declare the source service with it
74
+ * (`Descriptor.Service<InputCapture.SourceOf<typeof device>>()`), so the
75
+ * same descriptor is provided by the live devices in the page, by scripted
76
+ * devices in tests, by `playback.source(...)` in a replay, and by
77
+ * `Fuzz.input(...)` in the fuzzer. Keep the device itself in the host to
78
+ * rebind and dispose it. Use {@link Source} when the snapshot type is
79
+ * written out instead of taken from a device.
80
+ *
81
+ * @example
82
+ * ```ts
83
+ * const Actions = Controls.actions({ buttons: ["jump"] })
84
+ * const keys = { jump: [" "] } as const
85
+ * const pad = { jump: ["south"] } as const
86
+ * // ---cut---
87
+ * const makeControls = (devices: { readonly keyboard: Keyboard.Actions<typeof keys>; readonly gamepad: Gamepad.Actions<typeof pad> }) =>
88
+ * Actions.merge(devices)
89
+ * const ControlsInput = Descriptor.Service<InputCapture.SourceOf<ReturnType<typeof makeControls>>>()("Game/Controls")
90
+ * ```
91
+ */
92
+ export type SourceOf<Device extends Source<unknown>> = Source<ReturnType<Device["snapshot"]>>
93
+
61
94
  type ServiceDescriptor = Descriptor<"service", string, any>
62
95
  type ResourceDescriptor = Descriptor<"resource", string, any>
63
96
 
package/src/Keyboard.ts CHANGED
@@ -30,6 +30,8 @@
30
30
  *
31
31
  * @example
32
32
  * ```ts
33
+ * declare const jump: () => void
34
+ * // ---cut---
33
35
  * const input = Keyboard.actions(window, {
34
36
  * left: ["ArrowLeft", "a"],
35
37
  * right: ["ArrowRight", "d"],
@@ -61,6 +63,8 @@
61
63
  *
62
64
  * @example
63
65
  * ```ts
66
+ * declare const saved: string
67
+ * // ---cut---
64
68
  * // Browser: record a session, then save `recorder.timeline()` as JSON.
65
69
  * const recorder = Keyboard.recording(Keyboard.actions(window, bindings))
66
70
  *
@@ -490,6 +494,9 @@ export interface Presses extends System.Consumes<"snapshot"> {
490
494
  *
491
495
  * @example
492
496
  * ```ts
497
+ * const input = Keyboard.actions(window, bindings)
498
+ * declare const current: Keyboard.Rebinding<typeof bindings>
499
+ * // ---cut---
493
500
  * const presses = Keyboard.presses(window)
494
501
  *
495
502
  * // While the settings screen waits for the new jump key:
@@ -743,6 +750,9 @@ export interface InvalidRebinding {
743
750
  *
744
751
  * @example
745
752
  * ```ts
753
+ * const input = Keyboard.actions(window, bindings)
754
+ * declare const stored: string
755
+ * // ---cut---
746
756
  * const saved = Keyboard.parseRebinding(bindings, JSON.parse(stored))
747
757
  * if (saved.ok) input.rebind(saved.value)
748
758
  * ```
package/src/Pointer.ts CHANGED
@@ -31,6 +31,12 @@
31
31
  *
32
32
  * @example
33
33
  * ```ts
34
+ * declare const canvas: HTMLCanvasElement
35
+ * declare const aimAt: (position: Pointer.Position) => void
36
+ * declare const fire: () => void
37
+ * declare const zoomBy: (steps: number) => void
38
+ * declare const turn: (by: number) => void
39
+ * // ---cut---
34
40
  * const bindings = { fire: ["primary"], aim: ["secondary"], nextWeapon: ["wheelDown"] } as const
35
41
  * const mouse = Pointer.actions(canvas, window, bindings, { lock: document })
36
42
  *
@@ -168,6 +174,9 @@ export interface Snapshot<B extends Bindings> {
168
174
  * A pointer bound to actions, built with {@link actions} (live),
169
175
  * {@link scripted}, or {@link recording}. Capture it with
170
176
  * `InputCapture.system(...)`, or group it with the keyboard in `Controls`.
177
+ *
178
+ * In a test, build one with {@link scripted} rather than writing the object
179
+ * by hand: a hand-written double must also implement `rebind` and `dispose`.
171
180
  */
172
181
  export interface Actions<B extends Bindings> extends System.Consumes<"snapshot"> {
173
182
  /** Returns the pointer state and starts a new press/release window. */
@@ -649,6 +658,11 @@ export type InvalidRebinding = ButtonsInternal.InvalidRebinding
649
658
  *
650
659
  * @example
651
660
  * ```ts
661
+ * declare const canvas: HTMLCanvasElement
662
+ * const bindings = { fire: ["primary"], aim: ["secondary"] } as const
663
+ * const mouse = Pointer.actions(canvas, window, bindings)
664
+ * declare const stored: string
665
+ * // ---cut---
652
666
  * const saved = Pointer.parseRebinding(bindings, JSON.parse(stored))
653
667
  * if (saved.ok) mouse.rebind(saved.value)
654
668
  * ```
package/src/Touch.ts CHANGED
@@ -43,6 +43,11 @@
43
43
  *
44
44
  * @example
45
45
  * ```ts
46
+ * declare const canvas: HTMLCanvasElement
47
+ * declare const move: (direction: Touch.StickState) => void
48
+ * declare const shoot: (direction: Touch.StickState) => void
49
+ * declare const dash: () => void
50
+ * // ---cut---
46
51
  * const touch = Touch.actions(canvas, window, ({ width, height }) => ({
47
52
  * // Each stick drives the vector named like its key, so it merges into `Controls`.
48
53
  * sticks: {
@@ -99,9 +104,9 @@ export interface StickZone {
99
104
  * button has the same name (a name is either a vector a stick drives or an
100
105
  * action a button reports).
101
106
  */
102
- export type StickNamed<K extends string, B extends string> = K extends B
107
+ export type StickNamed<K extends string, B extends string, H extends string = K> = K extends B
103
108
  ? `${K} names both a stick and a button: give them different names`
104
- : StickZone | null
109
+ : K extends H ? StickZone | null : StickZone
105
110
 
106
111
  /** A round on-screen button of a {@link Layout}; it reports the action named like its key. */
107
112
  export interface ButtonZone {
@@ -124,8 +129,11 @@ export interface SwipeZone {
124
129
  * The touch controls, returned by the layout function {@link actions} calls
125
130
  * with the element's size. The stick and button names are fixed by the
126
131
  * first layout; a control the game hides keeps its name with a `null` zone.
132
+ * `H` names the controls whose zone may be `null`: `actions` infers it from
133
+ * the layout function, so a control it never hides has a zone that is never
134
+ * `null` in `view().layout`.
127
135
  */
128
- export interface Layout<B extends string, V extends string = never> {
136
+ export interface Layout<B extends string, V extends string = never, H extends B | V = B | V> {
129
137
  /**
130
138
  * The floating sticks, each keyed by the vector it drives (`move`, `aim`);
131
139
  * `{}` for buttons only. A finger that is not on a button goes to the
@@ -133,16 +141,24 @@ export interface Layout<B extends string, V extends string = never> {
133
141
  * so where regions overlap the earlier key wins. `null` hides a stick:
134
142
  * it takes no finger and reports a resting vector.
135
143
  */
136
- readonly sticks: { readonly [K in V]: StickNamed<K, B> }
144
+ readonly sticks: { readonly [K in V]: StickNamed<K, B, H> }
137
145
  /**
138
146
  * The buttons, each keyed by the action it reports. `null` hides a
139
147
  * button: it takes no finger and reports nothing held.
140
148
  */
141
- readonly buttons: { readonly [K in B]: ButtonZone | null }
149
+ readonly buttons: { readonly [K in B]: K extends H ? ButtonZone | null : ButtonZone }
142
150
  /** Optional: fingers here report their movement, for turning or looking around. */
143
151
  readonly swipe?: SwipeZone
144
152
  }
145
153
 
154
+ // The keys of a zone record whose value may be `null`.
155
+ type NullableKeys<Zones> = { [K in keyof Zones]-?: null extends Zones[K] ? K : never }[keyof Zones]
156
+
157
+ /** The controls a layout function can hide: the names whose zone it may return as `null`. */
158
+ export type Hideable<L> = L extends { readonly sticks: infer S; readonly buttons: infer Bs }
159
+ ? Extract<NullableKeys<S> | NullableKeys<Bs>, string>
160
+ : never
161
+
146
162
  /** The element's size in CSS pixels, passed to the layout function. */
147
163
  export interface Size {
148
164
  readonly width: number
@@ -214,8 +230,9 @@ export interface StickView {
214
230
  }
215
231
 
216
232
  /** Live control positions for drawing, in CSS pixels. Reading it consumes nothing. */
217
- export interface View<B extends string, V extends string = never> {
218
- readonly layout: Layout<B, V>
233
+ export interface View<B extends string, V extends string = never, H extends B | V = B | V> {
234
+ /** The layout in use; only the controls in `H`, the ones the layout function can hide, may be `null`. */
235
+ readonly layout: Layout<B, V, H>
219
236
  /** Each stick while a thumb holds it, `null` otherwise. */
220
237
  readonly sticks: { readonly [K in V]: StickView | null }
221
238
  readonly buttons: { readonly [K in B]: { readonly held: boolean; readonly aim: Vector | null } }
@@ -227,11 +244,11 @@ export interface View<B extends string, V extends string = never> {
227
244
  * `Controls` (through `lacking(...)` for actions with no on-screen
228
245
  * control). There is no `rebind`: the layout is the binding.
229
246
  */
230
- export interface Actions<B extends string, V extends string = never> extends System.Consumes<"snapshot"> {
247
+ export interface Actions<B extends string, V extends string = never, H extends B | V = B | V> extends System.Consumes<"snapshot"> {
231
248
  /** Returns the controls' state and starts a new press/release window. */
232
249
  snapshot(): Snapshot<B, V>
233
250
  /** The live state for drawing. */
234
- view(): View<B, V>
251
+ view(): View<B, V, H>
235
252
  /** Removes the event listeners and restores the element's `touch-action`. */
236
253
  dispose(): void
237
254
  }
@@ -376,12 +393,12 @@ interface StickTrack {
376
393
  * held controls when the page loses focus. Use `Pointer.actions` for mouse
377
394
  * and pen input.
378
395
  */
379
- export const actions = <const B extends string, const V extends string = never>(
396
+ export const actions = <const B extends string, const V extends string = never, L extends Layout<B, V> = Layout<B, V>>(
380
397
  target: TouchTarget,
381
398
  blurHost: BlurHost,
382
- layout: (size: Size) => Layout<B, V>,
399
+ layout: (size: Size) => Layout<B, V> & L,
383
400
  options: ActionsOptions = {}
384
- ): Actions<B, V> => {
401
+ ): Actions<B, V, Hideable<L>> => {
385
402
  const pointerTypes = options.pointerTypes ?? ["touch"]
386
403
  const sizeOf = (): Size => {
387
404
  const rect = target.getBoundingClientRect()
@@ -551,7 +568,8 @@ export const actions = <const B extends string, const V extends string = never>(
551
568
  },
552
569
  view() {
553
570
  return {
554
- layout: current,
571
+ // `current` is what the layout function returned, so its zones are `null` only where `Hideable<L>` says.
572
+ layout: current as unknown as Layout<B, V, Hideable<L>>,
555
573
  sticks: byName(stickNames, stickView),
556
574
  buttons: byName(names, (name) => {
557
575
  const button = buttons.get(name)!
package/src/index.ts CHANGED
@@ -1,12 +1,14 @@
1
1
  /**
2
2
  * Browser host integrations kept outside the renderer-agnostic ECS core:
3
- * animation-frame timing (`BrowserTickSource`, `BrowserHostClock`), input
3
+ * animation-frame timing (`BrowserTickSource`, `BrowserHostClock`), tab
4
+ * visibility for networked sessions (`BrowserVisibility`), input
4
5
  * devices bound to actions (`Keyboard`, `Gamepad`, `Pointer`, `Touch`),
5
6
  * merging and local multiplayer (`Controls`), and the system that copies
6
7
  * input into a resource (`InputCapture`).
7
8
  */
8
9
  export * as BrowserHostClock from "./BrowserHostClock.ts"
9
10
  export * as BrowserTickSource from "./BrowserTickSource.ts"
11
+ export * as BrowserVisibility from "./BrowserVisibility.ts"
10
12
  export * as Controls from "./Controls.ts"
11
13
  export * as Gamepad from "./Gamepad.ts"
12
14
  export * as InputCapture from "./InputCapture.ts"