From 998b61de0da845f9fd9acb84ea1bac9fa1ed28bd Mon Sep 17 00:00:00 2001 From: Geoff Bourne Date: Fri, 17 Oct 2025 17:05:09 -0500 Subject: [PATCH] Improve variable naming with MODRINTH_MODPACK_VERSION_TYPE and MODRINTH_PROJECTS_DEFAULT_VERSION_TYPE (#3716) --- docs/mods-and-plugins/modrinth.md | 2 +- .../mod-platforms/modrinth-modpacks.md | 218 +++++++++--------- .../modrinth/modrinth-modpack/compose.yml | 8 +- examples/modrinth/modrinth-paper/compose.yml | 2 +- scripts/start-deployModrinth | 9 +- scripts/start-setupModpack | 5 +- 6 files changed, 123 insertions(+), 121 deletions(-) diff --git a/docs/mods-and-plugins/modrinth.md b/docs/mods-and-plugins/modrinth.md index e85981e4..539c4776 100644 --- a/docs/mods-and-plugins/modrinth.md +++ b/docs/mods-and-plugins/modrinth.md @@ -92,7 +92,7 @@ When the environment variable `VERSION_FROM_MODRINTH_PROJECTS` is set to "true" `MODRINTH_DOWNLOAD_DEPENDENCIES` : Can be set to `none` (the default), `required`, or `optional` to download required and/or optional dependencies. -`MODRINTH_ALLOWED_VERSION_TYPE` +`MODRINTH_PROJECTS_DEFAULT_VERSION_TYPE` : The version type is used to determine the newest version to use from each project. The allowed values are `release` (default), `beta`, `alpha`. Setting to `beta` will pick up both release and beta versions. Setting to `alpha` will pick up release, beta, and alpha versions. `MODRINTH_LOADER` diff --git a/docs/types-and-platforms/mod-platforms/modrinth-modpacks.md b/docs/types-and-platforms/mod-platforms/modrinth-modpacks.md index 160a6528..a02d6d80 100644 --- a/docs/types-and-platforms/mod-platforms/modrinth-modpacks.md +++ b/docs/types-and-platforms/mod-platforms/modrinth-modpacks.md @@ -1,109 +1,109 @@ -# Modrinth Modpacks - -[Modrinth Modpacks](https://modrinth.com/modpacks) can automatically be installed along with the required mod loader (Forge or Fabric) by setting `MODPACK_PLATFORM`, `MOD_PLATFORM` or `TYPE` to "MODRINTH". Upgrading (and downgrading) takes care of cleaning up old files and upgrading (and downgrading) the mod loader. - -## Modpack project - -The desired modpack project is specified with the `MODRINTH_MODPACK` environment variable and must be one of: - -- The project "slug", which is located in the URL shown here: - - ![](../../img/modrinth-project-slug.drawio.png) - -- The project ID, which is located in the bottom of the left panel, shown here - - ![](../../img/modrinth-project-id.drawio.png) - -- The project page URL, such as . As described below, this can further be the page URL of a modpack's version page. - -- A custom URL of a hosted [mrpack file](https://support.modrinth.com/en/articles/8802351-modrinth-modpack-format-mrpack) - -- The container path to a local [mrpack file](https://support.modrinth.com/en/articles/8802351-modrinth-modpack-format-mrpack) - -## Modpack version - -The automatic modpack version resolving can be narrowed in a few ways: - -The latest release or beta version, respectively, of the Modrinth modpack is selected when `VERSION` is "LATEST" or "SNAPSHOT". That can be overridden by setting `MODRINTH_DEFAULT_VERSION_TYPE` to "release", "beta", or "alpha". - -The resolved modpack version can be narrowed by setting `VERSION` to a specific Minecraft version, such as "1.19.2". - -The selected version can also be narrowed to a particular mod loader by setting `MODRINTH_LOADER` to either "forge", "fabric", or "quilt". - -Instead of auto resolving, a specific version of modpack file can be specified by passing the version's page URL to `MODRINTH_MODPACK`, such as or by setting `MODRINTH_VERSION` to the version ID or number located in the Metadata section, as shown here - -![](../../img/modrinth-version-id.drawio.png) - -## Ignore missing files - -Some mods, such as [MCInstance Loader](https://modrinth.com/mod/mcinstance-loader), use temporary files from the modpack and delete them when finished. In order to avoid the installer from detecting the absent file(s) and re-installing, those files can be ignored by passing a comma or newline delimited list to `MODRINTH_IGNORE_MISSING_FILES`. - -!!! example - - In a Compose file - ```yaml - environment: - MODRINTH_IGNORE_MISSING_FILES: | - config/mcinstanceloader/pack.mcinstance - ``` - -## Excluding files - -To exclude client mods that are incorrectly declared by the modpack as server-compatible, set `MODRINTH_EXCLUDE_FILES` to a comma or newline delimited list of partial file names to exclude. You may need to set `MODRINTH_FORCE_SYNCHRONIZE` to "true" while iterating on a compatible set of mods to use. - -!!! example - - In a Compose file: - ```yaml - MODRINTH_EXCLUDE_FILES: | - notenoughanimations - lambdynamiclights - euphoriapatcher - ``` - -## Force-include files - -To force include client mods, set `MODRINTH_FORCE_INCLUDE_FILES` to a comma or newline delimited list of partial file names. You may need to set `MODRINTH_FORCE_SYNCHRONIZE` to "true" while iterating on a compatible set of mods to use. - -!!! example - - In a Compose file: - ```yaml - MODRINTH_FORCE_INCLUDE_FILES: | - yet-another-config-lib - ``` - -## Default exclude/includes - -The image comes with a default set of exclude/includes, maintained [in the repo files area](https://github.com/itzg/docker-minecraft-server/blob/master/files/modrinth-exclude-include.json) and uses the same [JSON schema](https://github.com/itzg/mc-image-helper?tab=readme-ov-file#excludeinclude-file-schema) as Auto CurseForge. Those defaults can be disabled by setting the env var `MODRINTH_DEFAULT_EXCLUDE_INCLUDES` to an empty string. - -## Excluding Overrides Files - -Modrinth mrpack/zip files may include an `overrides` subdirectory that contains config files, world data, and extra mod files. All of those files will be extracted into the `/data` path of the container. If any of those files, such as incompatible mods, need to be excluded from extraction, then the `MODRINTH_OVERRIDES_EXCLUSIONS` variable can be set with a comma or newline delimited list of ant-style paths ([see below](#ant-style-paths)) to exclude, relative to the overrides (or `/data`) directory. - -### Ant-style paths - -Ant-style paths can include the following globbing/wildcard symbols: - -| Symbol | Behavior | -|--------|---------------------------------------------------------| -| `*` | Matches zero, one, or many characters except a slash | -| `**` | Matches zero, one, or many characters including slashes | -| `?` | Matches one character | - -!!! example - - The following compose `environment` entries show how to exclude Iris and Sodium mods from the overrides - - ```yaml - MODRINTH_OVERRIDES_EXCLUSIONS: mods/NekosEnchantedBooks-*.jar,mods/citresewn-*.jar - ``` - - or using newline delimiter, which improves maintainability - - ```yaml - MODRINTH_OVERRIDES_EXCLUSIONS: | - mods/NekosEnchantedBooks-*.jar - mods/citresewn-*.jar - ``` - +# Modrinth Modpacks + +[Modrinth Modpacks](https://modrinth.com/modpacks) can automatically be installed along with the required mod loader (Forge or Fabric) by setting `MODPACK_PLATFORM`, `MOD_PLATFORM` or `TYPE` to "MODRINTH". Upgrading (and downgrading) takes care of cleaning up old files and upgrading (and downgrading) the mod loader. + +## Modpack project + +The desired modpack project is specified with the `MODRINTH_MODPACK` environment variable and must be one of: + +- The project "slug", which is located in the URL shown here: + + ![](../../img/modrinth-project-slug.drawio.png) + +- The project ID, which is located in the bottom of the left panel, shown here + + ![](../../img/modrinth-project-id.drawio.png) + +- The project page URL, such as . As described below, this can further be the page URL of a modpack's version page. + +- A custom URL of a hosted [mrpack file](https://support.modrinth.com/en/articles/8802351-modrinth-modpack-format-mrpack) + +- The container path to a local [mrpack file](https://support.modrinth.com/en/articles/8802351-modrinth-modpack-format-mrpack) + +## Modpack version + +The automatic modpack version resolving can be narrowed in a few ways: + +The latest release or beta version, respectively, of the Modrinth modpack is selected when `VERSION` is "LATEST" or "SNAPSHOT". That can be overridden by setting `MODRINTH_MODPACK_VERSION_TYPE` to "release", "beta", or "alpha". + +The resolved modpack version can be narrowed by setting `VERSION` to a specific Minecraft version, such as "1.19.2". + +The selected version can also be narrowed to a particular mod loader by setting `MODRINTH_LOADER` to either "forge", "fabric", or "quilt". + +Instead of auto resolving, a specific version of modpack file can be specified by passing the version's page URL to `MODRINTH_MODPACK`, such as or by setting `MODRINTH_VERSION` to the version ID or number located in the Metadata section, as shown here + +![](../../img/modrinth-version-id.drawio.png) + +## Ignore missing files + +Some mods, such as [MCInstance Loader](https://modrinth.com/mod/mcinstance-loader), use temporary files from the modpack and delete them when finished. In order to avoid the installer from detecting the absent file(s) and re-installing, those files can be ignored by passing a comma or newline delimited list to `MODRINTH_IGNORE_MISSING_FILES`. + +!!! example + + In a Compose file + ```yaml + environment: + MODRINTH_IGNORE_MISSING_FILES: | + config/mcinstanceloader/pack.mcinstance + ``` + +## Excluding files + +To exclude client mods that are incorrectly declared by the modpack as server-compatible, set `MODRINTH_EXCLUDE_FILES` to a comma or newline delimited list of partial file names to exclude. You may need to set `MODRINTH_FORCE_SYNCHRONIZE` to "true" while iterating on a compatible set of mods to use. + +!!! example + + In a Compose file: + ```yaml + MODRINTH_EXCLUDE_FILES: | + notenoughanimations + lambdynamiclights + euphoriapatcher + ``` + +## Force-include files + +To force include client mods, set `MODRINTH_FORCE_INCLUDE_FILES` to a comma or newline delimited list of partial file names. You may need to set `MODRINTH_FORCE_SYNCHRONIZE` to "true" while iterating on a compatible set of mods to use. + +!!! example + + In a Compose file: + ```yaml + MODRINTH_FORCE_INCLUDE_FILES: | + yet-another-config-lib + ``` + +## Default exclude/includes + +The image comes with a default set of exclude/includes, maintained [in the repo files area](https://github.com/itzg/docker-minecraft-server/blob/master/files/modrinth-exclude-include.json) and uses the same [JSON schema](https://github.com/itzg/mc-image-helper?tab=readme-ov-file#excludeinclude-file-schema) as Auto CurseForge. Those defaults can be disabled by setting the env var `MODRINTH_DEFAULT_EXCLUDE_INCLUDES` to an empty string. + +## Excluding Overrides Files + +Modrinth mrpack/zip files may include an `overrides` subdirectory that contains config files, world data, and extra mod files. All of those files will be extracted into the `/data` path of the container. If any of those files, such as incompatible mods, need to be excluded from extraction, then the `MODRINTH_OVERRIDES_EXCLUSIONS` variable can be set with a comma or newline delimited list of ant-style paths ([see below](#ant-style-paths)) to exclude, relative to the overrides (or `/data`) directory. + +### Ant-style paths + +Ant-style paths can include the following globbing/wildcard symbols: + +| Symbol | Behavior | +|--------|---------------------------------------------------------| +| `*` | Matches zero, one, or many characters except a slash | +| `**` | Matches zero, one, or many characters including slashes | +| `?` | Matches one character | + +!!! example + + The following compose `environment` entries show how to exclude Iris and Sodium mods from the overrides + + ```yaml + MODRINTH_OVERRIDES_EXCLUSIONS: mods/NekosEnchantedBooks-*.jar,mods/citresewn-*.jar + ``` + + or using newline delimiter, which improves maintainability + + ```yaml + MODRINTH_OVERRIDES_EXCLUSIONS: | + mods/NekosEnchantedBooks-*.jar + mods/citresewn-*.jar + ``` + diff --git a/examples/modrinth/modrinth-modpack/compose.yml b/examples/modrinth/modrinth-modpack/compose.yml index 30b61292..00a4ca6e 100644 --- a/examples/modrinth/modrinth-modpack/compose.yml +++ b/examples/modrinth/modrinth-modpack/compose.yml @@ -8,14 +8,14 @@ services: environment: EULA: "TRUE" MODPACK_PLATFORM: MODRINTH - MODRINTH_MODPACK: https://modrinth.com/modpack/cobblemon-fabric/version/1.3.2 + MODRINTH_MODPACK: https://modrinth.com/modpack/cobblemon-fabric/version/1.6.1.4 # or for auto-upgrading to latest # MODRINTH_MODPACK: https://modrinth.com/modpack/cobblemon-fabric # or just cobblemon-fabric or 5FFgwNNP # and could replace version URL with - # MODRINTH_VERSION: nvrqJg44 - # MODRINTH_VERSION: 1.3.2 - # MODRINTH_VERSION: "Cobblemon [Fabric] 1.3.2" + # MODRINTH_VERSION: 98odLiu9 + # MODRINTH_VERSION: 1.6.1.4 + # MODRINTH_VERSION: "Cobblemon [Fabric] 1.6.1.4" volumes: # attach the relative directory 'data' to the container's /data path - ./data:/data diff --git a/examples/modrinth/modrinth-paper/compose.yml b/examples/modrinth/modrinth-paper/compose.yml index ba5f76a8..3c77aa06 100644 --- a/examples/modrinth/modrinth-paper/compose.yml +++ b/examples/modrinth/modrinth-paper/compose.yml @@ -6,6 +6,6 @@ services: TYPE: PAPER VERSION: 1.19.3 MODRINTH_PROJECTS: "coreprotect" - MODRINTH_ALLOWED_VERSION_TYPE: "release" + MODRINTH_PROJECTS_DEFAULT_VERSION_TYPE: "release" volumes: - ./data:/data diff --git a/scripts/start-deployModrinth b/scripts/start-deployModrinth index 2c8068c8..36144b2d 100644 --- a/scripts/start-deployModrinth +++ b/scripts/start-deployModrinth @@ -40,13 +40,14 @@ fi case "${VERSION^^}" in LATEST) - : "${MODRINTH_DEFAULT_VERSION_TYPE:=release}" + # need to be backward compatible with old variable name, MODRINTH_DEFAULT_VERSION_TYPE + : "${MODRINTH_MODPACK_VERSION_TYPE:=${MODRINTH_DEFAULT_VERSION_TYPE:-release}}" ;; SNAPSHOT) - : "${MODRINTH_DEFAULT_VERSION_TYPE:=beta}" + : "${MODRINTH_MODPACK_VERSION_TYPE:=${MODRINTH_DEFAULT_VERSION_TYPE:-beta}}" ;; *) - : "${MODRINTH_DEFAULT_VERSION_TYPE:=release}" + : "${MODRINTH_MODPACK_VERSION_TYPE:=${MODRINTH_DEFAULT_VERSION_TYPE:-release}}" args+=("--game-version=$VERSION") ;; esac @@ -61,7 +62,7 @@ setArg() { } setArg --loader MODRINTH_LOADER setArg --version MODRINTH_VERSION -setArg --default-version-type MODRINTH_DEFAULT_VERSION_TYPE +setArg --default-version-type MODRINTH_MODPACK_VERSION_TYPE setArg --exclude-files MODRINTH_EXCLUDE_FILES setArg --force-include-files MODRINTH_FORCE_INCLUDE_FILES setArg --overrides-exclusions MODRINTH_OVERRIDES_EXCLUSIONS diff --git a/scripts/start-setupModpack b/scripts/start-setupModpack index 1ecfce2e..eae5e8c9 100755 --- a/scripts/start-setupModpack +++ b/scripts/start-setupModpack @@ -253,7 +253,8 @@ function handleGenericPacks() { } function handleModrinthProjects() { - : "${MODRINTH_ALLOWED_VERSION_TYPE:=release}" + # need to be backward compatible with old variable name, MODRINTH_ALLOWED_VERSION_TYPE + : "${MODRINTH_PROJECTS_DEFAULT_VERSION_TYPE:=${MODRINTH_ALLOWED_VERSION_TYPE:-release}}" : "${MODRINTH_DOWNLOAD_DEPENDENCIES:=none}" if [[ -v MODRINTH_DOWNLOAD_OPTIONAL_DEPENDENCIES ]]; then logWarning "The variable MODRINTH_DOWNLOAD_OPTIONAL_DEPENDENCIES is removed." @@ -283,7 +284,7 @@ function handleModrinthProjects() { --game-version="${VERSION}" \ --loader="$loader" \ --download-dependencies="$MODRINTH_DOWNLOAD_DEPENDENCIES" \ - --allowed-version-type="$MODRINTH_ALLOWED_VERSION_TYPE" + --allowed-version-type="$MODRINTH_PROJECTS_DEFAULT_VERSION_TYPE" fi }