Introduction

buttplug.js is a type-safe TypeScript client for the Buttplug Intimacy Protocol v4. It connects to a Buttplug server over WebSocket, discovers devices, and controls them through a high-level API.

import { ButtplugClient } from "@zendrex/buttplug.js";

const client = new ButtplugClient("ws://localhost:12345");

client.on("deviceAdded", ({ device }) => {
  device.vibrate(50);
});

await client.connect();
await client.startScanning();

Features

• Protocol v4 -- 10 output types and 5 sensor input types: vibration, rotation, position, oscillation, constriction, and more
• Type-safe API -- Full TypeScript types with Zod schema validation for autocomplete and compile-time safety
• Pattern Engine -- Keyframe-based pattern playback with built-in presets, custom tracks, easing curves, and loop control
• Auto-reconnect -- Configurable reconnection with exponential backoff, attempt limits, and lifecycle events
• Ping Keep-alive -- Automatic ping management with configurable intervals to maintain server connections
• Runtime Agnostic -- Works in any JavaScript runtime with WebSocket support

Prerequisites

Intiface Central acts as the Buttplug server. Install and start it before connecting from your application. The default WebSocket address is ws://localhost:12345.

Any JavaScript runtime with WebSocket support works: Node.js 18+, Bun, Deno, or modern browsers. The library has zero native dependencies.

Next Steps