zx-kit 0.19.1 → 0.21.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/README.md CHANGED
@@ -536,7 +536,7 @@ requestAnimationFrame(loop)
536
536
  | [`ay.ts`](#ayts--ay-3-8912-melodik-audio) | AY chip emulator: 3-channel tone, LFSR noise, 16 envelope shapes |
537
537
  | [`renderer.ts`](#rendererts--canvas-renderer) | Canvas setup, sprites, text, scanlines, border flash |
538
538
  | [`audio.ts`](#audiots--beeper-audio) | 1-bit beeper: square-wave notes, patterns, volume control |
539
- | [`ui.ts`](#uits--ui-widgets) | Progress bars, boxes, frames, panel titles |
539
+ | [`ui.ts`](#uits--ui-widgets) | Boxes, frames, panel titles, progress bars + instrumentation widgets (dotted grids, segmented bars, fluid tanks, dials, text compass) |
540
540
  | [`input.ts`](#inputts--keyboard-input) | Movement with key-repeat, action flags, state reset |
541
541
  | [`sprite.ts`](#spritets--free-roaming-sprites) | Sprites: position, velocity, gravity, flip, render |
542
542
  | [`collision.ts`](#collisionts--aabb-collision) | AABB overlap tests, tile-map wall resolution |
@@ -550,10 +550,77 @@ requestAnimationFrame(loop)
550
550
 
551
551
  ---
552
552
 
553
+ ## Audio architecture — beeper vs AY
554
+
555
+ zx-kit ships two independent audio modules — [`audio.ts`](#audiots--beeper-audio) (the **beeper**) and [`ay.ts`](#ayts--ay-3-8912-melodik-audio) (the **AY chip**). They are **not alternatives** — most ZX Spectrum 128K games used both at once, and so should yours.
556
+
557
+ ### The history (so the choice makes sense)
558
+
559
+ | Hardware | Beeper (1-bit) | AY-3-8912 (3 ch) |
560
+ |----------|:--:|:--:|
561
+ | Spectrum 48K | ✅ built-in | ❌ |
562
+ | Spectrum 128K / +2 / +3 | ✅ built-in | ✅ built-in |
563
+ | Melodik add-on (for 48K) | — | ✅ |
564
+
565
+ - **48K games** (Manic Miner, Jet Set Willy, Atic Atac) had only the beeper — every blip, jump, footstep and title jingle was a square wave forced out of the 1-bit speaker by tight CPU loops.
566
+ - **128K games** (Robocop, R-Type, Chase H.Q., Lord of the Rings) used the AY for **music** — proper 3-channel tunes with envelope shaping — while the beeper kept doing **sound effects** in parallel. AY hummed an orchestral score; the beeper still went *pew pew*.
567
+
568
+ ### When to use which
569
+
570
+ | Want to play… | Module | Function | Why |
571
+ |---|---|---|---|
572
+ | Short SFX (shot, jump, hit, beep) | `audio.ts` | `beep(freq, dur, t)` | Single square wave, punchy, era-correct for SFX |
573
+ | A 3-channel jingle / chord | `ay.ts` | `playAY({ a, b, c })` | Needs ≥2 simultaneous voices |
574
+ | Game-over fanfare / level music | `ay.ts` | `playAY(...)` | Envelope shaping + multiple voices |
575
+ | Single-voice melody | `audio.ts` | `playPattern(notes)` | Lighter setup, no AY init needed |
576
+ | Live, dynamically-changing tone (siren, engine) | `ay.ts` | `createAY()` then `tone()` | Persistent oscillator handle |
577
+ | Title-screen music | `ay.ts` | `playAY(...)` | Authentic 128K title-music feel |
578
+
579
+ **Rule of thumb:** if it needs to be *heard at the same time as something else*, you almost certainly want AY for at least one of the two.
580
+
581
+ ### Authentic parallel pattern — the "Robocop" pattern
582
+
583
+ This is how 128K games actually sounded:
584
+
585
+ ```ts
586
+ import { initAudio, beep, getAudioContext, resumeAudio } from 'zx-kit' // beeper
587
+ import { playAY } from 'zx-kit' // AY
588
+
589
+ // One-time setup (must be inside a user gesture — click, keydown — due to browser autoplay policy)
590
+ window.addEventListener('keydown', () => { initAudio(); resumeAudio() }, { once: true })
591
+
592
+ // Title screen: AY plays a multi-voice melody...
593
+ playAY({
594
+ a: [{ freq: 523, dur: 200 }, { freq: 659, dur: 200 }, { freq: 784, dur: 400, envShape: 12, envCycleDurMs: 200 }],
595
+ b: [{ freq: 262, dur: 200 }, { freq: 330, dur: 200 }, { freq: 392, dur: 400 }],
596
+ })
597
+
598
+ // ...meanwhile in the game loop, beeper does the SFX:
599
+ function onPlayerShoots() {
600
+ const audio = getAudioContext()
601
+ if (audio) beep(1200, 40, audio.currentTime) // sharp pew
602
+ }
603
+ function onPlayerHit() {
604
+ const audio = getAudioContext()
605
+ if (audio) beep(120, 200, audio.currentTime) // low thump
606
+ }
607
+ ```
608
+
609
+ Both modules route through the **same master `GainNode`**, so `setMasterVolume(v)` controls both at once. They share state cleanly — no audio bus conflicts.
610
+
611
+ ### Notes on accuracy
612
+
613
+ - **Beeper** (`audio.ts`) is a faithful 1-bit-style square wave via Web Audio's `OscillatorNode`. Era-correct for SFX use.
614
+ - **AY** (`ay.ts`) is a *good approximation* of the AY-3-8912 — hardware-accurate logarithmic amplitudes (16 levels, ≈ √2 ratio), all 16 envelope shapes, proper LFSR noise. **Not sample-accurate**: Web Audio's `OscillatorNode` is band-limited (no aliasing artefacts), real AY's raw squares have a buzzier, fuzzier character; envelopes are smooth ramps here vs the chip's 16-step ramps. For chip-tune purists wanting bit-exact AY emulation, a future AudioWorklet-based backend is on the roadmap. For game sound and most music, the current implementation is more than convincing.
615
+
616
+ ---
617
+
553
618
  ## `ay.ts` — AY-3-8912 Melodik Audio
554
619
 
555
620
  The AY-3-8912 chip (sold as the *Melodik* add-on for ZX Spectrum 48K, built into the 128K) gave the Spectrum three independent square-wave channels, a shared LFSR noise generator, and a hardware envelope generator with 16 distinct shapes. This module emulates all of it via the Web Audio API with hardware-accurate logarithmic amplitude values.
556
621
 
622
+ > **Pair with [`audio.ts`](#audiots--beeper-audio) (the beeper) for sound effects.** Use AY for music, beeper for SFX — see [Audio architecture — beeper vs AY](#audio-architecture--beeper-vs-ay) for the historical context and the parallel-use pattern. Both modules share the same master gain, so `setMasterVolume()` controls them together.
623
+
557
624
  Two usage modes:
558
625
 
559
626
  | Mode | Function | Use case |
@@ -839,9 +906,11 @@ curveDisplay(ctx, 256, 208, 6) // stronger warp
839
906
 
840
907
  ## `audio.ts` — Beeper Audio
841
908
 
842
- Single-channel 1-bit square-wave audio, faithful to the ZX Spectrum beeper. Use this for simple SFX and monophonic melodies. For music with harmony, noise, and envelopes, use `ay.ts`.
909
+ Single-channel 1-bit square-wave audio, faithful to the ZX Spectrum beeper. Use this for **sound effects** (shots, jumps, hits, beeps) and simple monophonic melodies.
843
910
 
844
- All audio routes through a shared `AudioContext` and master `GainNode`. **`initAudio()` must be called inside a user-gesture handler** due to browser autoplay policy.
911
+ > **Pair with [`ay.ts`](#ayts--ay-3-8912-melodik-audio) for music.** This is how 128K Spectrum games actually sounded see [Audio architecture — beeper vs AY](#audio-architecture--beeper-vs-ay) for the reasoning and the "Robocop" parallel-use pattern.
912
+
913
+ All audio routes through a shared `AudioContext` and master `GainNode` — `setMasterVolume()` controls both modules at once. **`initAudio()` must be called inside a user-gesture handler** due to browser autoplay policy.
845
914
 
846
915
  ### `initAudio(volume?): void`
847
916
 
@@ -993,6 +1062,176 @@ drawPanelTitle(ctx, {
993
1062
  })
994
1063
  ```
995
1064
 
1065
+ ### Instrumentation widgets (stateless)
1066
+
1067
+ Five stateless primitives for HUDs, dashboards and tactical displays — gauges, bars, tanks, dials, compass. Each function takes a `ctx` plus an `options` object and renders immediately. The caller drives state on every frame (no built-in animation, no internal timers). Pair with `Animation` / `Tween` from `animation.ts` if you want smoothed transitions.
1068
+
1069
+ #### `drawDottedGrid(ctx, options): void`
1070
+
1071
+ Regularly-spaced dot pattern. Useful for radar / sonar screens, tactical scanner overlays, debug grids, stippled backgrounds, alien-invasion detection grids.
1072
+
1073
+ ```ts
1074
+ // Sonar background (submarine HUD)
1075
+ drawDottedGrid(ctx, {
1076
+ x: 8, y: 8, width: 64, height: 48,
1077
+ spacing: 4, color: C.GREEN, paper: C.BLACK,
1078
+ })
1079
+
1080
+ // Chunky 2×2 dots for tactical map overlay
1081
+ drawDottedGrid(ctx, {
1082
+ x: 0, y: 0, width: 256, height: 192,
1083
+ spacing: 8, dotSize: 2, color: C.B_WHITE,
1084
+ })
1085
+ ```
1086
+
1087
+ | Option | Type | Default | Description |
1088
+ |--------|------|---------|-------------|
1089
+ | `x`, `y`, `width`, `height` | `number` | — | Area covered by the dot field |
1090
+ | `spacing` | `number` | — | Distance between adjacent dot centres |
1091
+ | `color` | `SpectrumColor` | — | Dot colour |
1092
+ | `paper` | `SpectrumColor` | — | Optional background fill |
1093
+ | `dotSize` | `number` | `1` | Dot size in pixels (use `2` for chunkier dots) |
1094
+
1095
+ #### `drawSegmentedBar(ctx, options): void`
1096
+
1097
+ Discrete segmented bar — health, ammo, shield, fuel, stamina, mana, battery, damage. Computes `round(value/max * segments)` filled segments.
1098
+
1099
+ Two colouring strategies, mutually exclusive:
1100
+
1101
+ - **Single colour** (`color`): every filled segment uses it. Classic Robocop health style.
1102
+ - **Threshold gradient** (`colors: [low, mid, high]`): the widget picks one of three colours based on `value/max` (`< 1/3` → low, `< 2/3` → mid, else high). Classic oxygen / damage indicator.
1103
+
1104
+ ```ts
1105
+ // Robocop-style health (single colour)
1106
+ drawSegmentedBar(ctx, {
1107
+ x: 0, y: 0, segments: 10, value: 7, max: 10,
1108
+ color: C.B_GREEN, paper: C.BLACK,
1109
+ })
1110
+
1111
+ // Oxygen with threshold gradient (red → yellow → green)
1112
+ drawSegmentedBar(ctx, {
1113
+ x: 0, y: 0, segments: 10, value: 8, max: 10,
1114
+ colors: [C.B_RED, C.B_YELLOW, C.B_GREEN],
1115
+ paper: C.BLACK,
1116
+ })
1117
+
1118
+ // Vertical bar (e.g. ammo column on the side of the HUD)
1119
+ drawSegmentedBar(ctx, {
1120
+ x: 0, y: 0, segments: 8, value: 5, max: 8,
1121
+ orientation: 'vertical', color: C.B_GREEN,
1122
+ })
1123
+ ```
1124
+
1125
+ | Option | Type | Default | Description |
1126
+ |--------|------|---------|-------------|
1127
+ | `x`, `y` | `number` | — | Top-left corner |
1128
+ | `segments` | `number` | — | Total segment count |
1129
+ | `value`, `max` | `number` | — | Filled = `round(value/max * segments)` |
1130
+ | `segmentWidth` | `number` | `8` (CELL) | Width of one segment |
1131
+ | `segmentHeight` | `number` | `8` (CELL) | Height of one segment |
1132
+ | `gap` | `number` | `1` | Pixels between adjacent segments |
1133
+ | `color` | `SpectrumColor` | — | Single fill colour (mutually exclusive with `colors`) |
1134
+ | `colors` | `[low, mid, high]` | — | Three-stop threshold gradient |
1135
+ | `paper` | `SpectrumColor` | — | Background for empty segments |
1136
+ | `orientation` | `'horizontal' \| 'vertical'` | `'horizontal'` | Layout direction |
1137
+
1138
+ #### `drawTank(ctx, options): void`
1139
+
1140
+ Fluid container — ballast tanks, fuel gauges, water reservoirs, lava levels, oil drums, chemical canisters. Liquid fills from the bottom up.
1141
+
1142
+ ```ts
1143
+ // Submarine ballast tank (pill, cyan fluid)
1144
+ drawTank(ctx, {
1145
+ x: 8, y: 16, width: 16, height: 48,
1146
+ fillPct: 0.66, shape: 'pill',
1147
+ liquidColor: C.B_CYAN,
1148
+ containerColor: C.WHITE,
1149
+ emptyColor: C.BLACK,
1150
+ })
1151
+
1152
+ // Generic fuel gauge (rect, yellow fluid)
1153
+ drawTank(ctx, {
1154
+ x: 200, y: 8, width: 24, height: 32,
1155
+ fillPct: 0.4, shape: 'rect',
1156
+ liquidColor: C.B_YELLOW,
1157
+ containerColor: C.WHITE,
1158
+ emptyColor: C.BLACK,
1159
+ })
1160
+ ```
1161
+
1162
+ | Option | Type | Default | Description |
1163
+ |--------|------|---------|-------------|
1164
+ | `x`, `y`, `width`, `height` | `number` | — | Container bounding box |
1165
+ | `fillPct` | `number` | — | Fill level `0..1`, clamped |
1166
+ | `shape` | `'pill' \| 'rect'` | `'pill'` | `'pill'` = rounded caps, `'rect'` = sharp corners |
1167
+ | `liquidColor` | `SpectrumColor` | — | Fluid colour |
1168
+ | `containerColor` | `SpectrumColor` | `liquidColor` | Outline colour |
1169
+ | `emptyColor` | `SpectrumColor \| 'transparent'` | `C.BLACK` | Fill for the empty portion. Use `'transparent'` to leave it un-painted (so the underlying frame shows through) |
1170
+
1171
+ #### `drawDial(ctx, options): void`
1172
+
1173
+ Circular analog gauge with movable needle — RPM, speedometer, fuel, temperature, volume knob. Decorations (face fill, rim outline, tick marks) are optional; the needle alone is the minimum visible output.
1174
+
1175
+ ```ts
1176
+ // Submarine motor RPM gauge (range 0–3000)
1177
+ drawDial(ctx, {
1178
+ cx: 128, cy: 100, radius: 24,
1179
+ value: 1500, min: 0, max: 3000,
1180
+ needleColor: C.B_RED,
1181
+ rimColor: C.WHITE,
1182
+ tickColor: C.WHITE,
1183
+ ticks: 7,
1184
+ })
1185
+
1186
+ // Bare minimum: just the needle
1187
+ drawDial(ctx, {
1188
+ cx: 50, cy: 50, radius: 10,
1189
+ value: 75, needleColor: C.B_GREEN,
1190
+ })
1191
+ ```
1192
+
1193
+ | Option | Type | Default | Description |
1194
+ |--------|------|---------|-------------|
1195
+ | `cx`, `cy`, `radius` | `number` | — | Centre and radius |
1196
+ | `value` | `number` | — | Mapped to needle angle |
1197
+ | `min` | `number` | `0` | Minimum value |
1198
+ | `max` | `number` | `100` | Maximum value |
1199
+ | `startAngle` | `number` (rad) | `3π/4` | Needle angle at `min` (bottom-left default) |
1200
+ | `endAngle` | `number` (rad) | `9π/4` | Needle angle at `max` (bottom-right, after sweeping CW through top) |
1201
+ | `needleColor` | `SpectrumColor` | — | Needle colour |
1202
+ | `faceColor` | `SpectrumColor` | — | Optional filled disc background |
1203
+ | `rimColor` | `SpectrumColor` | — | Optional circle outline |
1204
+ | `tickColor` | `SpectrumColor` | — | Optional tick mark colour (requires `ticks`) |
1205
+ | `ticks` | `number` | `0` | Number of evenly-spaced tick marks |
1206
+
1207
+ Angles use canvas convention: `0` = right, `π/2` = down, `π` = left, `3π/2` = up — angles increase **clockwise** because the canvas y-axis points down. Default sweep covers the typical 270° gauge arc through the top.
1208
+
1209
+ #### `drawCompassText(ctx, options): void`
1210
+
1211
+ Text-based heading indicator in the classic 80s tactical-display style `[W [NW] N [NE] E]` — current direction in the centre, highlighted, with two neighbouring directions on each side. Heading rounds to the nearest 45° step.
1212
+
1213
+ ```ts
1214
+ drawCompassText(ctx, {
1215
+ x: 0, y: 168,
1216
+ heading: 0, // N
1217
+ color: C.WHITE,
1218
+ highlightColor: C.B_YELLOW,
1219
+ paper: C.BLACK,
1220
+ })
1221
+ // heading=0 → centre is N. Five labels: W, NW, N, NE, E
1222
+ // → `W [NW] N [NE] E` — centre "N" in bright yellow, ±1 in brackets,
1223
+ // outer ±2 ("W", "E") rendered plain.
1224
+ ```
1225
+
1226
+ | Option | Type | Default | Description |
1227
+ |--------|------|---------|-------------|
1228
+ | `x`, `y` | `number` | — | Top-left of the rendered string |
1229
+ | `heading` | `number` (degrees) | — | `0`/`360` = N, `90` = E, `180` = S, `270` = W (wraps automatically) |
1230
+ | `color` | `SpectrumColor` | — | Colour for non-current direction labels |
1231
+ | `highlightColor` | `SpectrumColor` | `color` | Colour for current direction (centre label) |
1232
+ | `paper` | `SpectrumColor` | — | Optional background behind labels |
1233
+ | `brackets` | `boolean` | `true` | Wrap **only the ±1 (adjacent) directions** in `[…]`. The centre label and the outer ±2 directions are never bracketed. |
1234
+
996
1235
  ### Stateful widget — Progress Bar
997
1236
 
998
1237
  The progress bar is a **managed widget**: after a `drawProgressBar` call, the bar is automatically re-rendered on subsequent frames by `renderUI` until `visibilityLength` milliseconds have elapsed. Calling `drawProgressBar` again resets the timer.
package/dist/audio.d.ts CHANGED
@@ -1,3 +1,22 @@
1
+ /**
2
+ * @module audio
3
+ *
4
+ * **The beeper** — single-channel, 1-bit-style square-wave audio, faithful to
5
+ * the ZX Spectrum 48K speaker. Use this module for **sound effects** (jumps,
6
+ * shots, hits, beeps) and simple monophonic melodies.
7
+ *
8
+ * For **music** (multi-voice harmony, envelope shaping, noise mixing), use
9
+ * the companion {@link "ay" | ay.ts} module — the AY-3-8912 chip that 128K
10
+ * Spectrum games used alongside the beeper. Both modules share the same
11
+ * `AudioContext` and master `GainNode`, so:
12
+ *
13
+ * - `setMasterVolume()` controls both at once
14
+ * - `initAudio()` initialises both (call once, inside a user-gesture handler)
15
+ * - You can run AY music and beeper SFX in parallel — that's the authentic
16
+ * 128K pattern (Robocop, R-Type, Chase H.Q.…)
17
+ *
18
+ * @see {@link createAY} and {@link playAY} for multi-channel music in `ay.ts`
19
+ */
1
20
  /**
2
21
  * Creates the shared `AudioContext` and master `GainNode`. Idempotent — safe to call
3
22
  * multiple times (subsequent calls are no-ops).
@@ -95,10 +114,16 @@ export interface Note {
95
114
  */
96
115
  export declare function playPattern(notes: Note[], startDelay?: number): void;
97
116
  /**
98
- * Schedules a single square-wave beep on the shared `AudioContext`.
99
- * Uses a 5ms linear ramp attack and release to avoid click artefacts.
117
+ * Schedules a single square-wave beep on the shared `AudioContext` — the
118
+ * canonical Spectrum **sound effect**: short, monophonic, era-correct.
119
+ *
120
+ * Uses a 5 ms linear ramp attack and release to avoid click artefacts.
100
121
  * Routed through the master gain node.
101
- * Prefer `playPattern` for sequences — use `beep` when you need precise timing control.
122
+ *
123
+ * **When to reach for `beep`:** SFX (shots, jumps, hits, pickup blips).
124
+ * **For sequences,** use `playPattern`. **For multi-voice music,** use
125
+ * `playAY` from `ay.js` — the two modules are designed to run in parallel
126
+ * (AY music + beeper SFX = the authentic 128K Spectrum sound).
102
127
  *
103
128
  * @param freq - Frequency in Hz
104
129
  * @param durationMs - Duration in milliseconds
@@ -1 +1 @@
1
- {"version":3,"file":"audio.d.ts","sourceRoot":"","sources":["../src/audio.ts"],"names":[],"mappings":"AASA;;;;;;;;;GASG;AACH,wBAAgB,SAAS,CAAC,MAAM,SAAM,GAAG,IAAI,CAM5C;AAED;;;;;;;GAOG;AACH,wBAAgB,WAAW,IAAI,IAAI,CAElC;AAED;;;;;;;GAOG;AACH,wBAAgB,eAAe,IAAI,YAAY,GAAG,IAAI,CAErD;AAED;;;;;;;GAOG;AACH,wBAAgB,aAAa,IAAI,QAAQ,GAAG,IAAI,CAE/C;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,IAAI,MAAM,CAExC;AAED;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAGpD;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,IAAI,IAAI,CAErC;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,IAAI,IAAI,CAErC;AAED,6EAA6E;AAC7E,MAAM,WAAW,IAAI;IACnB,IAAI,EAAE,MAAM,CAAA;IACZ,GAAG,EAAE,MAAM,CAAA;CACZ;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,IAAI,EAAE,EAAE,UAAU,SAAI,GAAG,IAAI,CAS/D;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,IAAI,CAc9E"}
1
+ {"version":3,"file":"audio.d.ts","sourceRoot":"","sources":["../src/audio.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAWH;;;;;;;;;GASG;AACH,wBAAgB,SAAS,CAAC,MAAM,SAAM,GAAG,IAAI,CAM5C;AAED;;;;;;;GAOG;AACH,wBAAgB,WAAW,IAAI,IAAI,CAElC;AAED;;;;;;;GAOG;AACH,wBAAgB,eAAe,IAAI,YAAY,GAAG,IAAI,CAErD;AAED;;;;;;;GAOG;AACH,wBAAgB,aAAa,IAAI,QAAQ,GAAG,IAAI,CAE/C;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,IAAI,MAAM,CAExC;AAED;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAGpD;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,IAAI,IAAI,CAErC;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,IAAI,IAAI,CAErC;AAED,6EAA6E;AAC7E,MAAM,WAAW,IAAI;IACnB,IAAI,EAAE,MAAM,CAAA;IACZ,GAAG,EAAE,MAAM,CAAA;CACZ;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,IAAI,EAAE,EAAE,UAAU,SAAI,GAAG,IAAI,CAS/D;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,IAAI,CAc9E"}
package/dist/audio.js CHANGED
@@ -1,3 +1,22 @@
1
+ /**
2
+ * @module audio
3
+ *
4
+ * **The beeper** — single-channel, 1-bit-style square-wave audio, faithful to
5
+ * the ZX Spectrum 48K speaker. Use this module for **sound effects** (jumps,
6
+ * shots, hits, beeps) and simple monophonic melodies.
7
+ *
8
+ * For **music** (multi-voice harmony, envelope shaping, noise mixing), use
9
+ * the companion {@link "ay" | ay.ts} module — the AY-3-8912 chip that 128K
10
+ * Spectrum games used alongside the beeper. Both modules share the same
11
+ * `AudioContext` and master `GainNode`, so:
12
+ *
13
+ * - `setMasterVolume()` controls both at once
14
+ * - `initAudio()` initialises both (call once, inside a user-gesture handler)
15
+ * - You can run AY music and beeper SFX in parallel — that's the authentic
16
+ * 128K pattern (Robocop, R-Type, Chase H.Q.…)
17
+ *
18
+ * @see {@link createAY} and {@link playAY} for multi-channel music in `ay.ts`
19
+ */
1
20
  let ctx = null;
2
21
  let masterGain = null;
3
22
  const VOLUME_STEP = 0.1;
@@ -131,10 +150,16 @@ export function playPattern(notes, startDelay = 0) {
131
150
  }
132
151
  }
133
152
  /**
134
- * Schedules a single square-wave beep on the shared `AudioContext`.
135
- * Uses a 5ms linear ramp attack and release to avoid click artefacts.
153
+ * Schedules a single square-wave beep on the shared `AudioContext` — the
154
+ * canonical Spectrum **sound effect**: short, monophonic, era-correct.
155
+ *
156
+ * Uses a 5 ms linear ramp attack and release to avoid click artefacts.
136
157
  * Routed through the master gain node.
137
- * Prefer `playPattern` for sequences — use `beep` when you need precise timing control.
158
+ *
159
+ * **When to reach for `beep`:** SFX (shots, jumps, hits, pickup blips).
160
+ * **For sequences,** use `playPattern`. **For multi-voice music,** use
161
+ * `playAY` from `ay.js` — the two modules are designed to run in parallel
162
+ * (AY music + beeper SFX = the authentic 128K Spectrum sound).
138
163
  *
139
164
  * @param freq - Frequency in Hz
140
165
  * @param durationMs - Duration in milliseconds
package/dist/audio.js.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"audio.js","sourceRoot":"","sources":["../src/audio.ts"],"names":[],"mappings":"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"}
1
+ {"version":3,"file":"audio.js","sourceRoot":"","sources":["../src/audio.ts"],"names":[],"mappings":"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"}
package/dist/ay.d.ts CHANGED
@@ -1,3 +1,33 @@
1
+ /**
2
+ * @module ay
3
+ *
4
+ * **AY-3-8912 chip emulator** — three independent square-wave channels, shared
5
+ * LFSR noise generator, 16-shape hardware envelope generator. This is the chip
6
+ * built into the ZX Spectrum 128K / +2 / +3 (and sold as the *Melodik* add-on
7
+ * for the 48K) — the source of every 3-voice tune you remember from Robocop,
8
+ * R-Type, Chase H.Q. and a thousand other 128K games.
9
+ *
10
+ * Use this module for **music** — title screens, in-game soundtracks,
11
+ * multi-voice jingles, chord-based fanfares. For **sound effects** (single
12
+ * blips, jumps, shots), pair this with the companion {@link "audio" | audio.ts}
13
+ * module (the 1-bit beeper). That's the authentic 128K pattern: AY hums the
14
+ * orchestral score, beeper still goes *pew pew*.
15
+ *
16
+ * Both modules share the same `AudioContext` and master `GainNode`:
17
+ *
18
+ * - `setMasterVolume()` (from audio.ts) controls AY and beeper together
19
+ * - `initAudio()` initialises both — call once inside a user gesture
20
+ * - Run AY music and beeper SFX in parallel without bus conflicts
21
+ *
22
+ * Accuracy notes: this is a *good approximation*, not a sample-accurate
23
+ * AY emulator. Hardware-accurate logarithmic amplitudes (16 levels, ≈ √2
24
+ * ratio) and all 16 envelope shapes are correct. Web Audio's `OscillatorNode`
25
+ * is band-limited (no aliasing artefacts), so the sound is slightly cleaner
26
+ * than the real chip's raw squares. A sample-accurate AudioWorklet backend
27
+ * is on the roadmap.
28
+ *
29
+ * @see {@link beep} and {@link playPattern} for single-voice SFX in `audio.ts`
30
+ */
1
31
  /** ZX Spectrum 128K / Melodik AY-3-8912 master clock. */
2
32
  export declare const AY_CLOCK = 1773400;
3
33
  /**
@@ -68,12 +98,21 @@ export declare const AY_ENVELOPE_SHAPES: readonly ["\\_ ", "\\_ ", "\\_ ", "\\_
68
98
  */
69
99
  export declare function createAY(): AYChip;
70
100
  /**
71
- * Pre-schedules up to three independent AY note arrays on the shared AudioContext.
72
- * All channels start at the same wall-clock time; shorter channels finish earlier.
73
- * Fire-and-forget no handle returned.
101
+ * Pre-schedules up to three independent AY note arrays on the shared
102
+ * `AudioContext` the canonical Spectrum 128K **music** primitive:
103
+ * 3-voice harmony, envelope shaping, noise mixing, all in one call.
104
+ *
105
+ * All channels start at the same wall-clock time; shorter channels finish
106
+ * earlier. Fire-and-forget — no handle returned.
74
107
  *
75
108
  * Each `AYNote` may optionally mix in LFSR noise and/or apply an envelope shape.
76
109
  *
110
+ * **When to reach for `playAY`:** title screen music, level themes,
111
+ * game-over fanfares, multi-voice jingles. **For sound effects** (single
112
+ * blips, jumps, hits), use `beep` from `audio.js` in parallel — the two
113
+ * modules share the master gain and were designed to run together
114
+ * (the authentic 128K pattern: AY music + beeper SFX).
115
+ *
77
116
  * @example
78
117
  * playAY({
79
118
  * a: [{ freq: 440, dur: 300 }, { freq: 523, dur: 300, envShape: 12, envCycleDurMs: 150 }],
package/dist/ay.d.ts.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"ay.d.ts","sourceRoot":"","sources":["../src/ay.ts"],"names":[],"mappings":"AAIA,yDAAyD;AACzD,eAAO,MAAM,QAAQ,UAAY,CAAA;AAEjC;;;;GAIG;AACH,eAAO,MAAM,MAAM,EAAE,SAAS,MAAM,EAGnC,CAAA;AAWD,MAAM,MAAM,SAAS,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,CAAA;AAEvC,2CAA2C;AAC3C,MAAM,WAAW,MAAM;IACrB,2CAA2C;IAC3C,IAAI,EAAE,MAAM,CAAA;IACZ,gCAAgC;IAChC,GAAG,EAAE,MAAM,CAAA;IACX,kEAAkE;IAClE,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ,wDAAwD;IACxD,KAAK,CAAC,EAAE,OAAO,CAAA;IACf,0EAA0E;IAC1E,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,2DAA2D;IAC3D,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,uFAAuF;IACvF,aAAa,CAAC,EAAE,MAAM,CAAA;CACvB;AAED,yDAAyD;AACzD,MAAM,WAAW,MAAM;IACrB,kFAAkF;IAClF,IAAI,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IACrD,kFAAkF;IAClF,WAAW,CAAC,EAAE,EAAE,SAAS,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IACjD,kCAAkC;IAClC,YAAY,CAAC,EAAE,EAAE,SAAS,GAAG,IAAI,CAAA;IACjC;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,EAAE,SAAS,EAAE,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,IAAI,CAAA;IAChE,yCAAyC;IACzC,IAAI,CAAC,EAAE,EAAE,SAAS,GAAG,IAAI,CAAA;IACzB,mCAAmC;IACnC,OAAO,IAAI,IAAI,CAAA;IACf,kEAAkE;IAClE,IAAI,IAAI,IAAI,CAAA;CACb;AAED;;;GAGG;AACH,eAAO,MAAM,kBAAkB,mIAWrB,CAAA;AAwFV;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,QAAQ,IAAI,MAAM,CA6GjC;AAID;;;;;;;;;;;;;GAaG;AACH,wBAAgB,MAAM,CACpB,OAAO,EAAE;IAAE,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC;IAAC,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC;IAAC,CAAC,CAAC,EAAE,MAAM,EAAE,CAAA;CAAE,EACrD,UAAU,SAAI,GACb,IAAI,CA+EN"}
1
+ {"version":3,"file":"ay.d.ts","sourceRoot":"","sources":["../src/ay.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAMH,yDAAyD;AACzD,eAAO,MAAM,QAAQ,UAAY,CAAA;AAEjC;;;;GAIG;AACH,eAAO,MAAM,MAAM,EAAE,SAAS,MAAM,EAGnC,CAAA;AAWD,MAAM,MAAM,SAAS,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,CAAA;AAEvC,2CAA2C;AAC3C,MAAM,WAAW,MAAM;IACrB,2CAA2C;IAC3C,IAAI,EAAE,MAAM,CAAA;IACZ,gCAAgC;IAChC,GAAG,EAAE,MAAM,CAAA;IACX,kEAAkE;IAClE,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ,wDAAwD;IACxD,KAAK,CAAC,EAAE,OAAO,CAAA;IACf,0EAA0E;IAC1E,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,2DAA2D;IAC3D,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,uFAAuF;IACvF,aAAa,CAAC,EAAE,MAAM,CAAA;CACvB;AAED,yDAAyD;AACzD,MAAM,WAAW,MAAM;IACrB,kFAAkF;IAClF,IAAI,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IACrD,kFAAkF;IAClF,WAAW,CAAC,EAAE,EAAE,SAAS,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IACjD,kCAAkC;IAClC,YAAY,CAAC,EAAE,EAAE,SAAS,GAAG,IAAI,CAAA;IACjC;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,EAAE,SAAS,EAAE,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,IAAI,CAAA;IAChE,yCAAyC;IACzC,IAAI,CAAC,EAAE,EAAE,SAAS,GAAG,IAAI,CAAA;IACzB,mCAAmC;IACnC,OAAO,IAAI,IAAI,CAAA;IACf,kEAAkE;IAClE,IAAI,IAAI,IAAI,CAAA;CACb;AAED;;;GAGG;AACH,eAAO,MAAM,kBAAkB,mIAWrB,CAAA;AAwFV;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,QAAQ,IAAI,MAAM,CA6GjC;AAID;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,MAAM,CACpB,OAAO,EAAE;IAAE,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC;IAAC,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC;IAAC,CAAC,CAAC,EAAE,MAAM,EAAE,CAAA;CAAE,EACrD,UAAU,SAAI,GACb,IAAI,CA+EN"}
package/dist/ay.js CHANGED
@@ -1,3 +1,33 @@
1
+ /**
2
+ * @module ay
3
+ *
4
+ * **AY-3-8912 chip emulator** — three independent square-wave channels, shared
5
+ * LFSR noise generator, 16-shape hardware envelope generator. This is the chip
6
+ * built into the ZX Spectrum 128K / +2 / +3 (and sold as the *Melodik* add-on
7
+ * for the 48K) — the source of every 3-voice tune you remember from Robocop,
8
+ * R-Type, Chase H.Q. and a thousand other 128K games.
9
+ *
10
+ * Use this module for **music** — title screens, in-game soundtracks,
11
+ * multi-voice jingles, chord-based fanfares. For **sound effects** (single
12
+ * blips, jumps, shots), pair this with the companion {@link "audio" | audio.ts}
13
+ * module (the 1-bit beeper). That's the authentic 128K pattern: AY hums the
14
+ * orchestral score, beeper still goes *pew pew*.
15
+ *
16
+ * Both modules share the same `AudioContext` and master `GainNode`:
17
+ *
18
+ * - `setMasterVolume()` (from audio.ts) controls AY and beeper together
19
+ * - `initAudio()` initialises both — call once inside a user gesture
20
+ * - Run AY music and beeper SFX in parallel without bus conflicts
21
+ *
22
+ * Accuracy notes: this is a *good approximation*, not a sample-accurate
23
+ * AY emulator. Hardware-accurate logarithmic amplitudes (16 levels, ≈ √2
24
+ * ratio) and all 16 envelope shapes are correct. Web Audio's `OscillatorNode`
25
+ * is band-limited (no aliasing artefacts), so the sound is slightly cleaner
26
+ * than the real chip's raw squares. A sample-accurate AudioWorklet backend
27
+ * is on the roadmap.
28
+ *
29
+ * @see {@link beep} and {@link playPattern} for single-voice SFX in `audio.ts`
30
+ */
1
31
  import { initAudio, getMasterGain } from './audio.js';
2
32
  // ─── Hardware constants ────────────────────────────────────────────────────────
3
33
  /** ZX Spectrum 128K / Melodik AY-3-8912 master clock. */
@@ -210,12 +240,21 @@ export function createAY() {
210
240
  }
211
241
  // ─── Sequencer ────────────────────────────────────────────────────────────────
212
242
  /**
213
- * Pre-schedules up to three independent AY note arrays on the shared AudioContext.
214
- * All channels start at the same wall-clock time; shorter channels finish earlier.
215
- * Fire-and-forget no handle returned.
243
+ * Pre-schedules up to three independent AY note arrays on the shared
244
+ * `AudioContext` the canonical Spectrum 128K **music** primitive:
245
+ * 3-voice harmony, envelope shaping, noise mixing, all in one call.
246
+ *
247
+ * All channels start at the same wall-clock time; shorter channels finish
248
+ * earlier. Fire-and-forget — no handle returned.
216
249
  *
217
250
  * Each `AYNote` may optionally mix in LFSR noise and/or apply an envelope shape.
218
251
  *
252
+ * **When to reach for `playAY`:** title screen music, level themes,
253
+ * game-over fanfares, multi-voice jingles. **For sound effects** (single
254
+ * blips, jumps, hits), use `beep` from `audio.js` in parallel — the two
255
+ * modules share the master gain and were designed to run together
256
+ * (the authentic 128K pattern: AY music + beeper SFX).
257
+ *
219
258
  * @example
220
259
  * playAY({
221
260
  * a: [{ freq: 440, dur: 300 }, { freq: 523, dur: 300, envShape: 12, envCycleDurMs: 150 }],
package/dist/ay.js.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"ay.js","sourceRoot":"","sources":["../src/ay.ts"],"names":[],"mappings":"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"}
1
+ {"version":3,"file":"ay.js","sourceRoot":"","sources":["../src/ay.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH,OAAO,EAAE,SAAS,EAAE,aAAa,EAAE,MAAM,YAAY,CAAA;AAErD,kFAAkF;AAElF,yDAAyD;AACzD,MAAM,CAAC,MAAM,QAAQ,GAAG,SAAS,CAAA;AAEjC;;;;GAIG;AACH,MAAM,CAAC,MAAM,MAAM,GAAsB;IACvC,CAAC,EAAO,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM;IAC9D,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG;CAC5D,CAAA;AAED,qEAAqE;AACrE,MAAM,OAAO,GAAG,IAAI,CAAA;AAEpB,SAAS,KAAK,CAAC,KAAa;IAC1B,OAAO,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE,KAAK,CAAC,CAAC,CAAC,GAAG,OAAO,CAAA;AAC3D,CAAC;AA+CD;;;GAGG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG;IAChC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAG,uBAAuB;IACxD,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAQ,wBAAwB;IAC1D,MAAM,EAA6B,oCAAoC;IACvE,KAAK,EAA8B,uBAAuB;IAC1D,QAAQ,EAA2B,oCAAoC;IACvE,KAAK,EAA8B,wBAAwB;IAC3D,IAAI,EAA+B,mCAAmC;IACtE,IAAI,EAA+B,yBAAyB;IAC5D,QAAQ,EAA2B,oCAAoC;IACvE,IAAI,EAA+B,wBAAwB;CACnD,CAAA;AAEV,kFAAkF;AAElF,uEAAuE;AACvE,SAAS,cAAc,CAAC,IAAkB;IACxC,MAAM,GAAG,GAAI,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,UAAU,GAAG,GAAG,CAAC,CAAA,CAAE,aAAa;IAC5D,MAAM,GAAG,GAAI,IAAI,CAAC,YAAY,CAAC,CAAC,EAAE,GAAG,EAAE,IAAI,CAAC,UAAU,CAAC,CAAA;IACvD,MAAM,IAAI,GAAG,GAAG,CAAC,cAAc,CAAC,CAAC,CAAC,CAAA;IAClC,IAAI,IAAI,GAAG,OAAO,CAAA;IAClB,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,GAAG,EAAE,CAAC,EAAE,EAAE,CAAC;QAC7B,MAAM,GAAG,GAAG,CAAC,IAAI,GAAG,CAAC,IAAI,IAAI,CAAC,CAAC,CAAC,GAAG,CAAC,CAAA;QACpC,IAAI,GAAG,CAAC,IAAI,IAAI,CAAC,CAAC,GAAG,CAAC,GAAG,IAAI,EAAE,CAAC,CAAA;QAChC,IAAI,CAAC,CAAC,CAAC,GAAG,CAAC,IAAI,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAA;IACnC,CAAC;IACD,OAAO,GAAG,CAAA;AACZ,CAAC;AAED,oFAAoF;AACpF,SAAS,aAAa,CAAC,MAAc;IACnC,OAAO,QAAQ,GAAG,CAAC,EAAE,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE,MAAM,CAAC,CAAC,CAAC,CAAA;AAC5D,CAAC;AAED,iFAAiF;AAEjF;;;;;;;GAOG;AACH,SAAS,gBAAgB,CACvB,KAAiB,EACjB,KAAa,EACb,QAAgB,EAChB,SAAiB,EACjB,SAAS,GAAG,EAAE;IAEd,MAAM,IAAI,GAAG,CAAC,KAAK,IAAI,CAAC,CAAC,GAAG,CAAC,CAAA;IAC7B,MAAM,GAAG,GAAI,CAAC,KAAK,IAAI,CAAC,CAAC,GAAG,CAAC,CAAA;IAC7B,MAAM,GAAG,GAAI,CAAC,KAAK,IAAI,CAAC,CAAC,GAAG,CAAC,CAAA;IAC7B,MAAM,IAAI,GAAI,KAAK,GAAS,CAAC,CAAA;IAE7B,MAAM,EAAE,GAAG,CAAC,CAAA;IACZ,MAAM,EAAE,GAAG,KAAK,CAAC,EAAE,CAAC,CAAA;IAEpB,iEAAiE;IACjE,KAAK,CAAC,qBAAqB,CAAC,SAAS,CAAC,CAAA;IAEtC,MAAM,IAAI,GAAG,CAAC,IAAY,EAAE,EAAU,EAAE,CAAS,EAAE,EAAE;QACnD,KAAK,CAAC,cAAc,CAAC,IAAI,EAAE,CAAC,CAAC,CAAA;QAC7B,KAAK,CAAC,uBAAuB,CAAC,EAAE,EAAE,CAAC,GAAG,QAAQ,CAAC,CAAA;IACjD,CAAC,CAAA;IAED,IAAI,CAAC,IAAI,EAAE,CAAC;QACV,wCAAwC;QACxC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,EAAE,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,EAAE,SAAS,CAAC,CAAA;QAC7C,KAAK,CAAC,cAAc,CAAC,EAAE,EAAE,SAAS,GAAG,QAAQ,CAAC,CAAA;QAC9C,OAAM;IACR,CAAC;IAED,IAAI,IAAI,EAAE,CAAC;QACT,yCAAyC;QACzC,IAAI,CAAC,GAAG,EAAE,CAAC;YACT,IAAI,CAAC,EAAE,EAAE,EAAE,EAAE,SAAS,CAAC,CAAA;YACvB,+DAA+D;YAC/D,KAAK,CAAC,cAAc,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,EAAE,SAAS,GAAG,QAAQ,CAAC,CAAA;QAC3D,CAAC;aAAM,CAAC;YACN,IAAI,CAAC,EAAE,EAAE,EAAE,EAAE,SAAS,CAAC,CAAA;YACvB,iEAAiE;YACjE,KAAK,CAAC,cAAc,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,EAAE,SAAS,GAAG,QAAQ,CAAC,CAAA;QAC3D,CAAC;QACD,OAAM;IACR,CAAC;IAED,gEAAgE;IAChE,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,SAAS,EAAE,CAAC,EAAE,EAAE,CAAC;QACnC,MAAM,CAAC,GAAG,SAAS,GAAG,CAAC,GAAG,QAAQ,CAAA;QAClC,8CAA8C;QAC9C,MAAM,IAAI,GAAG,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,KAAK,CAAC,CAAA;QAChE,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,EAAE,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAA;IACzC,CAAC;AACH,CAAC;AAED,iFAAiF;AAEjF;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,QAAQ;IACtB,SAAS,EAAE,CAAA;IACX,MAAM,MAAM,GAAG,aAAa,EAAG,CAAA;IAC/B,MAAM,IAAI,GAAK,MAAM,CAAC,OAAuB,CAAA;IAE7C,MAAM,QAAQ,GAAG,cAAc,CAAC,IAAI,CAAC,CAAA;IAErC,MAAM,WAAW,GAAG,GAAG,EAAE;QACvB,MAAM,GAAG,GAAQ,IAAI,CAAC,gBAAgB,EAAE,CAAA;QACxC,MAAM,QAAQ,GAAG,IAAI,CAAC,UAAU,EAAE,CAAA;QAClC,GAAG,CAAC,IAAI,GAAG,QAAQ,CAAA;QACnB,GAAG,CAAC,SAAS,CAAC,KAAK,GAAG,GAAG,CAAA;QACzB,QAAQ,CAAC,IAAI,CAAC,KAAK,GAAG,CAAC,CAAA;QACvB,GAAG,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAA;QACrB,QAAQ,CAAC,OAAO,CAAC,MAAM,CAAC,CAAA;QACxB,GAAG,CAAC,KAAK,EAAE,CAAA;QAEX,MAAM,WAAW,GAAG,IAAI,CAAC,kBAAkB,EAAE,CAAA;QAC7C,WAAW,CAAC,IAAI,GAAG,SAAS,CAAA;QAC5B,WAAW,CAAC,SAAS,CAAC,KAAK,GAAG,aAAa,CAAC,CAAC,CAAC,CAAA;QAC9C,MAAM,SAAS,GAAG,IAAI,CAAC,UAAU,EAAE,CAAA;QACnC,SAAS,CAAC,IAAI,CAAC,KAAK,GAAG,CAAC,CAAA;QACxB,WAAW,CAAC,OAAO,CAAC,SAAS,CAAC,CAAA;QAC9B,SAAS,CAAC,OAAO,CAAC,MAAM,CAAC,CAAA;QAEzB,OAAO,EAAE,GAAG,EAAE,QAAQ,EAAE,WAAW,EAAE,SAAS,EAAE,CAAA;IAClD,CAAC,CAAA;IAGD,MAAM,GAAG,GAA0B;QACjC,CAAC,EAAE,WAAW,EAAE,EAAE,CAAC,EAAE,WAAW,EAAE,EAAE,CAAC,EAAE,WAAW,EAAE;KACrD,CAAA;IAED,gEAAgE;IAChE,MAAM,QAAQ,GAAG,IAAI,CAAC,kBAAkB,EAAE,CAAA;IAC1C,QAAQ,CAAC,MAAM,GAAG,QAAQ,CAAA;IAC1B,QAAQ,CAAC,IAAI,GAAK,IAAI,CAAA;IACtB,QAAQ,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,WAAW,CAAC,CAAA;IACnC,QAAQ,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,WAAW,CAAC,CAAA;IACnC,QAAQ,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,WAAW,CAAC,CAAA;IACnC,QAAQ,CAAC,KAAK,EAAE,CAAA;IAEhB,OAAO;QACL,IAAI,CAAC,EAAE,EAAE,IAAI,EAAE,GAAG,GAAG,EAAE;YACrB,MAAM,EAAE,GAAG,EAAE,QAAQ,EAAE,GAAG,GAAG,CAAC,EAAE,CAAC,CAAA;YACjC,MAAM,GAAG,GAAG,IAAI,CAAC,WAAW,CAAA;YAC5B,QAAQ,CAAC,IAAI,CAAC,qBAAqB,CAAC,GAAG,CAAC,CAAA;YACxC,IAAI,IAAI,IAAI,CAAC,EAAE,CAAC;gBACd,QAAQ,CAAC,IAAI,CAAC,eAAe,CAAC,CAAC,EAAE,GAAG,EAAE,KAAK,CAAC,CAAA;YAC9C,CAAC;iBAAM,CAAC;gBACN,GAAG,CAAC,SAAS,CAAC,cAAc,CAAC,IAAI,EAAE,GAAG,CAAC,CAAA;gBACvC,QAAQ,CAAC,IAAI,CAAC,eAAe,CAAC,KAAK,CAAC,GAAG,CAAC,EAAE,GAAG,EAAE,KAAK,CAAC,CAAA;YACvD,CAAC;QACH,CAAC;QAED,WAAW,CAAC,EAAE,EAAE,MAAM,GAAG,CAAC;YACxB,MAAM,EAAE,WAAW,EAAE,SAAS,EAAE,GAAG,GAAG,CAAC,EAAE,CAAC,CAAA;YAC1C,MAAM,GAAG,GAAG,IAAI,CAAC,WAAW,CAAA;YAC5B,WAAW,CAAC,SAAS,CAAC,cAAc,CAAC,aAAa,CAAC,MAAM,CAAC,EAAE,GAAG,CAAC,CAAA;YAChE,SAAS,CAAC,IAAI,CAAC,eAAe,CAAC,KAAK,CAAC,EAAE,CAAC,EAAE,GAAG,EAAE,KAAK,CAAC,CAAA;QACvD,CAAC;QAED,YAAY,CAAC,EAAE;YACb,GAAG,CAAC,EAAE,CAAC,CAAC,SAAS,CAAC,IAAI,CAAC,eAAe,CAAC,CAAC,EAAE,IAAI,CAAC,WAAW,EAAE,KAAK,CAAC,CAAA;QACpE,CAAC;QAED,QAAQ,CAAC,EAAE,EAAE,KAAK,EAAE,UAAU;YAC5B,gBAAgB,CACd,GAAG,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,IAAI,EACrB,KAAK,EACL,UAAU,GAAG,IAAI,EACjB,IAAI,CAAC,WAAW,CACjB,CAAA;QACH,CAAC;QAED,IAAI,CAAC,EAAE;YACL,MAAM,EAAE,QAAQ,EAAE,SAAS,EAAE,GAAG,GAAG,CAAC,EAAE,CAAC,CAAA;YACvC,MAAM,GAAG,GAAG,IAAI,CAAC,WAAW,CAAA;YAC5B,QAAQ,CAAC,IAAI,CAAC,qBAAqB,CAAC,GAAG,CAAC,CAAA;YACxC,SAAS,CAAC,IAAI,CAAC,qBAAqB,CAAC,GAAG,CAAC,CAAA;YACzC,QAAQ,CAAC,IAAI,CAAC,eAAe,CAAC,CAAC,EAAE,GAAG,EAAE,KAAK,CAAC,CAAA;YAC5C,SAAS,CAAC,IAAI,CAAC,eAAe,CAAC,CAAC,EAAE,GAAG,EAAE,KAAK,CAAC,CAAA;QAC/C,CAAC;QAED,OAAO;YACL,MAAM,GAAG,GAAG,IAAI,CAAC,WAAW,CAAA;YAC5B,KAAK,MAAM,EAAE,QAAQ,EAAE,SAAS,EAAE,IAAI,MAAM,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC;gBACzD,QAAQ,CAAC,IAAI,CAAC,qBAAqB,CAAC,GAAG,CAAC,CAAA;gBACxC,SAAS,CAAC,IAAI,CAAC,qBAAqB,CAAC,GAAG,CAAC,CAAA;gBACzC,QAAQ,CAAC,IAAI,CAAC,eAAe,CAAC,CAAC,EAAE,GAAG,EAAE,KAAK,CAAC,CAAA;gBAC5C,SAAS,CAAC,IAAI,CAAC,eAAe,CAAC,CAAC,EAAE,GAAG,EAAE,KAAK,CAAC,CAAA;YAC/C,CAAC;QACH,CAAC;QAED,IAAI;YACF,MAAM,GAAG,GAAG,IAAI,CAAC,WAAW,CAAA;YAC5B,QAAQ,CAAC,IAAI,CAAC,GAAG,GAAG,IAAI,CAAC,CAAA;YACzB,QAAQ,CAAC,UAAU,EAAE,CAAA;YACrB,KAAK,MAAM,EAAE,GAAG,EAAE,QAAQ,EAAE,WAAW,EAAE,SAAS,EAAE,IAAI,MAAM,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC;gBAC3E,QAAQ,CAAC,IAAI,CAAC,cAAc,CAAC,CAAC,EAAE,GAAG,CAAC,CAAA;gBACpC,SAAS,CAAC,IAAI,CAAC,cAAc,CAAC,CAAC,EAAE,GAAG,CAAC,CAAA;gBACrC,GAAG,CAAC,IAAI,CAAC,GAAG,GAAG,IAAI,CAAC,CAAA;gBACpB,GAAG,CAAC,UAAU,EAAE,CAAA;gBAChB,QAAQ,CAAC,UAAU,EAAE,CAAA;gBACrB,WAAW,CAAC,UAAU,EAAE,CAAA;gBACxB,SAAS,CAAC,UAAU,EAAE,CAAA;YACxB,CAAC;QACH,CAAC;KACF,CAAA;AACH,CAAC;AAED,iFAAiF;AAEjF;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,UAAU,MAAM,CACpB,OAAqD,EACrD,UAAU,GAAG,CAAC;IAEd,SAAS,EAAE,CAAA;IACX,MAAM,MAAM,GAAG,aAAa,EAAE,CAAA;IAC9B,IAAI,CAAC,MAAM;QAAE,OAAM;IACnB,MAAM,IAAI,GAAK,MAAM,CAAC,OAAuB,CAAA;IAC7C,MAAM,QAAQ,GAAG,cAAc,CAAC,IAAI,CAAC,CAAA;IAErC,MAAM,eAAe,GAAG,CAAC,KAA2B,EAAQ,EAAE;QAC5D,IAAI,CAAC,KAAK,EAAE,MAAM;YAAE,OAAM;QAC1B,IAAI,CAAC,GAAG,IAAI,CAAC,WAAW,GAAG,UAAU,GAAG,IAAI,CAAA;QAE5C,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;YACzB,MAAM,EAAE,IAAI,EAAE,GAAG,EAAE,GAAG,GAAG,EAAE,EAAE,KAAK,GAAG,KAAK,EAAE,WAAW,GAAG,CAAC,EAAE,QAAQ,EAAE,aAAa,EAAE,GAAG,IAAI,CAAA;YAC7F,MAAM,IAAI,GAAG,GAAG,GAAG,IAAI,CAAA;YAEvB,IAAI,IAAI,GAAG,CAAC,EAAE,CAAC;gBACb,MAAM,GAAG,GAAQ,IAAI,CAAC,gBAAgB,EAAE,CAAA;gBACxC,MAAM,QAAQ,GAAG,IAAI,CAAC,UAAU,EAAE,CAAA;gBAClC,GAAG,CAAC,IAAI,GAAG,QAAQ,CAAA;gBACnB,GAAG,CAAC,SAAS,CAAC,KAAK,GAAG,IAAI,CAAA;gBAC1B,GAAG,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAA;gBACrB,QAAQ,CAAC,OAAO,CAAC,MAAM,CAAC,CAAA;gBAExB,IAAI,QAAQ,KAAK,SAAS,EAAE,CAAC;oBAC3B,MAAM,QAAQ,GAAG,CAAC,aAAa,IAAI,GAAG,CAAC,GAAG,IAAI,CAAA;oBAC9C,MAAM,SAAS,GAAG,IAAI,CAAC,IAAI,CAAC,IAAI,GAAG,QAAQ,CAAC,GAAG,CAAC,CAAA;oBAChD,gBAAgB,CAAC,QAAQ,CAAC,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,CAAC,EAAE,SAAS,CAAC,CAAA;oBACjE,QAAQ,CAAC,IAAI,CAAC,cAAc,CAAC,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC,CAAA;gBAC3C,CAAC;qBAAM,CAAC;oBACN,MAAM,GAAG,GAAG,KAAK,CAAA;oBACjB,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC,KAAK,EAAE,IAAI,GAAG,IAAI,CAAC,CAAA;oBACxC,QAAQ,CAAC,IAAI,CAAC,cAAc,CAAC,CAAC,EAAE,CAAC,CAAC,CAAA;oBAClC,QAAQ,CAAC,IAAI,CAAC,uBAAuB,CAAC,KAAK,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,GAAG,CAAC,CAAA;oBAC1D,QAAQ,CAAC,IAAI,CAAC,cAAc,CAAC,KAAK,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,IAAI,GAAG,GAAG,CAAC,CAAA;oBACxD,QAAQ,CAAC,IAAI,CAAC,uBAAuB,CAAC,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC,CAAA;gBACpD,CAAC;gBAED,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,CAAA;gBACZ,GAAG,CAAC,IAAI,CAAC,CAAC,GAAG,IAAI,GAAG,IAAI,CAAC,CAAA;YAC3B,CAAC;YAED,IAAI,KAAK,EAAE,CAAC;gBACV,MAAM,QAAQ,GAAM,IAAI,CAAC,kBAAkB,EAAE,CAAA;gBAC7C,MAAM,WAAW,GAAG,IAAI,CAAC,kBAAkB,EAAE,CAAA;gBAC7C,MAAM,SAAS,GAAK,IAAI,CAAC,UAAU,EAAE,CAAA;gBACrC,QAAQ,CAAC,MAAM,GAAU,QAAQ,CAAA;gBACjC,QAAQ,CAAC,IAAI,GAAY,IAAI,CAAA;gBAC7B,WAAW,CAAC,IAAI,GAAS,SAAS,CAAA;gBAClC,WAAW,CAAC,SAAS,CAAC,KAAK,GAAG,aAAa,CAAC,WAAW,CAAC,CAAA;gBAExD,IAAI,QAAQ,KAAK,SAAS,EAAE,CAAC;oBAC3B,MAAM,QAAQ,GAAG,CAAC,aAAa,IAAI,GAAG,CAAC,GAAG,IAAI,CAAA;oBAC9C,MAAM,SAAS,GAAG,IAAI,CAAC,IAAI,CAAC,IAAI,GAAG,QAAQ,CAAC,GAAG,CAAC,CAAA;oBAChD,gBAAgB,CAAC,SAAS,CAAC,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,CAAC,EAAE,SAAS,CAAC,CAAA;oBAClE,SAAS,CAAC,IAAI,CAAC,cAAc,CAAC,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC,CAAA;gBAC5C,CAAC;qBAAM,CAAC;oBACN,MAAM,GAAG,GAAG,KAAK,CAAA;oBACjB,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC,KAAK,EAAE,IAAI,GAAG,IAAI,CAAC,CAAA;oBACxC,MAAM,EAAE,GAAI,KAAK,CAAC,GAAG,CAAC,GAAG,GAAG,CAAA;oBAC5B,SAAS,CAAC,IAAI,CAAC,cAAc,CAAC,CAAC,EAAE,CAAC,CAAC,CAAA;oBACnC,SAAS,CAAC,IAAI,CAAC,uBAAuB,CAAC,EAAE,EAAE,CAAC,GAAG,GAAG,CAAC,CAAA;oBACnD,SAAS,CAAC,IAAI,CAAC,cAAc,CAAC,EAAE,EAAE,CAAC,GAAG,IAAI,GAAG,GAAG,CAAC,CAAA;oBACjD,SAAS,CAAC,IAAI,CAAC,uBAAuB,CAAC,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC,CAAA;gBACrD,CAAC;gBAED,QAAQ,CAAC,OAAO,CAAC,WAAW,CAAC,CAAA;gBAC7B,WAAW,CAAC,OAAO,CAAC,SAAS,CAAC,CAAA;gBAC9B,SAAS,CAAC,OAAO,CAAC,MAAM,CAAC,CAAA;gBACzB,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,CAAA;gBACjB,QAAQ,CAAC,IAAI,CAAC,CAAC,GAAG,IAAI,GAAG,IAAI,CAAC,CAAA;YAChC,CAAC;YAED,CAAC,IAAI,IAAI,CAAA;QACX,CAAC;IACH,CAAC,CAAA;IAED,eAAe,CAAC,OAAO,CAAC,CAAC,CAAC,CAAA;IAC1B,eAAe,CAAC,OAAO,CAAC,CAAC,CAAC,CAAA;IAC1B,eAAe,CAAC,OAAO,CAAC,CAAC,CAAC,CAAA;AAC5B,CAAC"}
package/dist/i18n.d.ts ADDED
@@ -0,0 +1,43 @@
1
+ /**
2
+ * i18n.ts — locale selection helper.
3
+ *
4
+ * A tiny, dependency-free utility for picking a string pack at runtime
5
+ * based on a language code. Designed so any zx-kit game can ship with
6
+ * multiple translations and switch them via a single config flag.
7
+ *
8
+ * USAGE
9
+ * ─────
10
+ * Each locale exports the same shape — usually as named string constants
11
+ * and template functions (e.g. `STR_DEPTH = (m) => \`D:${m}M\``).
12
+ * Import each locale module as a namespace and hand them to `pickLocale`:
13
+ *
14
+ * import * as en from './strings.ts' // default English
15
+ * import * as sk from './strings.sk.ts' // Slovak
16
+ * import * as ru from './strings.ru.ts' // Russian
17
+ * import { LANGUAGE_CODE } from './config.ts'
18
+ *
19
+ * export const L = pickLocale(en, { sk, ru }, LANGUAGE_CODE)
20
+ *
21
+ * Consumers then read `L.STR_DEPTH(120)` etc. — same name, swapped values.
22
+ *
23
+ * SELECTION RULES
24
+ * ───────────────
25
+ * - `code` null / undefined / empty → returns `defaultLocale`
26
+ * - `code` matches a key in `locales` → returns that locale
27
+ * (case-insensitive: 'SK' === 'sk')
28
+ * - `code` doesn't match anything → returns `defaultLocale`
29
+ *
30
+ * The default key (typically 'en') doesn't need to live in the `locales`
31
+ * map — passing 'en' simply falls through to `defaultLocale`. This keeps
32
+ * the English source-of-truth file at the conventional `strings.ts` path
33
+ * without forcing a `strings.en.ts` rename.
34
+ */
35
+ /**
36
+ * Pick a locale object from a map by code, with fallback to a default.
37
+ *
38
+ * Generic over `T` so every entry in `locales` is type-checked against the
39
+ * shape of `defaultLocale` — adding a new translation that misses a key
40
+ * (or has a wrong signature) becomes a compile error.
41
+ */
42
+ export declare function pickLocale<T>(defaultLocale: T, locales: Record<string, T>, code: string | null | undefined): T;
43
+ //# sourceMappingURL=i18n.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"i18n.d.ts","sourceRoot":"","sources":["../src/i18n.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAEH;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,CAAC,EAC1B,aAAa,EAAE,CAAC,EAChB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC,EAC1B,IAAI,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAC9B,CAAC,CAIH"}