[Feat] Passing arguments via protocol URLs (#4186)

* Introduce param-style protocol URLs

Using URL parameters (`?foo=bar`) to specify options in protocol URLs makes them
easier to extend/change later, and allows us to add features like launch
parameters (which may be specified multiple times)

"Old-style" URLs of course still work

* Add support for passing parameters via protocol

The new `arg` parameter can be used (multiple times if necessary) to specify
extra parameters to pass to runners/the game

Author: CommandMC

src/backend/launcher.ts

@@ -101,7 +101,8 @@ const launchEventCallback: (args: LaunchParams) => StatusPromise = async ({
   appName,
   launchArguments,
   runner,
-  skipVersionCheck
+  skipVersionCheck,
+  args
 }) => {
   const game = gameManagerMap[runner].getGameInfo(appName)
   const gameSettings = await gameManagerMap[runner].getSettings(appName)
@@ -203,6 +204,7 @@ const launchEventCallback: (args: LaunchParams) => StatusPromise = async ({
   const command = gameManagerMap[runner].launch(
     appName,
     launchArguments,
+    args,
     skipVersionCheck
   )
 

src/backend/protocol.ts

@@ -1,195 +1,122 @@
 import { dialog } from 'electron'
 import { logError, logInfo, LogPrefix } from './logger/logger'
 import i18next from 'i18next'
-import { getInfo } from './utils'
 import { GameInfo, Runner } from 'common/types'
 import { getMainWindow, sendFrontendMessage } from './main_window'
 import { icon } from './constants'
 import { gameManagerMap } from './storeManagers'
 import { launchEventCallback } from './launcher'
+import { z } from 'zod'
 
-type Command = 'ping' | 'launch'
+const RUNNERS = z.enum(['legendary', 'gog', 'nile', 'sideload'])
 
-const RUNNERS = ['legendary', 'gog', 'nile', 'sideload']
+export function handleProtocol(args: string[]) {
+  const urlStr = args.find((arg) => arg.startsWith('heroic://'))
+  if (!urlStr) return
 
-/**
- * Handles a protocol request
- * @param args The args to search
- * @example
- * handleProtocol(['heroic://ping'])
- * // => 'Received ping! Arg: undefined'
- * handleProtocol(['heroic://launch/gog/123'])
- * // => 'Received launch! Runner: gog, Arg: 123'
- **/
-export async function handleProtocol(args: string[]) {
-  const mainWindow = getMainWindow()
-
-  const url = getUrl(args)
-  if (!url) {
-    return
-  }
-
-  const [command, runner, arg = ''] = parseUrl(url)
+  const url = new URL(urlStr)
 
-  logInfo(`received '${url}'`, LogPrefix.ProtocolHandler)
+  logInfo(['Received', url.href], LogPrefix.ProtocolHandler)
 
-  switch (command) {
+  switch (url.hostname) {
     case 'ping':
-      return handlePing(arg)
+      return handlePing(url)
     case 'launch':
-      await handleLaunch(runner, arg, mainWindow)
-      break
+      return handleLaunch(url)
     default:
       return
   }
 }
 
-/**
- * Gets the url from the args
- * @param args The args to search
- * @returns The url if found, undefined otherwise
- * @example
- * getUrl(['heroic://ping'])
- * // => 'heroic://ping'
- * getUrl(['heroic://launch/gog/123'])
- * // => 'heroic://launch/gog/123'
- * getUrl(['heroic://launch/legendary/123'])
- * // => 'heroic://launch/legendary/123'
- **/
-function getUrl(args: string[]): string | undefined {
-  return args.find((arg) => arg.startsWith('heroic://'))
+function handlePing(url: URL) {
+  logInfo(['Received ping! Args:', url.searchParams], LogPrefix.ProtocolHandler)
 }
 
-/**
- * Parses a url into a tuple of [Command, Runner?, string?]
- * @param url The url to parse
- * @returns A tuple of [Command, Runner?, string?]
- * @example
- * parseUrl('heroic://ping')
- * // => ['ping', undefined, undefined]
- * parseUrl('heroic://launch/gog/123')
- * // => ['launch', 'gog', '123']
- * parseUrl('heroic://launch/123')
- * // => ['launch', '123']
- **/
-function parseUrl(url: string): [Command, Runner?, string?] {
-  const [, fullCommand] = url.split('://')
-
-  //check if the second param is a runner or not and adjust parts accordingly
-  const hasRunner = RUNNERS.includes(fullCommand.split('/')[1] as Runner)
-  if (hasRunner) {
-    const [command, runner, arg] = fullCommand.split('/')
-    return [command as Command, runner as Runner, arg]
+async function handleLaunch(url: URL) {
+  let appName
+  let runnerStr
+  let args: string[] = []
+
+  if (url.pathname) {
+    // Old-style pathname URLs:
+    // - `heroic://launch/Quail`
+    // - `heroic://launch/legendary/Quail`
+    const splitPath = url.pathname.split('/').filter(Boolean)
+    appName = splitPath.pop()
+    runnerStr = splitPath.pop()
   } else {
-    const [command, arg] = fullCommand.split('/')
-    return [command as Command, undefined, arg]
+    // New-style params URL:
+    // `heroic://launch?appName=Quail&runner=legendary&arg=foo&arg=bar`
+    appName = url.searchParams.get('appName')
+    runnerStr = url.searchParams.get('runner')
+    args = url.searchParams.getAll('arg')
   }
-}
 
-async function handlePing(arg: string) {
-  return logInfo(['Received ping! Arg:', arg], LogPrefix.ProtocolHandler)
-}
+  if (!appName) {
+    logError('No appName in protocol URL', LogPrefix.ProtocolHandler)
+    return
+  }
 
-/**
- * Handles a launch command
- * @param runner The runner to launch the game with
- * @param arg The game to launch
- * @param mainWindow The main window
- * @example
- * handleLaunch('gog', '123')
- * // => 'Received launch! Runner: gog, Arg: 123'
- * handleLaunch('legendary', '123')
- * // => 'Received launch! Runner: legendary, Arg: 123'
- * handleLaunch('nile', '123')
- * // => 'Received launch! Runner: nile, Arg: 123'
- **/
-async function handleLaunch(
-  runner: Runner | undefined,
-  arg: string | undefined,
-  mainWindow?: Electron.BrowserWindow | null
-) {
-  const game = await findGame(runner, arg)
-
-  if (!game) {
+  let runner: Runner | undefined
+  const runnerParse = RUNNERS.safeParse(runnerStr)
+  if (runnerParse.success) {
+    runner = runnerParse.data
+  }
+  const gameInfo = findGame(appName, runner)
+  if (!gameInfo) {
     return logError(
-      `Could not receive game data for ${arg}!`,
+      `Could not receive game data for ${appName}!`,
       LogPrefix.ProtocolHandler
     )
   }
 
-  const { is_installed, title, app_name, runner: gameRunner } = game
-  const settings = await gameManagerMap[gameRunner].getSettings(app_name)
-
-  if (!is_installed) {
-    logInfo(`"${title}" not installed.`, LogPrefix.ProtocolHandler)
+  const { is_installed, title } = gameInfo
+  const settings = await gameManagerMap[gameInfo.runner].getSettings(appName)
 
-    if (!mainWindow) {
-      return
-    }
-
-    const { response } = await dialog.showMessageBox(mainWindow, {
-      buttons: [i18next.t('box.yes'), i18next.t('box.no')],
-      cancelId: 1,
-      message: `${title} ${i18next.t(
-        'box.protocol.install.not_installed',
-        'Is Not Installed, do you wish to Install it?'
-      )}`,
-      title: title,
-      icon: icon
+  if (is_installed) {
+    return launchEventCallback({
+      appName: appName,
+      runner: gameInfo.runner,
+      skipVersionCheck: settings.ignoreGameUpdates,
+      args
     })
-    if (response === 0) {
-      return sendFrontendMessage('installGame', app_name, gameRunner)
-    }
-    if (response === 1) {
-      return logInfo('Not installing game', LogPrefix.ProtocolHandler)
-    }
   }
 
-  mainWindow?.hide()
-  launchEventCallback({
-    appName: app_name,
-    runner: gameRunner,
-    skipVersionCheck: settings.ignoreGameUpdates
+  logInfo(`"${title}" not installed.`, LogPrefix.ProtocolHandler)
+
+  const mainWindow = getMainWindow()
+  if (!mainWindow) return
+
+  const { response } = await dialog.showMessageBox(mainWindow, {
+    buttons: [i18next.t('box.yes'), i18next.t('box.no')],
+    cancelId: 1,
+    message: `${title} ${i18next.t(
+      'box.protocol.install.not_installed',
+      'Is Not Installed, do you wish to Install it?'
+    )}`,
+    title: title,
+    icon: icon
   })
+  if (response === 0) {
+    sendFrontendMessage('installGame', appName, gameInfo.runner)
+  } else if (response === 1) {
+    logInfo('Not installing game', LogPrefix.ProtocolHandler)
+  }
 }
 
-/**
- * Finds a game in the runners specified in runnersToSearch
- * @param runner The runner to search for the game
- * @param arg The game to search
- * @returns The game info if found, null otherwise
- * @example
- * findGame('gog', '123')
- * // => { app_name: '123', title: '123', is_installed: true, runner: 'gog' ...}
- * findGame('legendary', '123')
- * // => { app_name: '123', title: '123', is_installed: true, runner: 'legendary' ...}
- * findGame('nile', '123')
- * // => { app_name: '123', title: '123', is_installed: true, runner: 'nile' ...}
- **/
-async function findGame(
-  runner: Runner | undefined,
-  arg = ''
-): Promise<GameInfo | null> {
-  if (!arg) {
-    return null
-  }
+function findGame(
+  appName?: string | null,
+  runner?: Runner
+): GameInfo | undefined {
+  if (!appName) return
 
   // If a runner is specified, search for the game in that runner and return it (if found)
-  if (runner) {
-    const gameInfo = getInfo(arg, runner)
-    if (gameInfo.app_name) {
-      return gameInfo
-    }
-  }
+  if (runner) return gameManagerMap[runner].getGameInfo(appName)
 
   // If no runner is specified, search for the game in all runners and return the first one found
-  for (const currentRunner of RUNNERS) {
-    const run = (currentRunner as Runner) || 'legendary'
-
-    const gameInfoOrSideload = getInfo(arg, run)
-    if (gameInfoOrSideload.app_name) {
-      return gameInfoOrSideload
-    }
+  for (const runner of RUNNERS.options) {
+    const maybeGameInfo = gameManagerMap[runner].getGameInfo(appName)
+    if (maybeGameInfo.app_name) return maybeGameInfo
   }
-  return null
+  return
 }

src/backend/shortcuts/nonesteamgame/nonesteamgame.ts

@@ -304,7 +304,7 @@ async function addNonSteamGame(props: {
 
     const { runner, app_name } = props.gameInfo
 
-    args.push(`"heroic://launch/${runner}/${app_name}"`)
+    args.push(`"heroic://launch?appName=${app_name}&runner=${runner}"`)
     newEntry.LaunchOptions = args.join(' ')
     if (isFlatpak) {
       newEntry.LaunchOptions = `run com.heroicgameslauncher.hgl ${newEntry.LaunchOptions}`

src/backend/shortcuts/shortcuts/shortcuts.ts

@@ -41,7 +41,7 @@ async function addShortcuts(gameInfo: GameInfo, fromMenu?: boolean) {
     addNonSteamGame({ gameInfo })
   }
 
-  const launchWithProtocol = `heroic://launch/${runner}/${app_name}`
+  const launchWithProtocol = `heroic://launch?appName=${app_name}&runner=${runner}`
   const [desktopFile, menuFile] = shortcutFiles(gameInfo.title)
   if (!desktopFile || !menuFile) {
     return
@@ -222,7 +222,7 @@ async function generateMacOsApp(gameInfo: GameInfo) {
     // write the run.sh file
     const launchCommand = `${app.getPath(
       'exe'
-    )} --no-gui heroic://launch/${runner}/${app_name}`
+    )} --no-gui heroic://launch?appName=${app_name}&runner=${runner}`
     const shortcut = `#!/bin/bash
     # autogenerated file - do not edit
 

src/backend/storeManagers/gog/games.ts

@@ -486,7 +486,8 @@ export async function removeShortcuts(appName: string) {
 
 export async function launch(
   appName: string,
-  launchArguments?: LaunchOption
+  launchArguments?: LaunchOption,
+  args: string[] = []
 ): Promise<boolean> {
   const gameSettings = await getSettings(appName)
   const gameInfo = getGameInfo(appName)
@@ -602,7 +603,8 @@ export async function launch(
     ...shlex.split(
       (launchArguments as BaseLaunchOption | undefined)?.parameters ?? ''
     ),
-    ...shlex.split(gameSettings.launcherArgs ?? '')
+    ...shlex.split(gameSettings.launcherArgs ?? ''),
+    ...args
   ]
 
   if (gameInfo.install.cyberpunk?.modsEnabled) {

src/backend/storeManagers/legendary/games.ts

@@ -839,6 +839,7 @@ export async function syncSaves(
 export async function launch(
   appName: string,
   launchArguments?: LaunchOption,
+  args: string[] = [],
   skipVersionCheck = false
 ): Promise<boolean> {
   const gameSettings = await getSettings(appName)
@@ -931,6 +932,7 @@ export async function launch(
     subcommand: 'launch',
     appName: LegendaryAppName.parse(appNameToLaunch),
     extraArguments: [
+      ...args,
       launchArguments?.type !== 'dlc' ? launchArguments?.parameters : undefined,
       gameSettings.launcherArgs
     ]

src/backend/storeManagers/nile/games.ts

@@ -311,7 +311,8 @@ export async function removeShortcuts(appName: string) {
 
 export async function launch(
   appName: string,
-  launchArguments?: LaunchOption
+  launchArguments?: LaunchOption,
+  args: string[] = []
 ): Promise<boolean> {
   const gameSettings = await getSettings(appName)
   const gameInfo = getGameInfo(appName)
@@ -409,7 +410,8 @@ export async function launch(
       (launchArguments as BaseLaunchOption | undefined)?.parameters ?? ''
     ),
     ...shlex.split(gameSettings.launcherArgs ?? ''),
-    appName
+    appName,
+    ...args
   ]
   const fullCommand = getRunnerCallWithoutCredentials(
     commandParts,

src/backend/storeManagers/sideload/games.ts

@@ -68,10 +68,10 @@ export async function isGameAvailable(appName: string): Promise<boolean> {
 
 export async function launch(
   appName: string,
-  /* eslint-disable-next-line @typescript-eslint/no-unused-vars */
-  launchArguments?: LaunchOption
+  launchArguments?: LaunchOption,
+  args: string[] = []
 ): Promise<boolean> {
-  return launchGame(appName, getGameInfo(appName), 'sideload')
+  return launchGame(appName, getGameInfo(appName), 'sideload', args)
 }
 
 export async function stop(appName: string): Promise<void> {