FFModsSubfolders
Overview
Loads mods from nested folders in the mods directory.
Features
- Organize other mods into subfolders and disable entire folders by suffix.
- Includes Sinytra Connector integration and configurable scan behavior.
Getting started
- Put FFModsSubfolders itself directly in
mods. - Create some subfolders and move your other NeoForge mods into them.
- Start the game. Look for
[mod scan]in the log for a scan summary and any warnings.
Rename a folder to end in .disabled to skip everything inside it, including deeper folders. For example, mods/testing.disabled/ is ignored. Renaming it back enables it again on your next launch. Folder suffix matching is case-insensitive.
Configuration
After the first launch, edit config/ffmodsubfolders-common.toml. Changes affect the next launch because mod discovery happens before normal configuration registration. Config editing mods can also show the translated setting names and tooltips.
| Group | Setting | Default | Purpose |
|---|---|---|---|
general |
enabled |
true |
Enable recursive scanning. |
general |
disabledFolderSuffix |
.disabled |
Skip folders ending with this nonblank suffix. |
general |
maxScanDepth |
32 |
Maximum folder depth, from 1 to 256. |
logging |
logIndividualSubfolders |
true |
Log each scanned folder. |
logging |
logEmptySubfolders |
false |
Include empty folders in normal logs. |
logging |
warnOnDuplicateJarNames |
true |
Warn about repeated jar filenames. |
sinytraConnector |
enableConnectorIntegration |
true |
Pass scanned folders to Connector when available. |
The default depth of 32 counts mods/a/ as level 1. Symlink loops are skipped. Unreadable folders, empty jars and duplicate filenames produce diagnostic messages.
Compatibility and limitations
- FFModsSubfolders must stay directly in
mods. Its startup scanner can't discover itself. - Minecraft 1.20.6 through 1.21.8: the early wrapper relay supports embedded mod jars such as Sodium's NeoForge packaging. Sodium should still stay at the top level if you need its pre-window GPU-driver workarounds. A startup hook can't be replayed after it has already run.
- Minecraft 1.20.4 and 1.21.9 or newer: mods providing early startup services, custom mod locators, graphics bootstrappers or loading-screen replacements must stay directly in
mods. These versions use different startup systems, with early services discovered before subfolder scanning. Regular mods still load from subfolders; the log warns when it finds an early-service jar there. - Sinytra Connector: where a compatible Connector version exists, keep Connector itself directly in
mods. The integration passes subfolder locations to Connector for the Fabric mods it supports. Connector compatibility has been checked on 1.21.1 only. This is not native Fabric-loader support. - Folder paths containing commas can't be passed to Connector. Native NeoForge scanning still works, and the log names the affected folders.
- Only one early loading-screen provider can be active. Unusual startup mods need checking individually; a successful ordinary-mod scan doesn't verify every hook.
- There is no datapack support.
Requirements and source version
| Minecraft | 1.20.4, 1.20.6, 1.21, 1.21.1 through 1.21.11, 26.1, 26.1.1, 26.1.2, 26.2, 26.3 |
|---|---|
| Loader | NeoForge only. Choose the jar and NeoForge build matching Minecraft; checked loader ranges are listed below. Java 17 for 1.20.4, Java 21 for 1.20.6 and 1.21.x, Java 25 for 26.x. |
| Source version | 0.6.0 |
The Modrinth button is enabled only when a published project link is configured. The source version above may be newer than the latest published file.
Checked NeoForge targets
| Minecraft | Build checked | Allowed NeoForge range |
|---|---|---|
| 1.20.4 | 20.4.251 | [20.4.251,20.5) |
| 1.20.6 | 20.6.141 | [20.6.141,20.7) |
| 1.21 | 21.0.167 | [21.0.167,21.1) |
| 1.21.1 | 21.1.252 | [21.1.244,21.2) |
| 1.21.2 | 21.2.1-beta | [21.2.1-beta,21.3) |
| 1.21.3 | 21.3.97 | [21.3.97,21.4) |
| 1.21.4 | 21.4.158 | [21.4.158,21.5) |
| 1.21.5 | 21.5.98 | [21.5.98,21.6) |
| 1.21.6 | 21.6.20-beta | [21.6.20-beta,21.7) |
| 1.21.7 | 21.7.25-beta | [21.7.25-beta,21.8) |
| 1.21.8 | 21.8.54 | [21.8.54,21.9) |
| 1.21.9 | 21.9.16-beta | [21.9.16-beta,21.10) |
| 1.21.10 | 21.10.64 | [21.10.64,21.11) |
| 1.21.11 | 21.11.45 | [21.11.45,21.12) |
| 26.1 | 26.1.0.19-beta | [26.1.0.19-beta,26.1.1) |
| 26.1.1 | 26.1.1.15-beta | [26.1.1.15-beta,26.1.2) |
| 26.1.2 | 26.1.2.114 | [26.1.2.114,26.1.3) |
| 26.2 | 26.2.0.88 | [26.2.0.88,26.3) |
| 26.3 | 26.3.0.43-beta | [26.3.0.43-beta,26.4) |
Some short-lived Minecraft releases only have beta NeoForge builds. Minecraft 1.20.1, 1.20.2, 1.20.3 and 1.20.5 are not supported by these downloads. Connector and client graphics compatibility are not verified across this matrix.
Installation and startup services
Choose the jar for your Minecraft version and keep FFModsSubfolders directly in mods. No other mod is required. On 1.20.4 and 1.21.9 or newer, other mods providing early startup services must also stay directly in mods; misplaced jars produce a warning. Connector compatibility was previously checked on 1.21.1 and is not verified for the new targets.