Tasks

The 'tasks' represent an array of actions that can be used to launch the game.

You can think of them like the Tasks you have in VSCode.

Where Tasks can be Defined

• Per Game
  • These tasks are automatically created when you add a game to the launcher.
  • These are persisted in the user's preferences.
• Per Package
  • Tool Packages can declare their own tasks to run.
• Community Repository
  • Community Repository can define tasks for games.

Structure

The Tasks field when present is an array of Task objects, where each Task is defined as:

[[Tasks]]
Id = "" # No ID. Imported from GOG.
Type = "Executable"
VisualHint = "Game"
Name = "Launch Game"
GroupNames = ["GOG"]
Description = "Launches the game."
Path = {
  win+x64-any = "Game.exe",
  linux+x64-any = "Game.elf",
  macos+x64-any = "Game.app"
}
IsPrimary = true
IsHidden = false
InjectLoader = true
Icon = "GameIcon.png"
RelativeWorkingDir = "Bin"
Arguments = ["-fullscreen", "-config", "{GameDir}/config.ini"]

Type	Field	Description
Id	Id	Unique Identifier for Task.
TaskType	TaskType	The type of the task (e.g., "Executable", "Url").
VisualHint	VisualHint	Visual hint for the UIs.
string	Name	A user-friendly name for the task.
string[]	GroupNames	A user-friendly name for 'group' containing this task.
string?	Description	A brief description of the task. Ideally limited to 2 short lines.
CrossPath	Path	The relative path to the executable file or the URL to open. See Path for details.
bool	IsPrimary	Indicates whether this task launches the game's main executable. Only one task should have IsPrimary set to true.
bool	InjectLoader	Indicates whether the loader should be injected. Usually only true for the IsPrimary task.
string[]	Arguments	An array of additional commandline arguments to pass to the executable. Can use placeholders like {GameDir}.
bool?	IsHidden	Indicates whether the task should be hidden from the user. Defaults to false.
string?	RelativeWorkingDir	The working directory for the task. Defaults to the folder containing Path, otherwise is a folder relative to it.
StoreType	Store	The store to restrict this operation to.

Id

This is a unique identifier for the task.

This allows for tasks to be used in workflow scripts and other places where uniquely identifying a task is useful.

For tasks defined in packages, please always use an ID

Set the Task Id to packageId+TaskName to ensure uniqueness. For example, for a package named sonicheroes.tool.heroesone.s56, give the main tool the ID of sonicheroes.tool.heroesone.s56.main.

If you have multiple binaries, you would do, sonicheroes.tool.heroesone.s56.extractor, sonicheroes.tool.heroesone.s56.archiver etc.

TaskType

The TaskType can be one of the following

• 0: Executable: Represents a task that launches an executable file.
• 1: Url: Launches an URL. Path specifies the full URL to open.

VisualHint

This is a hint for the launcher and other UIs.

• 0: Game: Shows a GamePad. Used for game binary.
• 1: Settings: Shows a Gear. Used for launchers.
• 2: Tool: Shows a Wrench. Used for modding tools.
• 3: Wiki: Shows a Book. Used for documentation.
• 4: Community: Shows a Globe. Used for community links.

Group Names

A user-friendly name for 'groups' containing this task.

This field is used to group tasks together in the UI if the user to chooses to view tasks by group.

Example group names include:

• GOG: All items imported from GOG.
• Community: All items imported from the community repository.

Description

A brief description of the task. Ideally limited to 2 short lines.

The Description field provides a brief description of the task.

It should ideally be limited to 2 short lines for conciseness and clarity.

Example:

Description = "Launches the configuration program."

Path

The relative path to the executable file or the URL to open.

The Path field specifies the relative path to the executable file or the URL to open when the task is executed.

• If the task is declared in a Package, the Path is relative to the folder the package is located in.
• If the task is declared for a game, the Path is relative to the folder that contains the main executable of the game.
  • The one marked IsPrimary.

// TODO: - [Platform][platforms] only: win, linux. When package has all architecture binaries. - [Platform][platforms]+[Arch][architecture]: win+x64-v3, linux+x64-v3. When package has only one specific architecture.

Examples:

1. Cross-platform executable:

   Path = { any = "Tool.dll" } # .NET
   

2. Platform-specific paths:

   Path = {
     win+x64-any = "Tool.exe",
     linux+x64-any = "Tool.elf",
     macos+x64-any = "Tool.app"
   }
   

