OGJ Ferium

Warning

Expect bugs and breaking changes. If you want something more stable use Ferium instead.

OGJ Ferium is like Nix but for Minecraft. Simply specify your mods, keybindings, volume sliders (literally anything) in a profile, and ogj-ferium will automatically download and configure everything for you! Share your profiles with your friends so they can have the same configurations too!

This is a separate project from Ferium with different goals! I may rename it in the future to reflect this.

Note

You can migrate your Ferium profiles to OGJ Ferium using ogj-ferium migrate. The automatic migration may fail but should work in most cases.

A profile is a text file in the TOML format. As an example, my own profile can be found here. Note that the example does not showcase all the features of ogj-ferium. I am working on better documentation.

Features

• Use the CLI to easily automate your modding experience

• Download from multiple sources, including Modrinth, CurseForge, and GitHub Releases

• Beautiful and informative UI

  Profile info and listing mods

  

  Listing mods verbosely

  

  Upgrading mods/modpacks

  

• It's super fast due to multithreading for network intensive tasks

  Your results may vary depending on your internet connection.

  It downloads theRookieCoder's modpack Kupfur with 79 mods in 15 seconds:

  upgrade.mp4

  It downloads MMTP, a very large modpack with around 400 mods, in just under a minute:

  modpack_upgrade.mp4

• Upgrade your mods and configure Minecraft in one command, ogj-ferium upgrade

  • Ferium checks that the version being downloaded is the latest one that is compatible with the configured mod loader and Minecraft version

• Create multiple profiles and configure different mod loaders, Minecraft versions, mods, etc. for each

Installation

Ferium executables from GitHub Releases do not require any external dependencies at runtime.
If you compile from source on Linux, using GCC to build will result in binaries that require GCC to be available at runtime.
On Linux, the regular versions require some sort of desktop environment to be available that offers an XDG Desktop Portal to show the folder picker. The nogui versions do not need this as they won't have a GUI folder picker, making these variants suitable for server use.

Important

Linux users! Use the nogui versions (or compile with --no-default-features) if you do not have a desktop environment (like GNOME, KDE, XFCE, etc.)

Packages

Note

Only Github Releases is supported currently.

GitHub Releases

Important

You will have to manually download and install every time there is a new update.

1. Download the asset suitable for your operating system from the latest release
2. Unzip the file and move it to a folder in your path, e.g. ~/bin on Linux or C:\Windows on Windows
3. Remember to check the releases page for any updates!

Overview / Help Page

Note

A lot of ogj-ferium's backend is implemented in libium.
It deals with things such as the config, adding mod(pack)s, upgrading, file pickers, etc.

Program Configuration

OGJ Ferium stores profile information in its config file. By default, this is located at

• $XDG_CONFIG_HOME/ferium/ogj-config.toml or ~/.config/ferium/ogj-config.toml on Linux.
• %APPDATA%/ferium/config/ogj-config.toml on Windows.
• ~/.config/ferium/ogj-config.toml on macOS.

You can change this in 2 ways; by setting the OGJ_FERIUM_CONFIG_FILE environment variable, or the --config-file global flag. The flag takes precedence.

Caution

Be mindful of syntax when manually editing the config file

You can also set a custom CurseForge API key or GitHub personal access token using the CURSEFORGE_API_KEY and GITHUB_TOKEN environment variables, or the --curseforge_api_key and --github-token global flags respectively. Again, the flags take precedence.

First Startup

Create a new profile by running ogj-ferium profile create and entering the details for your profile.

• Then, add your mods using ogj-ferium add.
• Finally, download your mods using ogj-ferium upgrade.

Automatically Import Mods

ogj-ferium scan

This command scans a directory with mods, and attempts to add them to your profile.

The directory defaults to your profile's minecraft directory. Some mods are available on both Modrinth and CurseForge; ferium will prefer Modrinth by default, but you can choose CurseForge instead using the --platform flag.

As long as you ensure the mods in the directory match the configured mod loader and Minecraft version, they should all add properly. Some mods might require you to bypass compatibility checks by using the --force flag.

Manually Adding Mods

Tip

You can specify multiple identifiers to add multiple mods at once

This also works for resourcepacks, shaderpacks, and modpacks!

Modrinth

ogj-ferium add project_id

project_id is the slug or project ID of the mod. (e.g. Sodium has the slug sodium and project ID AANobbMI). You can find the slug in the website URL (modrinth.com/mod/<slug>), and the project ID at the bottom of the left sidebar under 'Technical information'.
So to add Sodium, you can run ogj-ferium add sodium or ogj-ferium add AANobbMI.

