UltimateDarkTower

A JavaScript/TypeScript library for controlling the Bluetooth-enabled tower from Restoration Games' Return to Dark Tower board game. Control lights, sounds, drum rotation, and track game state via Bluetooth - works in browsers (Web Bluetooth), Node.js, Electron, and React Native.

I have spent many hours reverse engineering the Tower's protocol in order to create this library, I look forward to what others will create using this! - Chris

Table of Contents

• UltimateDarkTower
  • Table of Contents
  • Features
  • Live Examples
  • Installation
    • Browser / Web Applications
    • Node.js Applications
  • Quick Start
    • Browser (auto-detected)
    • Node.js (auto-detected)
    • Explicit Platform Selection
    • Custom Adapter (React Native, etc.)
  • Documentation
    • 📖 Complete API Reference
    • Key Topics Covered:
  • Development
    • Building and Testing
    • Project Structure
  • Platform Support
    • Built-in Support (auto-detected)
    • Custom Adapter Support
    • Browser Support
  • Known Issues
  • Community

Features

• Multi-Platform Bluetooth - Works in browsers (Web Bluetooth), Node.js (@stoprocent/noble), Electron, and React Native via custom adapters
• Bluetooth Connection Management - Reliable connection with automatic monitoring and disconnect detection
• Tower Control - Complete control over lights, sounds, and drum rotation
• Game State Tracking - Track glyph positions, broken seals, and skull counts
• Event System - Callback-based event handling for tower events
• ESM + CJS - Ships both an ES Module build and a CommonJS build; works with import and require without configuration
• TypeScript Support - Full TypeScript definitions and type safety
• Comprehensive Logging - Multi-output logging system for debugging
• Battery Monitoring - Real-time battery level tracking and low battery warnings
• Extensible Adapter Pattern - Implement IBluetoothAdapter for custom platforms

Live Examples

Try the library in action! Just power on your Tower and visit:

• Tower Controller - Replicates official app functionality and gives examples of library functionality.

• Tower Game - "The Tower's Challenge" - a complete game using just the tower

Requires Web Bluetooth support (Chrome, Edge, Samsung Internet). For iOS, use the Bluefy app.

Installation

Browser / Web Applications

npm install ultimatedarktower

Node.js Applications

npm install ultimatedarktower @stoprocent/noble

@stoprocent/noble is an optional peer dependency for BLE support in Node.js environments.

Platform requirements: macOS works out of the box. Linux requires BlueZ (sudo apt install bluetooth bluez libbluetooth-dev). Windows requires Windows 10+ with BLE support.

Quick Start

Browser (auto-detected)

import UltimateDarkTower from 'ultimatedarktower';

const tower = new UltimateDarkTower();
await tower.connect(); // Opens browser device picker
await tower.calibrate();
await tower.playSound(1);
await tower.cleanup();

Node.js (auto-detected)

import UltimateDarkTower from 'ultimatedarktower';

const tower = new UltimateDarkTower();
await tower.connect(); // Scans for device automatically
await tower.calibrate();
await tower.playSound(1);
await tower.cleanup();

Explicit Platform Selection

import UltimateDarkTower, { BluetoothPlatform } from 'ultimatedarktower';

const tower = new UltimateDarkTower({ platform: BluetoothPlatform.NODE });

Custom Adapter (React Native, etc.)

import UltimateDarkTower, { IBluetoothAdapter } from 'ultimatedarktower';

class MyCustomAdapter implements IBluetoothAdapter {
    // Implement all IBluetoothAdapter methods
    // See Reference.md for the full interface
}

const tower = new UltimateDarkTower({ adapter: new MyCustomAdapter() });

Documentation

📖 Complete API Reference

Comprehensive documentation with TypeScript examples, best practices, and troubleshooting guides.

Key Topics Covered:

• Multi-Platform Setup - Configuration for Web, Node.js, Electron, and React Native
• Connection Management - Connecting, disconnecting, and monitoring connection health
• Bluetooth Adapters - Custom adapter interface for extending platform support
• Tower Control - Detailed coverage of all tower commands (lights, sounds, rotation)
• Glyph System - Automatic tracking of glyph positions as towers rotate
• Seal Management - Breaking seals and tracking game state
• Event Handling - Callback system for tower events
• Logging System - Multi-output logging for debugging and monitoring
• Best Practices - Performance tips, error handling, and common patterns
• Troubleshooting - Solutions for common issues and debugging techniques

Integration Testing

Integration tests that require real hardware are located in tests/integration/ and are not run by default with the main test suite. These tests use the Node.js Bluetooth adapter and require a physical Return to Dark Tower device in range.

To run the calibration integration test:

npm run test:integration

• This will connect to the tower, perform a full calibration sequence, and print the resulting glyph positions.
• The test will fail if the tower is not available or calibration does not complete within 60 seconds.
• Integration tests are not included in automated test runs or npm publish.

Prerequisites:

• Tower must be powered on and in Bluetooth range
• @stoprocent/noble must be installed (it is a peer dependency)

Development

Building and Testing

# Install dependencies
npm install

# Build the project
npm run build

# Run tests
npm test

# Run tests with coverage
npm run test:coverage

# Lint code
npm run lint

# Watch mode for development
npm run watch

Project Structure

src/
├── index.ts                  # Main exports
├── UltimateDarkTower.ts      # Main class
├── udtBluetoothAdapter.ts    # Bluetooth adapter interface & error types
├── udtBluetoothAdapterFactory.ts  # Platform auto-detection factory
├── udtBleConnection.ts       # Bluetooth connection management
├── udtTowerCommands.ts       # Tower command implementations
├── udtCommandFactory.ts      # Command creation utilities
├── udtCommandQueue.ts        # Command queue management
├── udtTowerResponse.ts       # Response handling
├── udtTowerState.ts          # Tower state management
├── udtHelpers.ts             # Utility helper functions
├── udtLogger.ts              # Logging system
├── udtConstants.ts           # Constants and type definitions
└── adapters/
    ├── WebBluetoothAdapter.ts    # Browser Web Bluetooth implementation
    └── NodeBluetoothAdapter.ts   # Node.js @stoprocent/noble BLE implementation

examples/
├── controller/               # Tower controller web app
├── game/                     # Tower game web app
├── node/                     # Node.js CLI example
└── assets/                   # Shared assets (images, fonts, etc.)

Platform Support

Built-in Support (auto-detected)

| Platform | Bluetooth Library | Notes | | -------------------------------- | ------------------------------------ | ---------------------------------------- | | Chrome / Edge / Samsung Internet | Web Bluetooth API | Desktop and Android | | Node.js | @stoprocent/noble | Requires npm install @stoprocent/noble | | Electron | Web Bluetooth or @stoprocent/noble | Auto-detects renderer vs main process |

Custom Adapter Support

| Platform | Recommended Library | Notes | | -------------------------- | ---------------------- | ----------------------------- | | React Native | react-native-ble-plx | Implement IBluetoothAdapter | | iOS (via React Native) | react-native-ble-plx | Same as React Native | | Android (via React Native) | react-native-ble-plx | Same as React Native | | Cordova / Capacitor | Platform BLE plugin | Implement IBluetoothAdapter |

Browser Support

iOS: Use the Bluefy app as Chrome/Safari does not support Web Bluetooth on Apple platforms.

Not Supported: Firefox, Safari (compatibility details)

Known Issues

• Sounds - Sounds show as command complete which is true even though the sound itself has not completed. This is just the way the tower works. I'll have to add time lengths to each at some point, just don't use the command complete response as a way of thinking the associated sound has finished playing and you can play another sound.
• Light Sequences - Same as sound for lights that play for a duration.

See Reference.md for performance best practices and workarounds.

Community

Questions? Ideas? Join us on our Discord Server!