3. Windows only

   Path = {
     any = "",
     win+x64-any = "Tool.exe"
   }
   

At least one of these keys must be specified. If a platform-specific key is not present, the Default path will be used if. This can be used to ship cross-platform binaries.

If there's no Default and no platform-specific path for the current platform, the task will not be available on that platform.

IsPrimary

Indicates whether this task launches the game's main executable.

Only one task should have IsPrimary set to true.

The IsPrimary field indicates whether the task launches the game's main executable, which is usually the primary EXE file assigned by the game store or the user.

When importing external tasks, there may be more than one 'default' task.

In such cases, the local already defined task wins.

InjectLoader

Indicates whether the loader should be injected.

Usually only true for the IsPrimary task.

The InjectLoader field is a boolean value that indicates whether the mod loader should be injected when the task is executed.

This field is only used when the method of injecting is set to 'Code Injection'

RelativeWorkingDir

The working directory for the task.

Defaults to the folder containing Path, otherwise is a folder relative to it.

The RelativeWorkingDir field specifies the working directory for the task.

If not specified, it defaults to the folder containing the file specified in the Path field.
Otherwise, it is treated as a folder relative to the Path.

Example:

RelativeWorkingDir = ""

Gives you C:/Games/MyGame/Bin if the Path is Bin/Game.exe and game is at C:/Games/MyGame.

If you want to go one folder up from the Path, use double dots:

RelativeWorkingDir = ".."

This will set the working directory to C:/Games/MyGame.

Commandline Placeholders

These placeholders will be replaced with their corresponding values when the task is executed.

When specifying the Path or commandline Arguments for a task, you can use placeholders to dynamically insert certain values.

The available placeholders are:

• {GameDir}: The absolute path to the directory containing the main executable file.

If the task is sourced from a package, the following variables are also available:

• {PackageDir}: The absolute path to the base folder of the package.
• {PackageUserCacheDir}: The absolute path to the config folder for the package.
  • This is the Package Cache Files (User) (Cache/{packageId}) folder.
• {PackageMachineCacheDir}: The absolute path to the config folder for the package.
  • This is the Package Cache Files (Machine) (Cache/{packageId}) folder.

The intent is to allow for external tools to store their configuration files within loadouts. By doing this, the user can cloud save their settings for their favourite tools.

Arguments

An array of additional commandline arguments to pass to the executable.

Can use Commandline Placeholders.

The Arguments field is an array of additional commandline arguments to pass to the executable when the task is executed. It supports the use of Commandline Placeholders like {GameDir} to dynamically insert values.

Example:

Arguments = ["-fullscreen", "-config", "{GameDir}/config.ini"]

When you execute the task, the following will run:

Game.exe -fullscreen -config C:/Games/MyGame/config.ini

Store

Some tasks are only available for certain game stores.

The Store field is an optional field that specifies the store this task is associated with.

The available store values can be found here.

If the Store field is not specified or set to None, the task is considered store-independent and can be used with any store.

This is useful for things like adding links via Steam Browser Protocol

Tasks in Code

Some additional fields exist only in memory/code, on the actual implementation side

Type	Field	Description
TaskSource	Type	Where the current task originated from.
string	UnavailableReason	The reason a task cannot be executed. Task is unavailable if this is not null.

TaskSource

• 0: Game: Task was defined for the game.
• 1: Package: Task was defined in a package.
• 2: Community: Task was imported from the community repository.
• 3: Imported: Task was imported from an external source (e.g., GOG).

Importing from GOG

GOG Games have their 'tasks' defined inside the goggame-{gameid}.info file.

Example from file (truncated):

"playTasks": [
    {
        "category": "game",
        "isPrimary": true,
        "languages": [
            "en-US"
        ],
        "name": "The Legend of Heroes: Trails in the Sky SC",
        "path": "ed6_win2_DX9.exe",
        "type": "File"
    },
    {
        "category": "launcher",
        "languages": [
            "en-US"
        ],
        "name": "Configuration Tool",
        "path": "Config2_DX9.exe",
        "type": "File"
    }
],

We should be able to import these tasks directly into the game configuration.

Edge Cases

Not All Tasks Always are Valid

Check the target file exists before showing the task.

A user who for example is dual booting their OS, might find that launching Steam on Linux, after using it on Windows has replaced their game with the Linux version.

A task that is not valid should set the UnavailableReason field to a string explaining why the task is not available. And be blanked out.