Install

# Browser
npm install ultimatedarktower

# Node.js (adds the optional BLE peer dependency)
npm install ultimatedarktower @stoprocent/noble

Platform notes. Node.js 18+. macOS works out of the box. Linux needs BlueZ (sudo apt install bluetooth bluez libbluetooth-dev). Windows needs Windows 10+ with BLE support.

Quick start

import UltimateDarkTower from 'ultimatedarktower';

const tower = new UltimateDarkTower();

tower.onTowerConnect = () => console.log('Connected.');
tower.onCalibrationComplete = () => console.log('Calibrated.');

await tower.connect(); // browser: opens device picker; node: scans
await tower.calibrate(); // required before drum rotation is reliable
await tower.playSound(1);
await tower.cleanup(); // always clean up on shutdown

Walkthrough with explanations, error handling, lights, drum rotation, and a full example: docs/GETTING_STARTED.md.

Features

• Multi-platform Bluetooth — Web Bluetooth, Node.js (@stoprocent/noble), Electron, React Native via custom adapters.
• Complete tower control — lights, sounds, drum rotation, seal breaking, skull counter.
• Stateful command variants — preserve every other state when changing one field.
• Glyph tracking — automatic glyph position updates as drums rotate.
• Game state — seal state, broken seals, software-tracked across sessions.
• BLE flight recorder — opt-in disconnect diagnostics with structured event capture.
• Event callbacks — connect, calibrate, skull drop, battery, state change.
• Logger — pluggable outputs (console, DOM, in-memory buffer).
• TypeScript-first — full type definitions, ESM + CJS builds.
• Seed parser — decode, encode, validate, and compare game seeds.

Documentation

A guided map of the docs lives at docs/README.md. The headline pages:

| Page | Use it when… | | -------------------------------------------- | --------------------------------------------------- | | Getting Started | …you're new and want a working tower in 10 minutes. | | API Reference | …you need the full surface, split by topic. | | Architecture | …you want to understand how the layers fit. | | Examples | …you want to know what the demo apps demonstrate. | | Tower Tech Notes | …you're reverse-engineering the protocol. | | Seed Format | …you're working with game seeds at the byte level. | | BLE Diagnostics | …you want disconnect flight-recorder data. | | Troubleshooting | …the hardware is misbehaving. | | Ecosystem | …you want the companion libraries & tools. |

Examples

• Controller — full reference UI with a BLE diagnostics tab and tower emulator.
• Game — The Tower's Challenge, a complete browser game.
• Node CLI — minimal interactive driver for verifying the Node adapter.

Platform support

| Platform | Adapter | Notes | | ---------------------------------------------------- | -------------- | ------------------------------------------------------------------------------- | | Chrome / Edge / Samsung Internet (desktop + Android) | Built-in | Web Bluetooth | | Node.js 18+ | Built-in | Requires @stoprocent/noble | | Electron | Built-in | Auto-detects renderer vs main process | | iOS Safari / iOS Chrome | — | Use Bluefy | | Firefox | — | No Web Bluetooth | | React Native | Custom adapter | react-native-ble-plx recommended — see adapters guide | | Cordova / Capacitor | Custom adapter | See adapters guide |

Related projects

This library is part of a wider Return to Dark Tower family. See docs/ECOSYSTEM.md for the full list. Highlights:

• UltimateDarkTowerDisplay — composable renderers (text, 2D, 3D) for tower state.
• UltimateDarkTowerSync — state synchronization across devices.
• mcp-server-return-to-dark-tower — MCP server exposing tower control to AI agents.

Known issues

• Sound and animation completion — the tower reports "command complete" the moment a sound or animation starts, not when it ends. Don't use the completion response as a "ready for next sound" signal; sleep or use the LED-sequence response timing documented in docs/TOWER_TECH_NOTES.md.

Contributing

Workflow, code standards, release process, and hardware testing instructions: CONTRIBUTING.md.

Community

Questions? Ideas? Join us on our UltimateDarkTower Discord Server!

You can also find us in the RTDT Fan Content Channel on Restoration Games Discord.

Personal note from the Developer

I have spent many hours reverse engineering the Tower's protocol (by hand, this was before AI existed :D) in order to create this library, I look forward to what others will create using this! - Chris