Skip to main content

Plugin Data Flow Guide

Simple visual guide showing how your plugin requests and receives data from HyperHQ.

How Data Requests Work​

Getting System Information​

When your plugin needs to know what game systems exist:

What you get back:

  • System name (e.g., "Nintendo 64")
  • Platform (e.g., "Nintendo 64")
  • Number of games in system
  • File extensions allowed
  • Unique system ID

Getting Media Folder Paths​

When your plugin needs to know where to save artwork:

What you get back:

  • Boxart folder path
  • Background folder path
  • Screenshot folder path
  • Logo folder path
  • Video folder path
  • Any custom media folders

Creating a New System​

When your plugin wants to add a new game system:

What you send:

  • System name
  • Platform name
  • Allowed file extensions
  • Optional: Description, emulator info

What you get back:

  • Success confirmation
  • New system ID
  • Or error message if something went wrong

Adding Games to a System​

When your plugin wants to add games:

What you send:

  • System ID
  • Array of games with:
    • Game name
    • File name
    • File path
    • Optional: Developer, publisher, year, genre, rating

What you get back:

  • Number of games added successfully
  • Number of games skipped (if any)
  • Any error messages

Complete Plugin Workflow Example​

Here's how a typical plugin syncs games from an external service:

Request Types at a Glance​

Read Requests (Get Data)​

  • getSystems - Get list of all game systems
  • getMediaFolders - Get folder paths for media

These return data immediately for you to use.

Write Requests (Create/Update Data)​

  • createSystem - Add a new game system
  • createEmulator - Add emulator configuration
  • addGames - Add games to a system

These confirm success or return error messages.

Error Handling Flow​

Best Practices:

  • Always check if request succeeded
  • Log errors for debugging
  • Show user-friendly messages
  • Retry failed requests (with limits)
  • Don't crash if one request fails

Data Flow Timing​

What this means:

  • Requests are fast (usually < 1 second)
  • Your plugin waits while HyperHQ processes
  • Once you get data back, you can use it immediately
  • For long operations, HyperHQ sends progress updates

Simple Request Example​

Here's the simplest possible data request:

That's it! Every data request follows this simple pattern:

  1. You ask for data
  2. HyperHQ processes your request
  3. You receive the response
  4. You use the data

Quick Reference​

What You WantRequest MethodWhat You Get Back
List of game systemsgetSystemsArray of systems with names, IDs, platforms
Where to save artworkgetMediaFoldersFolder paths for each media type
Add a new systemcreateSystemSuccess + new system ID
Add an emulatorcreateEmulatorSuccess + new emulator ID
Add gamesaddGamesNumber of games added successfully

Remember: All these requests happen automatically in the background. HyperHQ handles the complexity—you just send simple requests and get back the data you need!

For code examples, see: