HyperHQ Plugin Developer Onboarding

This page is the short path into HyperHQ plugin development. If you already know your way around a terminal and one programming language, you have enough to start.

HyperHQ supports JavaScript plugins and executable plugins. Executable plugins use stdin/stdout or authenticated Socket.IO, according to the manifest and available transport. Your plugin.json defines the entry point, settings, actions, and requested permissions.

What You Can Build

Plugin Type	Examples	Good First Project?
Utilities	File organizers, backup tools, ROM scanners	Yes
Media tools	Image processors, video helpers, artwork cleanup	Yes, if the scope is small
Arcade hardware	LED controllers, marquee displays, cabinet devices	Better after one basic plugin
Game integrations	MAME setup, Steam import, GOG import	More moving parts
Custom interfaces	Web dashboards, mobile controllers, companion tools	Advanced

Pick a Starting Point

Python

Good for the first pass, quick scripts, and plugins that lean on existing libraries.

wget https://docs.hyperai.io/downloads/templates/python-starter.zip
unzip python-starter.zip
cd python-starter

python3 -m venv .venv
. .venv/bin/activate
python -m pip install pyinstaller 'python-socketio[client]'
python -m PyInstaller --onefile plugin.py

JavaScript / Node.js

Good if you are already comfortable with async code and package tooling.

wget https://docs.hyperai.io/downloads/templates/nodejs-starter.zip
unzip nodejs-starter.zip
cd nodejs-starter

npm install
npm run build
npm test

C#

Use C# for .NET integrations and hardware tools with drivers for your target operating system.

wget https://docs.hyperai.io/downloads/templates/csharp-starter.zip
unzip csharp-starter.zip
cd csharp-starter

dotnet publish -c Release -r linux-x64 --self-contained true
# On Windows, use -r win-x64

Use the Linux template steps to install the published executable and set its manifest entry. Confirm authentication and an action in HyperHQ.

The Basic Contract

1. Your Plugin Handles a Few Methods

HyperHQ sends method calls over Socket.IO. Most plugins start with these:

class MyPlugin:
    def initialize(self, settings):
        return "initialized"

    def execute(self, action_data):
        return {"success": True}

    def test(self, _):
        return True

    def shutdown(self, _):
        return "ok"

2. Socket.IO Uses Request and Response

HyperHQ sends:

{"id":"123","method":"execute","data":{"action":"scan_files","path":"/roms"}}

Your plugin responds:

{"id":"123","type":"response","data":{"files_found":1337}}

For longer work, send short status updates while the request is still running:

{"status":"scanning","message":"Scanned 400 of 1200 files"}

That maps to the statusUpdate Socket.IO event.

3. Settings Come from the Manifest

Define settings in plugin.json; HyperHQ renders the settings UI.

{
  "settings": [
    {"key": "apiKey", "label": "API Key", "type": "string"},
    {"key": "enabled", "label": "Enable", "type": "boolean"},
    {"key": "romPath", "label": "ROM Path", "type": "directory"}
  ]
}

The field is label, not name. Keep keys stable once users might have saved settings.

Developer Resources

Resource	Use It For
Plugin Developer Guide	A full tutorial and examples
Socket.IO Guide	Connection, authentication, events, and data requests
API Reference	Method and payload lookup
Architecture Overview	The deeper design notes

Templates

Language	Download	Best For
Python	python-starter.zip	First plugin, quick automation
Node.js	nodejs-starter.zip	Async integrations
C#	csharp-starter.zip	.NET tooling on Windows or Linux
Go	go-starter.zip	Small native executables

Each starter gives you a working plugin, build instructions, example settings, and enough structure to start changing behavior without rebuilding the whole project.

Common Questions

Do I need to know HyperHQ internals?

No. The plugin boundary is Socket.IO plus plugin.json. You can build useful plugins without touching the HyperHQ app code.

What if my plugin crashes?

Plugins run in separate processes, so a crash should not take HyperHQ down. Make sure you log enough context to debug the failure afterward.

Can I access HyperHQ data?

Yes. Use requestData for supported methods such as getSystems, getGamesForSystem, addGames, and launchGame.

How do I handle long-running operations?

Send statusUpdate messages with a concise status and message. HyperHQ uses those updates to keep active plugin requests alive and show useful progress.

How do I distribute a plugin?

Package the manifest, executable, and any supporting files as a ZIP. Keep the folder layout simple and test the ZIP before sharing it.

Next Steps

1. Pick a template in a language you already know.
2. Build and run the sample plugin unchanged.
3. Open the Socket.IO guide and compare the sample code to the real event names.
4. Change one action or setting.
5. Package the plugin and test the ZIP.

Small first plugin, boring test loop, fewer surprises. That is usually the quickest route.