Skip to content

Commit

Permalink
Added: Ability to execute Tasks from Workflows
Browse files Browse the repository at this point in the history
  • Loading branch information
@Sewer56
Sewer56 committed Aug 17, 2024
1 parent 9d954c6 commit a015ec0
Show file tree
Hide file tree
Showing 6 changed files with 88 additions and 38 deletions.
48 changes: 28 additions & 20 deletions docs/Server/Packaging/Package-Metadata.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,25 +4,25 @@

Inside each package folder is a file named `package.toml`; which stores the metadata of each package.

| Type | Name | Description |
| -------------------------------- | --------------------------------------------- | ----------------------------------------------------------------------------------------------- |
| string | [Id](#id) | A name that uniquely identifies the package. |
| string | Name | Human friendly name of the package. |
| string | Author | Main author of the package. (Individual or Team Name) |
| string | Summary | Short summary of the package. Max 2 sentences. |
| PackageType | [PackageType](#packagetype) | Type of the package. See [PackageType](#packagetype) for possible values. |
| string | [DocsFile](#docsfile) | [Optional] Entry point for this package documentation. |
| SemVer | [Version](#version) | Semantic versioning version of the package. |
| bool | [IsDependency](#is-dependency) | This package is a dependency (e.g. library) and not directly consumable. |
| string | LicenseId | [SPDX License Identifier][spdx-license] |
| string[] | [Tags](#tags) | Used to make searching easier within mod managers. |
| Credit[] | [Credits](#credits) | [Optional] Stores information about who contributed what to the project. |
| string? | SourceUrl | [Optional] Link to source code (if applicable). |
| string? | ProjectUrl | [Optional] Link to website to learn more about the project. |
| UpdateData | [UpdateData](#update-data) | Stores package specific update information. |
| DependencyInfo[] | [Dependencies](#dependency-info) | Stores information about this package's dependencies. |
| DateTime | [Published](#published) | The time when this package was packed. |
| StoragePreference | [StoragePreference](#storage-preference) | Specifies the preferred storage tier for the package. |
| Type | Name | Description |
| ----------------- | ---------------------------------------- | ------------------------------------------------------------------------- |
| string | [Id](#id) | A name that uniquely identifies the package. |
| string | Name | Human friendly name of the package. |
| string | Author | Main author of the package. (Individual or Team Name) |
| string | Summary | Short summary of the package. Max 2 sentences. |
| PackageType | [PackageType](#packagetype) | Type of the package. See [PackageType](#packagetype) for possible values. |
| string | [DocsFile](#docsfile) | [Optional] Entry point for this package documentation. |
| SemVer | [Version](#version) | Semantic versioning version of the package. |
| bool | [IsDependency](#is-dependency) | This package is a dependency (e.g. library) and not directly consumable. |
| string | LicenseId | [SPDX License Identifier][spdx-license] |
| string[] | [Tags](#tags) | Used to make searching easier within mod managers. |
| Credit[] | [Credits](#credits) | [Optional] Stores information about who contributed what to the project. |
| string? | SourceUrl | [Optional] Link to source code (if applicable). |
| string? | ProjectUrl | [Optional] Link to website to learn more about the project. |
| UpdateData | [UpdateData](#update-data) | Stores package specific update information. |
| DependencyInfo[] | [Dependencies](#dependency-info) | Stores information about this package's dependencies. |
| DateTime | [Published](#published) | The time when this package was packed. |
| StoragePreference | [StoragePreference](#storage-preference) | Specifies the preferred storage tier for the package. |

These fields are usually only found when [PackageType](#packagetype) == `Mod`:

Expand All @@ -34,6 +34,12 @@ These fields are usually only found when [PackageType](#packagetype) == `Mod`:
| bool | [ClientSide](#client-side) | [Optional] True if the mod is purely cosmetic and does not have non-visual effects on gameplay. |
| bool | [AllowRuntimeLoading](#allow-runtime-loading) | [Optional] Allows the mod to be loaded in real-time at runtime, instead of only on startup. |

These fields are usually only found when [PackageType](#packagetype) == `Tool`:

| Type | Name | Description |
| ------ | -------------- | ---------------------------------------------------- |
| Task[] | [Tasks][tasks] | List of binaries that the `tool` package ships with. |

## Implicit Fields

Some items are stored as separate files:
Expand Down Expand Up @@ -235,6 +241,7 @@ automatically generated package. Specifically by:
| api | For [middleware/API hooks][middleware-api-hooks]. | `reloaded3.api.windows.vfs.s56` |
| game support | For [game support mods][game-support]. | `reloaded3.gamesupport.persona5royal.s56` |
| utility | For utility mods with reusable code. | `reloaded3.utility.hooks.s56` |
| tool | For non-game specific modding tools. | `reloaded3.tool.steamlaunchupdater.s56` |

Server can choose whether to show non game-specific mods (`reloaded3` id) on a specific game's page or not.

Expand Down Expand Up @@ -648,4 +655,5 @@ if they themselves don't support it. (These mods should log a warning to console
[semantic-versioning]: https://semver.org
[spdx-license]: https://spdx.org/licenses/
[platforms]: ../../Loader/Backends/Native.md#native-support
[architecture]: ../../Loader/Backends/Native.md#instruction-sets
[architecture]: ../../Loader/Backends/Native.md#instruction-sets
[tasks]: ./Tasks.md
41 changes: 30 additions & 11 deletions docs/Server/Storage/Games/Tasks.md → docs/Server/Packaging/Tasks.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -9,8 +9,8 @@ You can think of them like the `Tasks` you have in VSCode.
- 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
- Packages can declare their own tasks to run.
- [Per Package][package]
- `Tool` Packages can declare their own tasks to run.
- [Community Repository][community-repository]
- Community Repository can define tasks for games.

Expand All @@ -20,7 +20,8 @@ The `Tasks` field when present is an array of `Task` objects, where each `Task`

```toml
[[Tasks]]
Type = "File"
Id = "" # No ID. Imported from GOG.
Type = "Executable"
VisualHint = "Game"
Name = "Launch Game"
GroupNames = ["GOG"]
Expand All @@ -36,7 +37,8 @@ Arguments = ["-fullscreen", "-config", "{GameDir}/config.ini"]

| Type | Field | Description |
| ------------------------- | ----------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
| [TaskType](#tasktype) | [TaskType](#tasktype) | The type of the task (e.g., "File", "Url"). |
| [Id](#id) | [Id](#id) | Unique Identifier for Task. |
| [TaskType](#tasktype) | [TaskType](#tasktype) | The type of the task (e.g., "Executable", "Url"). |
| [VisualHint](#visualhint) | [VisualHint](#visualhint) | Visual hint for the UIs. |
| string | Name | A user-friendly name for the task. |
| string[] | [GroupNames](#group-names) | A user-friendly name for 'group' containing this task. |
Expand All @@ -50,11 +52,27 @@ Arguments = ["-fullscreen", "-config", "{GameDir}/config.ini"]
| [Platform](#platform) | [Platform](#platform) | (Flags) The OSes this task is available for. If 0, is enabled for all. |
| [StoreType][store-type] | [Store](#store) | The store to restrict this operation to. |

### Id

!!! info "This is a `unique identifier` for the task."

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

!!! tip "For tasks defined in [packages][package], 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

!!! info "The `TaskType` can be one of the following"

- 0: `File`: Represents a task that launches an executable file.
- 0: `Executable`: Represents a task that launches an executable file.
- 1: `Url`: Launches an URL. [Path](#path) specifies the full URL to open.

### VisualHint
Expand Down Expand Up @@ -282,10 +300,11 @@ We should be able to import these tasks directly into the game configuration.
A task that is not valid should set the [UnavailableReason](#tasks-in-code) field to a string
explaining why the task is not available. And be blanked out.

[gog-info-file]: ../Loadouts/Stores/GOG.md#goggame-gameidinfo
[images]: ../../../Common/Images.md
[package]: ../../Packaging/Package-Metadata.md
[items-to-store]: ../Locations.md#items-to-store
[community-repository]: ../../../Services/Community-Repository.md
[gog-info-file]: ../Storage/Loadouts/Stores/GOG.md#goggame-gameidinfo
[images]: ../../Common/Images.md
[package]: ./Package-Metadata.md
[items-to-store]: ../Storage/Locations.md#items-to-store
[community-repository]: ../../Services/Community-Repository.md
[steam-protocol]: https://developer.valvesoftware.com/wiki/Steam_browser_protocol
[store-type]: ../Loadouts/File-Format/DataTypes.md#storetype
[store-type]: ../Storage/Loadouts/File-Format/DataTypes.md#storetype
[workflows]: ../Workflows/Implementation/Scripting.md#workflow-scripting
6 changes: 3 additions & 3 deletions docs/Server/Storage/Games/About.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -174,9 +174,9 @@ This data is cached in the [`Server Cache Files` (`Cache/Server`) folder.][adde
[event-sourcing]: ../Loadouts/About.md#event-sourcing
[images]: ../../../Common/Images.md
[reloaded-community]: https://github.com/Reloaded-Project/Reloaded.Community
[task-placeholders]: Tasks.md#commandline-placeholders
[tasks]: ./Tasks.md
[tasks-arguments]: Tasks.md#arguments
[task-placeholders]: ../../Packaging/Tasks.md#commandline-placeholders
[tasks]: ../../Packaging/Tasks.md
[tasks-arguments]: ../../Packaging/Tasks.md#arguments
[community-repository-icon]: ../../../Services/Community-Repository.md#icons-and-banners-steamgriddb
[community-repository-banner]: ../../../Services/Community-Repository.md#icons-and-banners-steamgriddb
[store-info]: ../../../Services/Community-Repository.md#store-information
Expand Down
27 changes: 25 additions & 2 deletions docs/Server/Workflows/Implementation/Scripting.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -266,12 +266,33 @@ Here are the available modules:
// Get current date
let date = system::date();
print(`Year: ${date.year}, Month: ${date.month}, Day: ${date.day}`);

// Execute a task defined in a package declared task
let task_result = system::execute_task("launch-game", ["-fullscreen", "-nosound"]);
print(`Task execution result: ${task_result.exit_code}`);
print(`Task stdout: ${task_result.stdout}`);
```

* **`system::command(cmd: &str, args: Array) -> value`**: Executes the system command `cmd` with the given `args` array. Returns the command's output as a string.
* **`system::command(cmd: &str, args: Array) -> TaskResult`**: Executes the system command `cmd` with the given `args` array. Returns a `TaskResult` object.

* **`system::date() -> Date`**: Returns a `Date` object representing the current date in UTC. The `Date` object has `year`, `month`, and `day` properties.

* **`system::execute_task(task_id: &str, args: Array) -> TaskResult`**: Executes the [task][task] with the given `task_id`. The task must be defined in a package. Additional command-line arguments can be provided in the `args` array. Returns a `TaskResult` object.

The `TaskResult` object has the following properties:
- `exit_code`: An integer representing the exit code of the executed task or command.
- `stdout`: A string containing the stdout of the task or command.
- `stderr`: A string containing the stderr of the task or command.

!!! tip "The `system::execute_task` function allows you to run [tasks][task] defined in the Reloaded [packages]."

Use this for advanced functionality such as ***extracting archived game files*** that may
require external CLI tools.

!!! tip "Combine `system::command` with `workflow::path` to run native binaries within the workflow."

Do not use this to run generic modding tools, for these please create [`Tool` Packages with Tasks][packages].

## Example Rhai Script

Here's an example of a Rhai script that might be used in a Reloaded3 workflow:
Expand Down Expand Up @@ -394,4 +415,6 @@ fn copy_stage_files(source_number, target_number) {
[rhai-vsc]: https://marketplace.visualstudio.com/items?itemName=rhaiscript.vscode-rhai
[esoteric-platforms]: ../../../Code-Guidelines/Hardware-Requirements.md#about-esoteric-and-experimental-platforms
[workflow-localization]: ./Schema.md#localization
[for-loop-mj]: ./Templates.md#for-loop
[for-loop-mj]: ./Templates.md#for-loop
[Packages]: ../../Packaging/Package-Metadata.md
[task]: ../../Packaging/Tasks.md
2 changes: 1 addition & 1 deletion docs/Services/Community-Repository.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -572,4 +572,4 @@ If we ever get notified from GitHub about bandwidth usage, we will migrate this
[gog-buildid]: ../Server/Storage/Loadouts/Stores/GOG.md#retrieving-available-game-versions
[store-type]: ../Server/Storage/Loadouts/File-Format/DataTypes.md#storetype
[server-cache-files-communityrepo]: ../Server/Storage/Locations.md#community-repository
[tasks]: ../Server/Storage/Games/Tasks.md
[tasks]: ../Server/Packaging/Tasks.md
2 changes: 1 addition & 1 deletion mkdocs.yml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -104,7 +104,6 @@ nav:
- Package Tiering: Server/Storage/Package-Tiering.md
- Games:
- About: Server/Storage/Games/About.md
- Tasks: Server/Storage/Games/Tasks.md
- Loadouts:
- About: Server/Storage/Loadouts/About.md
- File Format:
Expand All @@ -122,6 +121,7 @@ nav:
- About: Server/Packaging/About.md
- Package Metadata: Server/Packaging/Package-Metadata.md
- Publishing Packages: Server/Packaging/Publishing-Packages.md
- Tasks: Server/Packaging/Tasks.md
- Workflows:
- About: Server/Workflows/About.md
- Guidelines: Server/Workflows/Guidelines.md
Expand Down

0 comments on commit a015ec0

Please sign in to comment.