Plugin Capabilities

Use this guide to choose a plugin contract and connect your implementation to HyperHQ. Use Plugin Repositories to publish installable packages.

Declare capabilities

Each manifest requires a nonempty capabilities array. Use structured entries:

{
  "capabilities": [
    {
      "name": "leaderboard-provider",
      "description": "Provides leaderboard and score operations",
      "required": true
    }
  ]
}

A descriptive name documents your plugin's purpose. A recognized host capability selects a specific contract. An arbitrary capability name creates no host method, permission, or runtime implementation. The required field does not grant access.

Capability	Host behavior
leaderboard-provider	Routes leaderboard metadata, reads, and score submissions through the selected provider.
media-provider-v1	Selects the versioned live media-provider contract. Development-only.
persistent-service	Keeps one service outside the ordinary dynamic-plugin eviction pool. The optional MCP integration uses this lifecycle behavior.

Settings and file pickers

Use key, type, and label for each setting. Set defaultValue, required, options, and validation where needed. Keep keys unique.

Supported types are string, number, boolean, email, password, url, textarea, select, oauth, array, object, file, directory, color, and range.

{
  "settings": [
    {
      "key": "romFolder",
      "type": "string",
      "label": "ROM folder",
      "browse": "directory",
      "defaultValue": ""
    }
  ]
}

Use file or directory for dedicated path settings. Use browse on a string setting for editable text plus a picker. Filter file selection with validation.fileTypes.

HyperHQ persists settings by plugin ID and refreshes runtime settings after saving. Active ordinary plugins receive updateSettings. Settings persistence and successful runtime application are separate outcomes; report an application failure through your response.

Actions and setup wizards

{
  "actions": [
    {
      "id": "sync_games",
      "label": "Sync games",
      "description": "Import the selected games",
      "icon": "fa-solid fa-arrows-rotate",
      "type": "secondary",
      "confirmation": true,
      "confirmationMessage": "Import the selected games?"
    }
  ]
}

The action sends execute with data.action: "sync_games". Return a structured result with success, message, and useful result data. HyperHQ displays action failures and result summaries. hidden: true hides the details-page action without disabling runtime execution.

Use type: "wizard" and wizard_id to open a declared onboarding wizard. Wizard steps support info, oauth, action, async-action, selection-list, and form. Form steps use the setting schema. Action steps use the onboarding/step-execute operation with step ID, step data, and session data.

Set wizard autoStart to "first-run" for initial setup, "always" for each discovery, or omit the field for explicit setup actions. true acts as first-run. HyperHQ saves progress and completion per plugin/wizard.

Generated interactive controls follow the host controller-navigation and accessibility requirements. Validate focus entry, every action, value adjustment, and focus restoration after a wizard or dialog closes.

Accounts and OAuth

An OAuth setting declares provider identity, authorization URL, accepted callback URLs, required callback parameters, and optional token exchange and status action fields. The host manages connection state, disconnect, expiry, and session artifacts through its OAuth service.

Use the fields in the developer guide. Surface expired authorization as a recoverable configuration error so users reconnect. Keep credentials, cookies, tokens, and full runtime settings out of logs and public diagnostics.

RetroAchievements also provides emulator sign-in through its plugin details and supported emulator settings. Users save the plugin username and Web API key, select detected emulators, review changes, and sign in. The host reuses verified login tokens without saving the password in plugin settings. DuckStation uses its own sign-in UI to preserve encrypted credentials. This behavior belongs to the RetroAchievements integration, rather than a generic capability name.

Runtime and transports

Ordinary executable plugins implement these methods:

Method	Purpose
initialize	Apply settings and plugin metadata, then report readiness.
execute	Run an action or operation.
test	Report health and configuration status.
shutdown	Stop work and release resources.
getSettings, updateSettings, getStatus	Handle host settings/status requests where implemented.

Correlate each response with the request ID. Keep stdio output as newline-delimited JSON and write diagnostics to stderr.

Socket.IO plugins use the injected HYPERHQ_SOCKET_PORT and HYPERHQ_AUTH_CHALLENGE. Authenticate before requests, keep the returned session token in memory, and attach the token to protected data/file calls. Follow the Socket.IO Guide for message envelopes and reconnect handling.

