@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.
- package/CHANGELOG.md +119 -1
- package/README.md +17 -1
- package/dist/BrowserTickSource.d.ts +9 -1
- package/dist/BrowserTickSource.d.ts.map +1 -1
- package/dist/BrowserTickSource.js +9 -1
- package/dist/BrowserTickSource.js.map +1 -1
- package/dist/BrowserVisibility.d.ts +36 -0
- package/dist/BrowserVisibility.d.ts.map +1 -0
- package/dist/BrowserVisibility.js +37 -0
- package/dist/BrowserVisibility.js.map +1 -0
- package/dist/Controls.d.ts +61 -7
- package/dist/Controls.d.ts.map +1 -1
- package/dist/Controls.js +78 -2
- package/dist/Controls.js.map +1 -1
- package/dist/Gamepad.d.ts +7 -0
- package/dist/Gamepad.d.ts.map +1 -1
- package/dist/Gamepad.js +4 -0
- package/dist/Gamepad.js.map +1 -1
- package/dist/InputCapture.d.ts +35 -3
- package/dist/InputCapture.d.ts.map +1 -1
- package/dist/InputCapture.js.map +1 -1
- package/dist/Keyboard.d.ts +10 -0
- package/dist/Keyboard.d.ts.map +1 -1
- package/dist/Keyboard.js +6 -0
- package/dist/Keyboard.js.map +1 -1
- package/dist/Pointer.d.ts +14 -0
- package/dist/Pointer.d.ts.map +1 -1
- package/dist/Pointer.js +5 -0
- package/dist/Pointer.js.map +1 -1
- package/dist/Touch.d.ts +27 -9
- package/dist/Touch.d.ts.map +1 -1
- package/dist/Touch.js +1 -0
- package/dist/Touch.js.map +1 -1
- package/dist/index.d.ts +3 -1
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +3 -1
- package/dist/index.js.map +1 -1
- package/package.json +2 -2
- package/src/BrowserTickSource.ts +9 -1
- package/src/BrowserVisibility.ts +47 -0
- package/src/Controls.ts +137 -8
- package/src/Gamepad.ts +7 -0
- package/src/InputCapture.ts +36 -3
- package/src/Keyboard.ts +10 -0
- package/src/Pointer.ts +14 -0
- package/src/Touch.ts +31 -13
- 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
|
-
*
|
|
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
|
-
* //
|
|
76
|
-
* const
|
|
77
|
-
*
|
|
78
|
-
*
|
|
79
|
-
*
|
|
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
|
* ```
|
package/src/InputCapture.ts
CHANGED
|
@@ -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
|
|
36
|
-
* const Input = Descriptor.TransientResource<
|
|
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
|
|
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
|
-
|
|
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
|
|
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`),
|
|
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"
|