Optional Modrinth projects (graceful skip on version mismatch)

[Vianpyro]

Enhancement Type

Improve an existing feature

Describe the enhancement

Describe the enhancement

Problem

When using MODRINTH_PROJECTS with VERSION=LATEST (or VERSION_FROM_MODRINTH_PROJECTS=true), the server startup fails entirely if any listed mod doesn't have a compatible version for the target Minecraft release. This is frustrating for mods that are "nice to have" but not required for the server to function -- like map renderers (Pl3xmap), aesthetic plugins, or QoL mods that tend to lag behind on updates.

Today, the only workaround is to manually remove/comment the mod from MODRINTH_PROJECTS every time you upgrade, then re-add it once the author publishes a compatible build. This defeats the purpose of automatic version management.

Proposed solution

Allow marking individual entries in MODRINTH_PROJECTS as optional using a ? suffix on the project slug/ID:

MODRINTH_PROJECTS: |
  fabric-api
  lithium
  pl3xmap?
  bluemap?:beta

Behavior:

1. Download phase: if an optional mod has no compatible version for the current Minecraft release, log a warning and continue startup instead of failing.
2. Version resolution (VERSION_FROM_MODRINTH_PROJECTS=true): only required (non-?) projects are considered when computing the target Minecraft version. Optional mods never block a version upgrade.

The ? marker works with all existing format combinations:

Format	Example
Slug only	pl3xmap?
With version	pl3xmap?:Oa9ZDzZq
With release type	pl3xmap?:beta
With loader prefix	fabric:pl3xmap?
Full combination	fabric:pl3xmap?:beta

Use case

environment:
  TYPE: FABRIC
  VERSION_FROM_MODRINTH_PROJECTS: true
  MODRINTH_PROJECTS: |
    fabric-api
    lithium
    pl3xmap?

When Minecraft 26.2 drops and fabric-api + lithium support it but pl3xmap doesn't yet:

• The server upgrades to 26.2 automatically (pl3xmap doesn't hold it back)
• The server starts without pl3xmap, logging a warning
• Once pl3xmap publishes a 26.2 build, the next container restart picks it up automatically

[itzg]

I understand the motivation for the feature idea, but isn't an incomplete server an invalid and non-deterministic outcome. Clients that connect to the server will fail when the mod list doesn't match what it required.

With that said, the enhancement seems reasonable since it's the server admin's choice to select that behavior.

[Vianpyro]

Good point, I should have been clearer about the use case. I'm thinking mainly about server-side mods that don't affect the client's mod list at all. A few examples:

• Map renderers: Pl3xmap, BlueMap, Dynmap, they generate web maps, clients don't need them
• Server optimizations: Lithium, C2ME, FerriteCore, Chunky, performance mods that are transparent to clients
• Monitoring: Spark, profiling tool, no client interaction

None of these would cause a client mod-list mismatch since they're never part of the handshake. The server is fully playable without them, you just lose the extra functionality they provide.

So the idea is really: "don't let a lagging Spark or BlueMap update block me from upgrading to a new Minecraft version when my actual gameplay mods are ready"

[itzg]

Ok yeah, I was assuming that was probably the use case in mind.