CurseForge

ogj-ferium add project_id

project_id is the project ID of the mod. (e.g. Terralith has the project id 513688). You can find the project id at the top of the right sidebar under 'About Project'.
So to add Terralith, you should run ogj-ferium add 513688.

GitHub

ogj-ferium add owner/name

owner is the username of the owner of the repository and name is the name of the repository, both are case-insensitive (e.g. Sodium's repository has the id CaffeineMC/sodium). You can find these at the top left of the repository's page.
So to add Sodium, you should run ogj-ferium add CaffeineMC/sodium.

Important

The GitHub repository needs to upload JAR or ZIP files to their Releases for ferium to download, or else it will refuse to be added.

Overrides

If you want to use files that are not downloadable by ferium, place them in a folder and add an overrides path to that folder in your profile:

overrides = "./path/to/overrides"

Files here will be copied to the .minecraft directory when upgrading. For example, you would put mods in ./path/to/overrides/mods and resourcepacks in ./path/to/overrides/resourcepacks.

Upgrading Mods

Warning

If your mods directory is not empty when setting it, ferium will offer to create a backup.
Please do so if it contains any files you would like to keep.

Now after adding all your mods, run ogj-ferium upgrade to download all of them to your minecraft directory. This defaults to .minecraft, which is the default Minecraft resources directory. You don't need to worry about this if you play with Mojang's launcher and use the default resources directory. You can choose to pick a custom minecraft directory during profile creation or change it later.

If ferium fails to download a mod, it will print its name in red and try to give a reason. It will continue downloading the rest of your mods and will exit with an error.

Tip

When upgrading, any mods not downloaded by ferium will be moved to the mods/.old folder in the output directory. Resourcepacks and shaderpacks are unaffected. See overrides for information on how to add mods that ferium cannot download.

Managing Mods

You can list out all the mods in your current profile by running ogj-ferium list. If you want to see more information about them, you can use ogj-ferium list -v or ogj-ferium list --verbose.

You can remove any of your mods using ogj-ferium remove; just select the ones you would like to remove using the space key, and press enter once you're done. You can also provide the names, IDs, or slugs of the mods as arguments.

Important

Both mod names and GitHub repository identifiers are case insensitive.
Mod names with spaces have to be given in quotes (ogj-ferium remove "ok zoomer") or the spaces should be escaped (usually ogj-ferium remove ok\ zoomer, but depends on the shell).

Profiles

Creating

You can create a profile by running ogj-ferium profile create and specifying the following:

• Minecraft directory
  • This defaults to .minecraft which is the default Minecraft resources directory. You don't need to worry about this if you play with Mojang's launcher and use the default resources directory.
• Name of the profile
• Minecraft version
• Mod loader

If you want to copy the mods from another profile, use the --import flag. If you want to embed the profile in the config, instead of generating a file for it, use the --embed flag. You can also directly provide the profile name to the flag if you don't want a profile picker to be shown.

Note

Ferium will automatically switch to the newly created profile

Tip

You can also provide these settings as flags to avoid interactivity for things like scripts

Configure

You can configure these same settings afterwards by running ogj-ferium profile configure. Again, you can provide these settings as flags.

Manage

You can get information about the current profile by running ogj-ferium profile or ogj-ferium profile info, and about all the profiles you have by running ogj-ferium profiles or ogj-ferium profile list.
Switch to a different profile using ogj-ferium profile switch.
Delete a profile using ogj-ferium profile delete and selecting the profile you want to delete.

Feature Requests

If you would like to make a feature request, check the issue tracker to see if the feature has already been added or is planned. If not, create a new issue.

Developing

Firstly, you will need the Rust toolchain, which includes cargo, rustup, etc. You can install these using rustup. You can manually run cargo commands if you wish, but I recommend using the justfile configuration in the repository. just is a command runner that is basically a much better version of make.

To build the project and install it to your Cargo binary directory, clone the project and run just install. If you want to install it for testing purposes, add the nightly toolchain and run just (aliased to just install-dev), which has some optimisations to make compilation faster.

You can run integration tests using cargo test, lint using cargo clippy, and delete all build and test artefacts using just clean.

If you would like to see how to cross-compile for specific targets (e.g. Linux ARM) or other information such as the development libraries required, have a look at the workflow file.
If you still have doubts, feel free to create a discussion and I will try help you out.