Skip to main content

Plugins

Extend HyperHQ with custom features and integrations.

What Are Plugins?​

Plugins are add-ons that extend HyperHQ's functionality without needing to modify the core app. Think of them like browser extensions or smartphone apps—small programs that add specific features you want.

What can plugins do?

  • Sync your library with external services (Steam, GOG, etc.)
  • Automatically download and organize media
  • Add custom game metadata or ratings
  • Integrate LED controllers and other hardware
  • Export data to other tools
  • Automate repetitive tasks
  • Connect to cloud storage for backups

Plugins run separately from HyperHQ, so if one crashes or has issues, it won't take down your whole setup. They communicate with HyperHQ through a secure interface, keeping everything isolated and safe.

Why Use Plugins?​

Save Time Automate tasks like scanning for new games, downloading artwork, or updating metadata. Let plugins do the boring stuff while you focus on playing.

Add Features Want something HyperHQ doesn't have built-in? Chances are there's a plugin for it. Need to sync with a specific service? Someone's probably made a plugin.

Keep It Simple Only install what you need. Don't want LED integration? Don't install those plugins. HyperHQ stays lean and fast.

Community Power The HyperSpin community builds plugins for all kinds of use cases. You benefit from their work, and if you're technical, you can contribute your own.

Installing Plugins​

HyperHQ makes it easy to browse and install plugins from the built-in plugin manager.

Using the Plugin Manager​

  1. Open the Plugin Manager

    • Click Settings in the bottom-left corner
    • Select Plugins from the sidebar
    • You'll see two tabs: Installed and Available

  2. Browse Available Plugins

    • Switch to the Available tab
    • Scroll through the list or use the search box
    • Each plugin shows:
      • Name and description
      • Author and version
      • What it does
      • How many people are using it
      • User ratings (if available)

  3. Install a Plugin

    • Click on a plugin to see more details
    • Read the description and check the permissions
    • Click Install
    • HyperHQ downloads and installs it automatically
    • The plugin appears in your Installed tab

  4. Configure the Plugin

    • After installing, click Settings next to the plugin
    • Fill in any required information (API keys, paths, preferences)
    • Click Save
    • The plugin is now active and ready to use

Automatic Updates​

By default, HyperHQ keeps your plugins up to date automatically.

How it works:

  • HyperHQ checks for plugin updates when you launch the app
  • If an update is available, it downloads in the background
  • Updates install automatically the next time you restart HyperHQ
  • You'll see a notification when updates are ready

Controlling updates:

  • Go to Settings > Plugins
  • Click the gear icon in the top-right
  • Toggle Auto-Update Plugins on or off
  • You can also disable auto-updates for individual plugins
Update Notifications

HyperHQ shows a small badge on the Plugins icon when updates are available. Click to see what's new before installing.

Manual Installation​

Sometimes you'll get a plugin directly from a developer or the community forums. Here's how to install it manually:

  1. Get the Plugin File

    • Plugins are distributed as ZIP files
    • Download it to a location you can find (like Downloads)

  2. Install It

    • Open Settings > Plugins
    • Click the Install from File button
    • Browse to the ZIP file and select it
    • HyperHQ extracts and installs the plugin

  3. Verify It Loaded

    • Check the Installed tab
    • Your new plugin should appear in the list
    • If it doesn't, check the logs for errors
Security Warning

Only install plugins from trusted sources. Plugins can access your game library, files, and network. Download from the official plugin manager when possible.

Uninstalling Plugins​

Don't need a plugin anymore? Removing it is easy.

  1. Open Plugin Manager

    • Go to Settings > Plugins
    • Switch to the Installed tab

  2. Remove the Plugin

    • Find the plugin you want to remove
    • Click the trash icon or Uninstall button
    • Confirm when asked

  3. Clean Up (Optional)

    • HyperHQ removes the plugin files
    • Settings and data are preserved in case you reinstall later
    • To completely remove everything, check the Delete all data option before uninstalling

Plugin Types​

HyperHQ supports different types of plugins depending on what they need to do.

JavaScript Plugins​

What they are: Small scripts that run directly inside HyperHQ. These are usually simple utilities or UI enhancements.

Pros:

  • Install instantly (no downloading executables)
  • Can customize the HyperHQ interface
  • Easy for developers to create and share
  • Work on any platform

Cons:

  • Limited to what JavaScript can do
  • Can't access low-level system features
  • Slower for heavy processing

Common uses:

  • Custom themes or UI tweaks
  • Simple data transformations
  • Display enhancements
  • Quick utilities

Executable Plugins​

What they are: Standalone programs (.exe files) that run alongside HyperHQ. These can be written in any programming language.

Pros:

  • Can do anything a normal program can
  • Fast processing for complex tasks
  • Can integrate with external tools
  • Work with hardware directly

