@typeonce/ritmo-browser 0.15.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/src/Controls.ts CHANGED
@@ -48,6 +48,9 @@
48
48
  *
49
49
  * @example
50
50
  * ```ts
51
+ * declare const walk: (direction: Controls.Vector) => void
52
+ * declare const jump: () => void
53
+ * // ---cut---
51
54
  * const Actions = Controls.actions({ buttons: ["jump", "pause"], vectors: ["move"] })
52
55
  *
53
56
  * const keyBindings = {
@@ -70,6 +73,7 @@
70
73
  * // Only the snapshot: a replay or the fuzzer provides it in place of the devices.
71
74
  * const ControlsInput = Descriptor.Service<InputCapture.SourceOf<ReturnType<typeof makeControls>>>()("Game/Controls")
72
75
  * const Input = Descriptor.TransientResource<InputCapture.SnapshotOf<typeof ControlsInput>>()("Game/Input")
76
+ * const Game = Schema.bind(Schema.fragment({ resources: { Input } }))
73
77
  * const CaptureInput = InputCapture.system(Game, { name: "Game/CaptureInput", source: ControlsInput, resource: Input })
74
78
  *
75
79
  * const runtime = Game.Runtime.make({
@@ -80,11 +84,13 @@
80
84
  * resources: { Input: Actions.idle({ keyboard: Keyboard.idle(keyBindings), gamepad: Gamepad.idle(padBindings) }) }
81
85
  * }).value
82
86
  *
83
- * // In a system:
84
- * const input = resources.input.get()
85
- * walk(input.vectors.move) // length at most 1: keys, d-pad, or stick
86
- * if (input.actions.jump.pressed) jump()
87
- * 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
+ * })
88
94
  * ```
89
95
  */
90
96
  import type * as System from "@typeonce/ritmo/System"
@@ -694,15 +700,23 @@ type NoAnyAction<A extends string> = [A & "any"] extends [never] ? unknown : "an
694
700
  *
695
701
  * @example
696
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---
697
711
  * const Players = Controls.players(Actions, { slots: ["p1", "p2"], join: "join", leave: "back" })
698
712
  * const makePlayers = (devices: {
699
713
  * readonly left: Keyboard.Actions<typeof leftKeys>
700
714
  * readonly right: Keyboard.Actions<typeof rightKeys>
701
715
  * readonly pads: Gamepad.Pads<typeof padBindings>
702
716
  * }) => Players.pool(devices)
717
+ * const PlayersInput = Descriptor.Service<InputCapture.SourceOf<ReturnType<typeof makePlayers>>>()("Game/Players")
703
718
  *
704
719
  * // In a system:
705
- * const input = resources.input.get()
706
720
  * if (input.p2.event === "joined") spawnSecondPlayer()
707
721
  * const move = input.p2.vectors.move
708
722
  * ```
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
  * ```
@@ -38,10 +38,14 @@
38
38
  * const bindings = { left: ["ArrowLeft", "a"], right: ["ArrowRight", "d"], jump: [" "] } as const
39
39
  *
40
40
  * const KeyboardInput = Descriptor.Service<InputCapture.SourceOf<Keyboard.Actions<typeof bindings>>>()("Game/Keyboard")
41
- * const Input = Descriptor.TransientResource<Keyboard.Snapshot<typeof bindings>>()("Game/Input")
41
+ * const Input = Descriptor.TransientResource<InputCapture.SnapshotOf<typeof KeyboardInput>>()("Game/Input")
42
+ * const Game = Schema.bind(Schema.fragment({ resources: { Input } }))
42
43
  *
43
44
  * const CaptureInput = InputCapture.system(Game, { name: "Game/CaptureInput", source: KeyboardInput, resource: Input })
44
- * 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)
45
49
  *
46
50
  * const runtime = Game.Runtime.make({
47
51
  * services: Game.Runtime.services(Game.Runtime.service(KeyboardInput, Keyboard.actions(window, bindings))),
@@ -76,6 +80,10 @@ export interface Source<Value> extends System.Consumes<"snapshot"> {
76
80
  *
77
81
  * @example
78
82
  * ```ts
83
+ * const Actions = Controls.actions({ buttons: ["jump"] })
84
+ * const keys = { jump: [" "] } as const
85
+ * const pad = { jump: ["south"] } as const
86
+ * // ---cut---
79
87
  * const makeControls = (devices: { readonly keyboard: Keyboard.Actions<typeof keys>; readonly gamepad: Gamepad.Actions<typeof pad> }) =>
80
88
  * Actions.merge(devices)
81
89
  * const ControlsInput = Descriptor.Service<InputCapture.SourceOf<ReturnType<typeof makeControls>>>()("Game/Controls")
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)!