From a015ec004f9928d7bd63b2e63abf93786d0ceec9 Mon Sep 17 00:00:00 2001 From: Sewer56 Date: Sat, 17 Aug 2024 17:54:08 +0100 Subject: [PATCH] Added: Ability to execute Tasks from Workflows --- docs/Server/Packaging/Package-Metadata.md | 48 +++++++++++-------- .../{Storage/Games => Packaging}/Tasks.md | 41 +++++++++++----- docs/Server/Storage/Games/About.md | 6 +-- .../Workflows/Implementation/Scripting.md | 27 ++++++++++- docs/Services/Community-Repository.md | 2 +- mkdocs.yml | 2 +- 6 files changed, 88 insertions(+), 38 deletions(-) rename docs/Server/{Storage/Games => Packaging}/Tasks.md (88%) diff --git a/docs/Server/Packaging/Package-Metadata.md b/docs/Server/Packaging/Package-Metadata.md index f6a8f19..320ef35 100644 --- a/docs/Server/Packaging/Package-Metadata.md +++ b/docs/Server/Packaging/Package-Metadata.md @@ -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`: @@ -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: @@ -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. @@ -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 \ No newline at end of file +[architecture]: ../../Loader/Backends/Native.md#instruction-sets +[tasks]: ./Tasks.md \ No newline at end of file diff --git a/docs/Server/Storage/Games/Tasks.md b/docs/Server/Packaging/Tasks.md similarity index 88% rename from docs/Server/Storage/Games/Tasks.md rename to docs/Server/Packaging/Tasks.md index e3892ea..fdbdd24 100644 --- a/docs/Server/Storage/Games/Tasks.md +++ b/docs/Server/Packaging/Tasks.md @@ -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. @@ -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"] @@ -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. | @@ -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 @@ -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 \ No newline at end of file +[store-type]: ../Storage/Loadouts/File-Format/DataTypes.md#storetype +[workflows]: ../Workflows/Implementation/Scripting.md#workflow-scripting \ No newline at end of file diff --git a/docs/Server/Storage/Games/About.md b/docs/Server/Storage/Games/About.md index 5ebc47d..5071bc1 100644 --- a/docs/Server/Storage/Games/About.md +++ b/docs/Server/Storage/Games/About.md @@ -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 diff --git a/docs/Server/Workflows/Implementation/Scripting.md b/docs/Server/Workflows/Implementation/Scripting.md index 863c057..eb49502 100644 --- a/docs/Server/Workflows/Implementation/Scripting.md +++ b/docs/Server/Workflows/Implementation/Scripting.md @@ -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: @@ -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 \ No newline at end of file +[for-loop-mj]: ./Templates.md#for-loop +[Packages]: ../../Packaging/Package-Metadata.md +[task]: ../../Packaging/Tasks.md \ No newline at end of file diff --git a/docs/Services/Community-Repository.md b/docs/Services/Community-Repository.md index 78c6f9b..3a8ebe4 100644 --- a/docs/Services/Community-Repository.md +++ b/docs/Services/Community-Repository.md @@ -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 \ No newline at end of file +[tasks]: ../Server/Packaging/Tasks.md \ No newline at end of file diff --git a/mkdocs.yml b/mkdocs.yml index f482216..41a83b2 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -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: @@ -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