Skip to content

feat(mcserver): add Forge and NeoForge variants - #5239

Open
dgibbs64 wants to merge 2 commits into
developfrom
feature/mc-forge-variants
Open

dgibbs64 wants to merge 2 commits into
developfrom
feature/mc-forge-variants

Conversation

@dgibbs64

Copy link
Copy Markdown
Member

Description

Adds Forge and NeoForge as Minecraft: Java Edition variants, using the variant setting added for Fabric, Paper, Purpur, Folia and Leaf.

./mcserver install --variant neoforge
./mcserver update --variant forge --version 1.21.10
  • Both are installed by running their installer with --installServer. The installer writes the launch arguments to libraries/.../unix_args.txt; LinuxGSM copies that to serverfiles/unix_args.txt and starts the server with java -Xmx<javaram>M @user_jvm_args.txt @unix_args.txt nogui. javaram keeps working, and JVM options added to user_jvm_args.txt are used too.
  • Forge uses the recommended build for the Minecraft version, or the latest build when there is no recommended one. Minecraft older than 1.17 is refused with a clear error, as those Forge versions use a different install layout.
  • NeoForge versions follow the Minecraft version (1.21.10 is 21.10.x, 26.3 is 26.3.0.x). Beta builds are only used with branch="snapshot".
  • Installers are verified against the SHA1 published next to them.
  • check_executable.sh ignores a leading @ so it finds unix_args.txt.
  • start, debug and details reload the start parameters from the config, which put -jar back in front of @unix_args.txt. The variant start settings are now applied again by one function, fn_variant_startparameters, which replaces the three copies of the startparameters and fs_basepath handling.
  • Switching between Fabric, Forge and NeoForge warns that the mods directory holds mods for the old loader.

Fixes #4907
Related to #2299

Affected servers: mc

Type of change

  • Bug fix (a change which fixes an issue).
  • New feature (a change which adds functionality).
  • New Server (new server added).
  • Refactor (restructures existing code).
  • Chore (CI, workflows, tooling or other maintenance).
  • Comment update (typo, spelling, explanation, examples, etc).

Testing

Tested on a test server in a clean ubuntu-26.04 container, with this branch:

  • auto-install --variant neoforge --version latest: EULA accepted, NeoForge 26.3.0.103 installer downloaded and verified by SHA1, installer ran, variant.txt and build.txt written. Server reached "Done", one monitor passed with the started lock unchanged.
  • update --variant forge: Forge 26.3-66.1.8 (recommended build) installed over NeoForge, with the mods warning. Reached "Done", monitor passed, started lock unchanged.
  • update --variant neoforge --version 1.21.10: NeoForge 21.10.64 installed. Reached "Done" on a new world, monitor passed, started lock unchanged. (A world saved by 26.3 won't load on 1.21.10, which is a Minecraft limit.)
  • details shows java -Xmx1024M @user_jvm_args.txt @unix_args.txt nogui for both loaders.
  • update with nothing new reports "No update available".
  • update --variant forge --version 1.16.5 fails with "Forge for Minecraft 1.16.5 is not supported. Use Minecraft 1.17 or newer."
  • Version lookups checked for Forge (recommended, latest-only and latest) and NeoForge (1.21, 1.21.10, 26.3, latest, betas skipped on release).
  • shellcheck clean on the changed modules.

Risk and rollback

  • Risk level: low. Existing variants behave the same. The shared changes are the @ strip in check_executable.sh and moving the variant start-parameter handling in start, debug and details into fn_variant_startparameters, which does the same thing for the other variants.
  • Rollback plan: revert this PR. Servers already switched to Forge or NeoForge can switch back with ./mcserver update --variant vanilla.

Breaking changes

  • No breaking changes.
  • Breaking changes included (describe below).

Documentation

Checklist

PR will not be merged until all steps are complete.

  • This pull request links to an issue ("Fixes", or "Related to" for a partial fix).
  • This pull request uses the develop branch as its base.
  • This pull request subject follows the Conventional Commits standard.
  • This code follows the style guidelines of this project.
  • I have performed a self-review of my code.
  • I have provided a detailed enough description of this PR.

Thank you for your Pull Request!

Forge and NeoForge are installed by running their installer with
--installServer. The installer writes the launch arguments to
libraries/.../unix_args.txt, which LinuxGSM copies to serverfiles and
starts with: java -Xmx<javaram>M @user_jvm_args.txt @unix_args.txt nogui.
javaram keeps working and JVM options added to user_jvm_args.txt are used.

Forge uses the recommended build for the Minecraft version, or the latest
build when there is no recommended one. Minecraft older than 1.17 is
refused: those Forge versions use a different install layout.

NeoForge versions follow the Minecraft version (1.21.10 is 21.10.x,
26.3 is 26.3.0.x). Beta builds are only used with branch="snapshot".

Installers are verified against the SHA1 published next to them.

The executable check now ignores a leading @ so it finds unix_args.txt.
Switching between Fabric, Forge and NeoForge warns that the mods
directory holds mods for the old loader.
fn_reload_startparameters reloads preexecutable from the config in
start, debug and details, which put -jar back in front of @unix_args.txt.
NeoForge then failed to start.

The variant start settings are now applied by one function,
fn_variant_startparameters, called after each reload. It replaces the
three copies of the startparameters and fs_basepath handling.
@dgibbs64 dgibbs64 added this to the v26.7.0 milestone Nov 14, 2026
@github-actions github-actions Bot added type: feature New feature or request engine: lwjgl2 Issues related to lwjgl2 engine game: Minecraft Issues related to Minecraft labels Nov 14, 2026
@dgibbs64 dgibbs64 linked an issue Nov 14, 2026 that may be closed by this pull request
2 tasks done
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

engine: lwjgl2 Issues related to lwjgl2 engine game: Minecraft Issues related to Minecraft type: feature New feature or request

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[Server Request]: Minecraft Forge

1 participant