@wilderzone/vgs 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Wilderzone
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,77 @@
+# VGS
+Voice Game System
+
+```sh
+npm install @wilderzone/vgs
+
+# or
+
+deno add @wilderzone/vgs
+```
+
+
+## Usage
+
+Create and configure a VGS instance.
+```ts
+import { VGS, type VGSConfig, type VGSMatch } from '@wilderzone/vgs';
+import { data } from './your/data';
+
+// Configure VGS.
+const config: VGSConfig = {
+	trigger: 'V',
+	timeout: 3000,
+	options: data
+};
+
+// Create a new VGS instance.
+const vgs = new VGS(config);
+```
+
+Connect callbacks with `.on`.
+```ts
+import { onCancel, onOptions, onMatch } from './your/logic';
+
+vgs.on('cancel', onCancel);
+vgs.on('options', onOptions);
+vgs.on('match', onMatch);
+```
+
+Then send keypresses to the system with `.press`.
+```ts
+vgs.press('V');
+vgs.press('G');
+vgs.press('W');
+```
+
+When the VGS finds a match, it will call your `'match'` callback so you can play the appropriate voice line.
+
+
+### Configuration
+
+| Option     | Required | Default    | Description                                                                                                    |
+| :--------- | :------- | :--------: | :------------------------------------------------------------------------------------------------------------- |
+| `options`  | *        |            | The voice lines to include in the VGS.                                                                         |
+| `timeout`  |          | `3000`     | The duration (in ms) to wait for further keypresses before timing out. Set this to `0` to disable the timeout. |
+| `trigger`  |          | `"V"`      | The key used to trigger VGS.                                                                                   |
+| `cancel`   |          | `"Escape"` | The key used to cancel the current VGS sequence.                                                               |
+
+
+### Methods
+
+| Method     | Description                                                           |
+| :--------- | :-------------------------------------------------------------------- |
+| `on`       | Listen to VGS [events](#events).                                      |
+| `press`    | Send a keypress to the VGS. Keys are case insensitive.                |
+| `cancel`   | Cancel the current VGS sequence.                                      |
+
+
+### Events
+
+| Event      | Payload      | Description                                                                        |
+| :--------- | :----------- | :--------------------------------------------------------------------------------- |
+| `trigger`  |              | Fired when a new VGS sequence is started (after a `trigger` keypress is detected). |
+| `options`  | `VGSMatch[]` | Fired when the VGS produces the next set of options in the current sequence.       |
+| `match`    | `VGSMatch`   | Fired when the sequence matches a single voice line. The sequence is then reset.   |
+| `cancel`   |              | Fired when the sequence is cancelled by the `cancel` key or `.cancel()` method.    |
+| `timeout`  |              | Fired when the sequence times out.                                                 |

package/npm/index.d.ts

@@ -0,0 +1,82 @@
+type VGSOptionType = 'category' | 'line';
+export interface VGSOption {
+    type: VGSOptionType;
+    name?: string;
+    file?: string;
+    phrase?: string;
+}
+export interface VGSMatch {
+    type: VGSOptionType;
+    command: string;
+    key: string;
+    name?: string;
+    file?: string;
+    phrase?: string;
+}
+/**
+ * VGS configuration.
+ */
+export interface VGSConfig {
+    /**
+     * The VGS options.
+     */
+    options: Record<string, VGSOption>;
+    /**
+     * The duration (in ms) to wait for further keypresses before timing out.\
+     * Set this to `0` to disable the timeout.
+     *
+     * _Optional, default: `3000`_
+     */
+    timeout?: number;
+    /**
+     * The key used to trigger VGS.
+     *
+     * _Optional, default: `"V"`_
+     */
+    trigger?: string;
+    /**
+     * The key used to cancel the current VGS sequence.
+     *
+     * _Optional, default: `"Escape"`_
+     */
+    cancel?: string;
+}
+type VGSEvent = 'cancel' | 'options' | 'match' | 'timeout' | 'trigger';
+type VGSCallback<T extends VGSEvent> = T extends 'cancel' ? () => void : T extends 'options' ? (options: VGSMatch[]) => void : T extends 'match' ? (match: VGSMatch) => void : T extends 'timeout' ? () => void : T extends 'trigger' ? () => void : never;
+/**
+ * A Voice Game System (VGS) command processor.
+ *
+ * @param config The VGS configuration.
+ */
+export declare class VGS {
+    private config;
+    private callbacks;
+    private options;
+    private sequence;
+    private timer;
+    constructor(config: VGSConfig);
+    private reset;
+    private timeout;
+    private processSequence;
+    /**
+     * Send a keypress to the VGS.
+     *
+     * @param key The key that was pressed. For example, `"V"`.
+     * @note This is case insensitive.
+     */
+    press(key: string): void;
+    /**
+     * Cancel the current VGS sequence.
+     *
+     * @note This will fire the `cancel` event.
+     */
+    cancel(): void;
+    /**
+     * Register a function to be called when a particular event is fired.
+     *
+     * @param event The event to listen to.
+     * @param callback The function to call.
+     */
+    on<T extends VGSEvent>(event: T, callback: VGSCallback<T>): void;
+}
+export {};

package/npm/index.js

@@ -0,0 +1 @@
+var o=class{config;callbacks={cancel:[],options:[],match:[],timeout:[],trigger:[]};options;sequence=[];timer;constructor(t){this.config={options:t.options,timeout:t.timeout??3e3,trigger:t.trigger?.toUpperCase()||"V",cancel:t.cancel?.toUpperCase()||"ESCAPE"},this.options=Object.entries(this.config.options).map(([s,e])=>({command:s,option:e}))}reset(){this.sequence=[],globalThis.clearTimeout(this.timer)}timeout(){this.reset();for(let t of this.callbacks.timeout)t()}processSequence(){let t=this.sequence.join(""),s=this.options.find(c=>c.command===t),e=this.options.filter(c=>c.command.length===t.length+1).filter(c=>c.command.startsWith(t));if(s&&s.option.type==="line"){for(let c of this.callbacks.match)c({...s.option,key:s.command.at(-1),command:s.command});this.reset()}if(e.length)for(let c of this.callbacks.options)c(e.map(i=>({...i.option,key:i.command.at(-1),command:i.command})));!s&&!e.length&&this.cancel()}press(t){t=t.toUpperCase();let s=t===this.config.cancel,e=t.length>1,c=t===this.config.trigger;if(s||e){this.cancel();return}if(!(!this.sequence.length&&!c)){globalThis.clearTimeout(this.timer),this.config.timeout&&(this.timer=globalThis.setTimeout(()=>this.timeout(),this.config.timeout));for(let i of this.callbacks.trigger)i();this.sequence.push(t),this.processSequence()}}cancel(){this.reset();for(let t of this.callbacks.cancel)t()}on(t,s){this.callbacks[t].push(s)}};export{o as VGS};

package/package.json

@@ -0,0 +1,17 @@
+{
+	"name": "@wilderzone/vgs",
+	"description": "",
+	"version": "1.0.0",
+	"author": "Giga",
+	"license": "MIT",
+	"main": "./npm/index.js",
+	"types": "./npm/index.d.ts",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/wilderzone/vgs.git"
+	},
+	"bugs": {
+		"url": "https://github.com/wilderzone/vgs/issues"
+	},
+	"homepage": "https://github.com/wilderzone/vgs#readme"
+}