Cons:

  • Larger download size
  • Platform-specific (Windows only for most)
  • Take longer to start up

Common uses:

  • Media scrapers and downloaders
  • Database sync tools
  • Hardware integration (LED controllers, etc.)
  • Heavy data processing
  • External service integrations

How Plugins Communicate​

Plugins talk to HyperHQ through a secure communication system. Here's what happens behind the scenes:

Socket.IO Connection​

Most plugins use Socket.IO for real-time, two-way communication with HyperHQ.

How it works:

  1. HyperHQ starts a local server (on your computer only)
  2. Plugins connect to this server
  3. They authenticate using a secret challenge
  4. Once verified, they can send and receive messages

What this means for you:

  • Plugins can respond instantly to changes
  • They receive real-time updates when you add games or change settings
  • You get live progress updates for long operations
  • No internet required—everything happens locally

Port 52789 By default, HyperHQ's plugin server runs on port 52789. If something else is using that port, you can change it in Settings > Advanced > Plugin Port.

Authentication and Security​

When a plugin starts, HyperHQ gives it a unique challenge code. The plugin must send this code back to prove it was launched by HyperHQ (not some random program trying to connect).

This keeps you safe:

  • Random programs can't connect to HyperHQ
  • Each plugin gets a unique session
  • Sessions expire when the plugin closes
  • You control which plugins can access what

Plugin Settings​

Every plugin can have its own settings and preferences.

Accessing Settings​

  1. Go to Settings > Plugins
  2. Find your plugin in the Installed list
  3. Click the Settings button
  4. A panel opens with the plugin's options

Common Settings​

API Keys Many plugins need API keys to access external services. You'll typically get these from the service's website, then paste them into the plugin settings.

File Paths Plugins that work with media or ROMs often need to know where your files are. Point them to the right folders.

Sync Intervals If a plugin checks for updates automatically, you can usually control how often it runs.

Display Options Some plugins add elements to the UI. You can often control what they show and where.

Saving Changes​

Click Save after changing settings. Some plugins need to restart for changes to take effect—HyperHQ will tell you if that's the case.

Plugin Data​

Plugins can store their own data separate from HyperHQ's main database.

Where Data Lives​

Each plugin gets its own data folder:

C:\ProgramData\HyperSpin\HyperHQ\plugins\plugin-name\data\

What's stored:

  • Cache files
  • Downloaded media
  • Temporary data
  • Plugin databases
  • Configuration files

Managing Plugin Data​

View Data Folder

  • Right-click a plugin in the Plugin Manager
  • Select Open Data Folder
  • Windows Explorer opens to that location

Clear Cache

  • Some plugins have a Clear Cache button in settings
  • This removes temporary files but keeps your configuration
  • Useful if things seem stuck or outdated

Backup Important Data

  • If a plugin stores valuable data, back up its folder
  • Copy the entire plugin data folder somewhere safe
  • Restore it if you reinstall or move to a new computer
Storage Space

Plugin data can add up over time, especially if they cache media. Check the data folders occasionally and clear old stuff you don't need.

Creating Your Own Plugins​

Feeling adventurous? You can create your own plugins to add exactly the features you want.

What You Need to Know​

Programming Skills You'll need to know at least one programming language. The easiest options:

  • Python - Beginner-friendly, lots of libraries
  • JavaScript - Good if you know web development
  • C# - Great for Windows, fast performance
  • Go - Simple and efficient

HyperHQ Plugin API Plugins use HyperHQ's API to interact with game data, settings, and the UI. The documentation for developers is at the Plugin Development Guide.

Quick Start​

  1. Pick a Template

    • HyperHQ provides starter templates in several languages
    • These include all the boilerplate code
    • Just add your custom logic

  2. Build Your Plugin

    • Follow the template's README
    • Test it manually first
    • Use the built-in validator to check for issues

  3. Install and Test

    • Install your plugin using the manual installation method
    • Test all the features
    • Check error logs if something doesn't work

  4. Share It (Optional)

    • If your plugin is useful, share it with the community
    • Post on the HyperSpin forums
    • Submit it to the plugin directory
Developer Resources

For full plugin development documentation, see the Plugin Development Guide. It includes templates, API reference, and step-by-step tutorials.

Troubleshooting Plugins​

Sometimes plugins don't work quite right. Here's how to fix common issues.

Plugin Won't Install​

Check the file:

  • Make sure you downloaded the complete file
  • Try re-downloading if it seems corrupted
  • Verify it's a .zip file for HyperHQ plugins

Look at the logs:

  • Go to Settings > View Logs
  • Check for installation errors
  • Common issues: missing files, wrong structure, incompatible version

Version compatibility:

  • Check if the plugin supports your HyperHQ version
  • Some plugins require newer versions
  • Update HyperHQ if needed

Plugin Not Working​

Restart HyperHQ: The classic fix. Some plugins need a fresh start to initialize properly.

