API Reference

API Reference

window.GD - Plugin Runtime API

All plugin Vue components access GD internals via window.__GD__:

const _gd = (window as any).__GD__

Stores

const auth = _gd.stores.auth()       // { user } - JWT token blocked for security
const socket = _gd.stores.socket()   // { syncProgress } - raw socket blocked
const theme = _gd.stores.theme()     // Full theme store

auth store - user object with: id, username, email, role, avatar_path theme store - themeId, skinId, animations, ambient, coverSize, heroBlur, etc.

API Client

const client = _gd.api  // Axios instance with Bearer token auto-attached

// GET
const { data } = await client.get('/roms/platforms')

// POST
await client.post('/plugins/store/install', { downloadUrl: '...' })

i18n

const t = _gd.i18n?.t || ((k: string) => k)

t('nh.my_key')                    // Returns translated string
t('nh.count', { count: 5 })      // With parameter interpolation
_gd.i18n.locale                   // Current locale (readonly ref)
_gd.i18n.setLocale('pl')          // Change locale
_gd.i18n.merge({ en: {}, pl: {} }) // Merge plugin translations

Notifications

// Add badge to user avatar
_gd.notifications.add({
  id: 'my-alert',           // Unique ID
  count: 1,                 // Badge number (0 = dot only)
  label: 'Something',       // Text in popup
  details: ['line 1'],      // Optional detail lines
  action: '/settings',      // Optional: navigate on click
  actionLabel: 'Go',        // Optional: button label
})

_gd.notifications.dismiss('my-alert')  // Hide until session restart
_gd.notifications.remove('my-alert')   // Remove permanently
_gd.notifications.store                // Reactive Pinia store

Composables

const { useCouchNav, couchNavPaused } = _gd.composables

// Couch Mode navigation
useCouchNav({
  left:    () => {},  // D-pad left / Arrow left
  right:   () => {},  // D-pad right / Arrow right
  up:      () => {},  // D-pad up / Arrow up
  down:    () => {},  // D-pad down / Arrow down
  confirm: () => {},  // A button / Enter
  back:    () => {},  // B button / Escape
  menu:    () => {},  // Start button / M key
})

// Pause during overlays
couchNavPaused.value = true

// Couch theme
const { theme, view, setTheme, setView } = _gd.composables.useCouchTheme()

Utilities

// EmulatorJS core mapping
const core = _gd.getEjsCore('snes')  // Returns 'snes9x' or null

// Theme registration (auto-called for compiled plugins)
_gd.registerTheme(themeDefinition)
_gd.registerPluginLayout('my-theme', LayoutComponent)
_gd.registerPluginCouchMode('my-theme', CouchComponent)

Global Components

Available in all plugin Vue templates:

• <DownloadManager /> - Download queue tray (admin only)
• <RandomGamePicker /> - Random game dice button
• <AmbientBackground /> - Animated orb background

Backend Hook Specs

MetadataProviderSpec

Hook	Signature	Returns
metadata_provider_name	() -> str	Display name
metadata_provider_id	() -> str	Unique ID
metadata_search_game	(query: str) -> list[dict]	Search results
metadata_get_game	(provider_game_id: str) -> dict	Full metadata
metadata_get_cover_url	(provider_game_id: str) -> str	Cover URL

LifecycleSpec

Hook	Signature	Returns
lifecycle_on_startup	() -> None	-
lifecycle_on_shutdown	() -> None	-
lifecycle_on_game_added	(game: dict) -> None	-
lifecycle_on_download_complete	(game: dict, path: str) -> None	-

FrontendProviderSpec

Hook	Signature	Returns
frontend_get_theme	() -> dict	Theme definition
frontend_get_css	() -> str	CSS overrides
frontend_get_js	() -> str	JavaScript effects

WidgetSpec

Hook	Signature	Returns
widget_get_cards	() -> list[dict]	Dashboard cards

DownloadProviderSpec

Hook	Signature	Returns
download_provider_name	() -> str	Display name
download_provider_id	() -> str	Unique ID
download_can_handle	(game_id: int) -> bool	Can download?
download_start	(game_id: int, dest: str) -> dict	Start download
download_get_status	(task_id: str) -> dict	Check progress

LibrarySourceSpec

Hook	Signature	Returns
library_source_name	() -> str	Display name
library_source_id	() -> str	Unique ID
library_scan	(path: str) -> list[dict]	Discovered games

Backend Endpoints

Plugin i18n

GET /api/plugins/frontend/i18n - Returns merged translations from all plugin i18n.json files. Auto-called on app startup.

Plugin Store Updates

GET /api/plugins/store/updates - Check for plugin updates (cached 5 min). Returns { count, updates: [{id, name, installed, available}] }

Plugin Assets

GET /api/plugins/{plugin-id}/assets/{path} - Serve static files from plugin assets/ directory. Supported types: .webp, .png, .jpg, .svg, .xml, .json

Container Restart

POST /api/plugins/restart - Gracefully restart container (admin only). Used after theme plugin install to recompile Vue files.