Owl20 - Beyond20 to Owlbear Rodeo Bridge

A Browser extension that bridges Beyond20 dice roll data to Owlbear Rodeo iframes. This extension focuses purely on data transmission - it listens for Beyond20 events and passes the raw JSON data to iframes without any visual display.

For end users: Visit owl20.uberdragon.org for installation instructions and setup guide.

Chrome: Web Store · Edge: Add-ons · Firefox: Add-ons

Architecture Overview

Core Components

• Owl20Bridge Class: Main data bridge logic in content.js
• Event Listeners: Captures Beyond20 events (Beyond20_RenderedRoll, Beyond20_Roll, Beyond20_Loaded)
• Iframe Detection: Automatic scanning and monitoring via MutationObserver
• Data Transmission: Cross-origin iframe communication via postMessage

Data Flow

D&D Beyond → Beyond20 Extension → Owl20 Bridge → Owlbear Rodeo Owl20 Iframes

1. User makes roll in D&D Beyond character sheet
2. Beyond20 processes the roll and sends it to custom domains
3. Owl20 Bridge receives the Beyond20_RenderedRoll or Beyond20_Roll event
4. Bridge transmits the raw roll data to all detected iframes

Website Features

The Owl20 documentation website (owl20.uberdragon.org) features an immersive space-themed design:

• Twinkling Star Background: Animated starfield with 170 stars that randomly twinkle and glow
• Floating Container Animation: The main content container gently floats in space with subtle circular motions
• Modern UI: Clean, accessible design with smooth animations
• Accessibility: All animations respect prefers-reduced-motion settings

The starfield is implemented using pure CSS and JavaScript for optimal performance.

Development Setup

Prerequisites

• Chrome/Edge/Firefox browser
• Basic understanding of browser extensions and iframe communication
• Beyond20 extension for testing

Installation

1. Clone the repository:

   git clone https://github.com/uberdragon/owl20.git
   cd owl20

2. Load the extension in developer mode:

   • Open chrome://extensions/ (or equivalent for your browser)
   • Enable "Developer mode"
   • Click "Load unpacked" and select the project directory

3. Configure Beyond20 for testing:

   • Add https://www.owlbear.rodeo/* to Beyond20's custom domains
   • Visit an Owlbear Rodeo session to test

Technical Implementation

Event Handling

The extension listens for these Beyond20 events:

// Primary events captured
document.addEventListener('Beyond20_RenderedRoll', handleRoll);
document.addEventListener('Beyond20_Roll', handleRoll);
document.addEventListener('Beyond20_Loaded', handleLoaded);

Iframe Communication

Uses postMessage for cross-origin iframe communication:

// Send to cross-origin iframes
iframe.contentWindow.postMessage({
  type: 'Beyond20_Roll',
  data: rollData
}, '*');

Message Format

// PostMessage structure
{
  type: 'Beyond20_Roll',
  data: {
    character: 'Character Name',
    html: '<div>Roll HTML</div>',
    roll: {
      dice: '1d20',
      result: 15,
      total: 18
    },
    // ... other Beyond20 roll properties
  }
}

Project Structure

owl20/
├── manifest.json          # Extension manifest (Manifest V3)
├── content.js             # Main content script (Owl20Bridge class)
├── icons/                 # Extension icons (16px to 128px)
│   ├── owl20-16.png
│   ├── owl20-24.png
│   ├── owl20-32.png
│   ├── owl20-48.png
│   ├── owl20-96.png
│   └── owl20-128.png
├── package.json           # NPM package configuration
├── README.md             # This file
└── docs/                 # Website documentation
    ├── index.html        # User-facing documentation
    ├── css/
    │   ├── starfield.css # Twinkling star background styles
    │   └── styles.css    # Main website styling
    └── js/
        ├── script.js     # Website functionality
        └── starfield.js  # Animated starfield implementation

Key Classes and Methods

Owl20Bridge Class

class Owl20Bridge {
  constructor() {
    this.iframes = [];
    this.init();
  }
  
  // Core methods
  init()                    // Initialize event listeners and find iframes
  setupEventListeners()    // Set up Beyond20 event listeners
  observeIframes()          // Watch for iframe changes via MutationObserver
  findIframes()             // Find existing iframes on page
  addIframe(iframe)         // Add iframe to tracking array
  removeIframe(iframe)       // Remove iframe from tracking array
  isValidIframe(iframe)     // Validate iframe before use
  shouldIncludeIframe(iframe) // Check if iframe should be tracked
  handleBeyond20Roll(rollData) // Process Beyond20 roll events
  sendToIframes(rollData)   // Send data to all valid iframes
}

Testing

Manual Testing

1. Setup Test Environment:

   • Install Beyond20 extension
   • Configure Beyond20 with https://www.owlbear.rodeo/*
   • Load Owl20 extension in developer mode

2. Test Scenarios:

   • Cross-origin iframe communication via postMessage
   • Dynamic iframe detection and removal
   • Multiple iframe handling
   • Scene changes in Owlbear (iframe replacement)
   • Error handling and edge cases (null contentWindow, stale references)

3. Debug Tools:

   • Browser DevTools Console
   • Extension DevTools
   • Network tab for postMessage debugging

Integration Testing

Test with the Owl20-Owlbear OBR Extension:

1. Install both extensions
2. Create Owlbear Rodeo session
3. Enable Owl20 OBR extension in room
4. Make rolls from D&D Beyond character sheet
5. Verify data appears in Owlbear Rodeo

Browser Compatibility

• Chrome: Manifest V3 support
• Edge: Chromium-based (full compatibility)
• Firefox: WebExtensions API
• Other Chromium browsers: Should work with Manifest V3 support

Contributing

Development Workflow

1. Fork and Clone:

   git clone https://github.com/your-username/owl20.git
   cd owl20

2. Create Feature Branch:

   git checkout -b feature/your-feature-name

3. Make Changes:

   • Follow existing code style
   • Add comments for complex logic
   • Test thoroughly with Beyond20 and Owlbear Rodeo

4. Test Your Changes:

   • Load extension in developer mode
   • Test all communication scenarios
   • Verify error handling

5. Submit Pull Request:

   • Clear description of changes
   • Reference any related issues
   • Include testing notes

Code Style Guidelines

• Use meaningful variable and function names
• Add comments for complex iframe detection logic
• Follow existing event handling patterns
• Maintain backward compatibility with Beyond20 events

Areas for Contribution

• Performance: Optimize iframe detection and scanning
• Error Handling: Improve edge case handling
• Browser Support: Add support for additional browsers
• Testing: Add automated test suite
• Documentation: Improve API documentation

Troubleshooting Development Issues

Common Development Problems

1. Extension Not Loading:

   • Check manifest.json syntax
   • Verify file paths in manifest
   • Check browser console for errors

2. Events Not Firing:

   • Verify Beyond20 is configured correctly
   • Check if you're on an Owlbear Rodeo page
   • Use console.log to debug event listeners

3. Iframe Communication Issues:

   • Verify iframe is fully loaded before sending messages
   • Check for stale iframe references (especially after Owlbear scene changes)
   • Use DevTools to inspect postMessage events
   • Check console for "Removing invalid Owl20 iframe" warnings

Debugging Tools

• Browser DevTools: Console, Network, Sources tabs
• Extension DevTools: chrome://extensions/ → Details → Inspect views
• Beyond20 Debug: Check Beyond20 console messages
• PostMessage Debug: Monitor window message events

License

MIT License - see LICENSE file for details.

Support

• Issues: GitHub Issues
• User Documentation: owl20.uberdragon.org
• OBR Extension: Owl20-Owlbear Repository