Check plugin status:

  • Go to Settings > Plugins
  • Look for error icons next to the plugin name
  • Click for details about what went wrong

Review settings:

  • Open the plugin's settings
  • Make sure required fields are filled in
  • Verify API keys are correct
  • Check file paths exist

Check permissions:

  • Some plugins need network access
  • Others need file system permissions
  • Windows might be blocking the plugin executable
  • Right-click the plugin in Installed > Permissions to review

Plugin Crashes​

View crash logs:

  • Settings > View Logs > Plugin Logs
  • Find the log file for your plugin
  • Look for error messages near the end

Disable and re-enable:

  • Right-click the plugin > Disable
  • Wait a few seconds
  • Right-click > Enable
  • See if it starts cleanly

Clear plugin data:

  • Right-click > Open Data Folder
  • Rename or delete cache files
  • Restart HyperHQ
  • The plugin will regenerate fresh data

Reinstall:

  • Uninstall the plugin (keep settings if offered)
  • Reinstall from the plugin manager
  • Re-enter your settings

Plugin Running Slow​

Check what it's doing:

  • Some plugins do heavy processing (scanning thousands of files, downloading media)
  • This is normal—give it time
  • Look for progress indicators

Reduce frequency:

  • If the plugin auto-syncs, increase the interval
  • Daily instead of hourly, for example

Limit scope:

  • Some plugins let you limit what they process
  • Exclude systems you don't need
  • Process smaller batches

Can't Connect to Plugin Server​

Error: "Cannot connect to plugin server on port 52789"

Check if port is available:

  • Another program might be using port 52789
  • Change the port in Settings > Advanced > Plugin Port
  • Pick something like 52790 or 52800
  • Restart HyperHQ

Firewall issues:

  • Windows Firewall might be blocking local connections
  • Add an exception for HyperHQ
  • The connection is local-only (doesn't go to the internet)

Restart the plugin service:

  • Settings > Advanced > Restart Plugin Service
  • Wait a moment for it to restart
  • Try the plugin again

Finding Community Plugins​

The HyperSpin community creates tons of useful plugins. Here's where to find them.

Official Plugin Directory​

Built into HyperHQ:

  • The Available tab in the Plugin Manager
  • Curated and tested plugins
  • Safe to install
  • Automatic updates

Browse by category:

  • Media tools
  • Integration services
  • Hardware support
  • Utilities
  • Themes and UI

Community Forums​

HyperSpin-fe.com Forums:

  • Check the "Plugins and Extensions" section
  • Developers share new plugins here first
  • You can request features or report issues
  • Beta versions available for testing

Discord:

  • Join the HyperSpin Discord server
  • #plugins channel for discussions
  • Get help from plugin authors
  • Share your own creations

GitHub and Other Sources​

Some developers host plugins on GitHub or their own websites.

Installing from external sources:

  • Download the ZIP file
  • Use Install from File in the Plugin Manager
  • Read the README for setup instructions

Stay safe:

  • Only install from trusted sources
  • Check user reviews and ratings
  • Ask in the forums if you're unsure
  • Scan downloads with antivirus if you're cautious

Here are some commonly used plugins to get you started:

EmuMovies Sync​

Automatically downloads gameplay videos and extra artwork from EmuMovies (requires EmuMovies account).

Steam Integration​

Imports your Steam library as a HyperSpin system, complete with artwork and metadata.

LEDBlinky Integration​

Controls LED lighting on your arcade cabinet, syncing with games and systems.

Auto-Scraper​

Scans your ROM folders and downloads missing media from multiple sources.

Backup Manager​

Automatically backs up your HyperSpin configuration to cloud storage.

RetroAchievements​

Displays achievement progress and unlocks for supported games.

Start Small

Don't install every plugin at once. Add one or two that solve specific problems, get familiar with how they work, then expand from there.

Best Practices​

A few tips to get the most out of plugins:

Read the descriptions: Know what a plugin does before installing. Some might duplicate features or conflict with others.

Check reviews: See what other users say. High ratings usually mean stable, useful plugins.

Keep them updated: Enable auto-updates unless you have a specific reason not to. Bug fixes and new features are good.

Don't go overboard: More plugins means more overhead. Stick to the ones you actually use.

Monitor performance: If HyperHQ starts running slowly, disable plugins one by one to find the culprit.

Back up your setup: Before installing a bunch of plugins, back up your HyperSpin folder. Makes it easy to roll back if something breaks.

What's Next?​

Now that you know how plugins work, explore the Plugin Manager and see what's available. Install a few that sound useful and see how they improve your workflow.

Want to build your own? Check out the Plugin Development Guide for templates, tutorials, and API documentation.

Need help? Visit the HyperSpin community forums or the Troubleshooting guide.

Plugins are one of HyperHQ's most powerful features—use them to make your arcade setup exactly what you want it to be.