HyperHQ serializes starts per plugin ID. The manager permits two active ordinary dynamic plugins and stops the oldest when another starts. One persistent-service plugin runs separately; a second persistent service is rejected. Default and host-managed companion packages have separate lifecycle paths.

Current long-operation polling tracks Battle.net imports with an operation ID and get_operation_result. This handling is specific to battlenet-plugin. Other plugins must follow their own request deadlines and progress contracts.

Events and library operations

Subscribe through subscribeEvents and receive hyperHqEvent broadcasts. Canonical names are:

• frontendStarted, frontendClosing, hyperSpinReady
• systemChanged, wheelSelectionSettled
• gameSelected, gameLaunched, gameClosed
• attractModeEntered, attractModeExited

romSelected is a compatibility alias for gameSelected. Current native launch/close routing deduplicates lifecycle delivery and tears down subscriptions with the runtime.

Authenticated plugins also report notifications through pluginEvent, with the running instance ID, event ID, event type, session token, and object data. The host acknowledges through pluginEventAck, suppresses repeated event IDs within the same running instance, and limits serialized event data to 16 KiB. Notifications do not authorize library mutation or game launches.

The Socket.IO data-method allowlist includes system/game/media reads, system/emulator creation, game addition/removal, and game launch. MAME upgrade commit/status methods provide durable receipts. Fire-and-forget acknowledgements confirm dispatch, not completion. Use Plugin API Reference for existing transport details.

Storefront imports use the host library/media pipeline. Current integration work enriches supported PC game metadata, queues managed media downloads, preserves local artwork, and respects explicit download preferences. Provider-specific authentication and catalog mapping stay in each plugin.

Leaderboard providers

Advertise leaderboard-provider and implement the relevant methods:

• leaderboard.getProviderMetadata
• leaderboard.getLeaderboard
• leaderboard.getScore
• leaderboard.submitScore

HyperHQ chooses an explicit or saved provider plugin ID and routes requests through the manager. Provider authentication, external IDs, score formats, and service-specific errors belong in the plugin. A manifest declaration alone does not supply a provider implementation or score data.

Development-only contracts

Production availability is disabled for configured public repositories, live media-provider browsing, and local MCP automation. Development documentation below describes implemented contracts, not released functionality.

Live media providers

Advertise media-provider-v1. Startup negotiates media.v1.getCapabilities and requires contractVersion: 1, rather than ordinary initialization.

The contract covers authorization, discovery, browse/search/detail, artwork, playback start/progress/resume/stop, and cancellation. Providers declare supported operations and request/page limits.

providerManagedMedia: true declares provider-owned metadata/artwork. media-provider-v1 always implies this ownership, including legacy manifests or an explicit false value. Provider responses are not mirrored into the editable HyperHQ catalog. The provider browser disables metadata editing, media management, audits, and media/view-type selection. Display scaling affects presentation only.

Local MCP automation

The optional hyperhq-mcp plugin exposes a fixed authenticated tool set for approved library, settings, backup, and launch operations. The host derives topic grants from plugin settings and checks request identities, revisions, and operation results. General capability declarations do not grant access to this automation surface.

Permissions and platform support

Permission objects use type, scope, and description. Accepted types are file, network, system, database, process, and credential. Keep scopes nonempty and specific. Unrestricted system access is rejected.

Permissions provide disclosure and validation, not an OS sandbox. Executables run with the signed-in user's privileges. The JavaScript compatibility runner uses simulated isolation and includes incomplete data, UI, event, and file API implementations. Use executable plugins for independent integrations and verify every host API you depend on.

Declare platforms and the corresponding executableProviders. Validate Windows and Linux packaging, startup, authentication, settings, actions, failure cleanup, shutdown, and upgrades. Restore Linux executable permissions and verify runtime dependencies. Preserve supported macOS paths and validate macOS before advertising support.

Missing host declarations select HyperHQ. Add pluginHosts: ["hyperhq", "hyperspin"] only after implementing both host paths.

Source contracts

Source checked on September 27, 2026 against HyperHQ develop. Source and parameterized tests do not replace native package acceptance.

• Manifest types, actions, settings, and providers
• Plugin manager, lifecycle, settings, and Battle.net polling
• Authenticated events and data requests
• Native RetroAchievements sign-in and lifecycle integration
• Settings, actions, and onboarding UI improvements
• Live media-provider contract