buttplug-js

A self-contained example that connects to Intiface Central and controls a vibrating device is available in the repository. To run it, serve the file using a local HTTP server.

Steps:

1. Locate examples/quickstart.html.
2. Run a local server (e.g., using npx serve).
3. Open the file in your browser.

npx serve examples

You can include buttplug-js in web projects using UMD or ES Modules.

• UMD: Use the UMD bundle to expose a global buttplug namespace. You can access types and classes via buttplug.ButtplugClient.
• ES Modules: Import specific members directly from the .mjs file.

For direct use in HTML without a bundler, use a CDN.

<!-- UMD (exposes global `buttplug` namespace) -->
<script src="https://cdn.jsdelivr.net/npm/buttplug@5/dist/web/buttplug.js"></script>

<!-- ES Module -->
<script type="module">
  import { ButtplugClient } from 'https://cdn.jsdelivr.net/npm/buttplug@5/dist/web/buttplug.mjs';
</script>

To use buttplug-js in a Node.js environment, you must swap the connector class. While the API remains identical to the browser version, you must use ButtplugNodeWebsocketClientConnector instead of ButtplugBrowserWebsocketClientConnector.

Note: The Buttplug WASM Server is not compatible with pure Node.js applications; it requires a browser environment to run.

Additional web-based examples are located in the examples/web/ directory. These examples demonstrate:

• Error handling
• Device enumeration
• Device information retrieval
• Logging

These examples utilize the UMD bundle via <script> tags.

The buttplug-js protocol uses unique IDs to track messages. Use msgId to retrieve the ID from a ButtplugMessage object and setMsgId to assign an ID to one. Both functions iterate through the entries of the message object to find the property containing the Id field.

Note: If the message does not contain a valid entry with an Id, a ButtplugMessageError is thrown.

import { msgId, setMsgId, ButtplugMessage } from './Messages';

// Example usage (assuming a message object exists)
const id = msgId(myMessage);
setMsgId(myMessage, 123);

The ButtplugClient allows you to control the discovery process of new devices on the server.

• startScanning(): Tells the server to begin looking for new devices. Sets isScanning to true.
• stopScanning(): Tells the server to stop looking for new devices. Sets isScanning to false.
• isScanning: A boolean property indicating if a scan is currently in progress.

When a scan completes, the client emits the scanningfinished event.

// Start looking for devices
await client.startScanning();

client.on('scanningfinished', () => {
  console.log('Scan complete!');
});

// Stop looking for devices
await client.stopScanning();

You can query a ButtplugClientDevice to see if it supports specific types of interaction using hasOutput and hasInput.

• hasOutput(type: Messages.OutputType): boolean: Returns true if any feature on the device supports the specified output type (e.g., Vibration, Temperature).
• hasInput(type: Messages.InputType): boolean: Returns true if any feature on the device supports the specified input type (e.g., Battery, Button, Position).

To trigger an action on a device (like starting vibration), use runOutput. This method iterates through all features on the device that support the requested outputType and executes the command on them.

If no features support the requested type, the promise will reject.

// Example: Running a vibration command
await device.runOutput({
  outputType: Messages.OutputType.Vibration,
  // ... other command properties
});

The stop() method sends a command to the device to stop all current outputs (vibration, etc.) and inputs. It is an asynchronous operation that ensures the device receives a StopCmd.

await device.stop();

The stopAllDevices() method sends a command to the server to stop all outputs and inputs on all connected devices. This is useful for an emergency stop or a clean shutdown.

// Immediately stop all device activity
await client.stopAllDevices();