Mindustry mod not loading: ZIP, JAR and dependency checks
Check ZIP vs JAR, wrapper folders, dependency names and restart steps for Mindustry mods, with a recorded 160.7 example and source-reviewed package cases.
Start with the game, version and unchanged ZIP
Confirm that the unmodified game starts before diagnosing a new mod. Back up existing game data and use a separate lab profile if you already play. Record the exact game build and mod version; a newer release is not automatically a compatible one.
For this example, start with the published ModLab Homing Lab 0.1.0 ZIP and Mindustry 160.7 desktop. The package declares minGameVersion 160.7. That minimum is not proof that every later version works; 160.7 is the build covered by our recorded test.
Running the prebuilt ZIP needs no coding agent, fal key, paid generated assets or separate Java installation in the tested official Mac distribution. Editing it with an AI agent is a separate workflow and may use that agent’s paid allowance.
Use the game’s actual mods folder, then restart
Open Mods → Open Folder in Mindustry. Quit the game, copy the supplied ZIP into that folder and relaunch. Keep the downloaded package zipped. In our Mac test, Import Mod → Import File did not open a file picker; copying the ZIP into the game-selected folder was the verified route.
Check that the mod is enabled in Mods. Avoid installing an extracted copy and the same ZIP together. If other mods are present, keep backups and reproduce with only this example enabled through the game’s normal controls.
Finding a folder named mods elsewhere is not enough. Use the folder opened by the same game installation and profile you are actually launching. Replacing the archive while the game is still running does not establish that the new files were loaded.
Check the ZIP root after making an edit
The supplied archive has mod.json at its root, alongside content, scripts and sprites. For this example, keep that simple layout when repacking. A wrapper folder is not automatically invalid: Mindustry v160.7 resolves one top-level directory when it is the only top-level entry, then searches there for metadata. A second nesting level or a sibling file can change which root is inspected. Compare the layouts below instead of diagnosing from the ZIP filename alone.
On macOS or Linux, the read-only command below lists archive paths without running the mod. On Windows, inspect the ZIP with an archive viewer. This checks packaging only; it does not prove that scripts or game content load successfully.
For the suggested experiment, change only homingPower in content/blocks/homing.json from 0.08 to 0.02. Keep baseline.json unchanged. The 0.02 variation is a learner experiment whose result has not been tested by ModLab.
unzip -l modlab-homing-lab-0.1.0.zip
# Expected archive paths include:
# mod.json
# content/blocks/baseline.json
# content/blocks/homing.json
# scripts/main.js
# sprites/baseline.png
# sprites/homing.pngCompare three archive layouts before repacking
Case A is the published ModLab ZIP: mod.json is at the archive root. The existing installation record covers that package. Cases B and C below are invented layouts, not downloaded mods or new game tests.
Case B has only one top-level folder, sample-main. In the v160.7 loader, that folder becomes the inspected root, where mod.json can be found. Its metadata being found does not prove that its scripts, content or dependencies work.
Case C adds README.txt beside sample-main at the top level. The loader now sees two entries and keeps the outer root; no metadata file is present at that root. Check the archive listing and first load error. A double wrapper likewise exceeds the one-directory normalization shown in this source version. Other game versions need their own source check.
# A: published package layout
mod.json
content/blocks/homing.json
scripts/main.js
# B: illustrative single wrapper
sample-main/mod.json
sample-main/scripts/main.js
# C: illustrative wrapper plus sibling
sample-main/mod.json
sample-main/scripts/main.js
README.txtChoose a content ZIP, compiled Java JAR or server plugin
The ModLab example uses JSON content and JavaScript. A Java mod is a different package: the official guide says JAR mods must be compiled, and a project’s Source code (zip) is not its compiled release asset. Renaming a source ZIP to .jar does not compile Java.
Illustrative Java case: mod.hjson declares main: "example.ExampleMod", but the archive contains only src/example/ExampleMod.java and no compiled example/ExampleMod.class. That listing does not supply the declared entry class. Obtain the maintainer’s compiled JAR for your game build from a trusted release, or follow that project’s build instructions; do not edit the name or version just to suppress a warning.
The official plugin guide describes plugins as server-only Java mods. They use plugin.json or plugin.hjson and belong in the server directory’s config/mods. Putting a server plugin into a desktop client is not a route to a client-side content block. This workshop does not test Java mods, Android, iOS or servers.
Check dependency IDs and the first reported failure
The required dependencies list refers to a mod’s internal name, not its displayName, ZIP filename or repository name. The official documentation normalizes names to lowercase with spaces changed to hyphens. Inspect the dependency’s metadata and the game’s Mods state before changing your own package.
Illustrative dependency case: a package declares dependencies: ["example-core"], while another installed package merely has displayName: "Example Core". That display label alone does not establish the required internal name, enabled state or compatible version. Match the metadata name and resolve the reported missing dependency first; do not delete the dependency declaration to hide the problem.
The published ModLab Homing Lab 0.1.0 metadata has name "modlab-homing", minGameVersion "160.7" and no required dependencies field. This is a read-only package observation; it does not show that every later game build is compatible. For another package, keep its version constraints intact and record the earliest relevant error, game build, mod version and package type. Redact personal paths or secrets before sharing logs.
Separate missing content from an arena-launch problem
After restarting with the example enabled, look for ModLab Homing Lab [F8] in the main menu. That menu item is evidence that the helper script loaded. Then open it, or press F8; some Macs require Fn + F8. Exit any active world first and stay in single player.
A menu item alone does not prove that the whole experiment works. Check the two lanes, projectile movement and the run finishing. The arena supplies copper automatically. If the game reports a mod error, record the first relevant message, game build and package version before changing several things at once.
Our fixed, scripted comparison recorded 1/25 straight hits and 24/25 homing hits in one 30-second run, then reproduced those counts after a clean ZIP installation. These observations demonstrate steering in that arena. They are not normal-play damage statistics or a guaranteed hit count for your machine.
Disable the example and confirm recovery
Press F9 to exit the temporary arena. Disable or remove ModLab Homing Lab through Mods and restart. In the recorded recovery check, the ModLab menu entry disappeared after the restart. Verify that result rather than assuming removal succeeded.
Keep campaign saves separate from the lab. A world that contains custom blocks may need the corresponding mod to load. Disabling a mod is not a promise that every previously modified save can be opened without it.
For another game, use that game’s loader and version requirements. Check the actual output path, required dependencies and the first relevant error, then verify a real game action and a restart. The Mindustry-specific folder and keyboard steps above are not a universal fix.
Inspect the recorded example and original package
Open the Mindustry workshop for the original ZIP, real gameplay capture and instructions. Compare the exact version and environment in the downloadable verification record before applying these observations to another setup.
Common loading questions
Is a folder around mod.json always a broken ZIP?
No. Mindustry v160.7 resolves one top-level directory when it is the only top-level entry, then looks there for metadata. A sibling file or a second wrapper changes that check. The layout cases on this page are source-reviewed examples, not additional in-game tests.
Can I rename a Java source ZIP to JAR?
No. Java mods need compiled classes in a suitable JAR. Use the maintainer’s compiled release for your game build or follow its build instructions. A source ZIP and a filename change do not provide a compiled entry class.
Does a dependency use the display name or filename?
Required dependencies refer to the normalized internal mod name from metadata. A displayName, archive filename or repository name alone does not establish that the needed mod is present and enabled. Check the metadata and the game’s first dependency error; do not remove the declaration to hide it.
Why is the Mindustry mod missing after I copy the ZIP?
Check the folder opened by Mods → Open Folder in the same game profile, confirm the mod is enabled and restart. The supplied ZIP contains mod.json at its root. Mindustry v160.7 can unwrap a single top-level folder when it is the only entry, so a wrapper alone is not proof of failure. Avoid installing both a folder copy and the same ZIP.
What if Import File does not open on Mac?
It did not open a picker in our macOS 15.7 test. Mods → Open Folder, quitting the game, copying the unchanged ZIP and relaunching was the verified alternative. This observation does not establish that the file picker fails on every Mac.
Do I need Universal Modder or a fal key to run the example?
No. The prebuilt Mindustry ZIP can be played without a coding agent, API key or paid generated assets. Universal Modder is used when researching or editing with an agent. An agent’s own usage charges can still apply to that separate workflow.
How can I tell that the example actually loaded?
Look for ModLab Homing Lab [F8] in the main menu, then open the arena and verify projectile movement and a completed run. A menu item checks script discovery; a real arena run checks more of the mod. Compilation or an archive listing alone proves neither.
How do I undo the ModLab Homing Lab installation?
Exit the arena with F9, disable or remove the mod in Mods and restart. Confirm that its menu item is gone. Keep lab work separate from campaign saves, because a world containing custom blocks may require the mod to load.
Has homingPower 0.02 been tested?
No. The recorded example compares homingPower 0 with 0.08. Changing only 0.08 to 0.02 is a suggested learner experiment. Run and record your own comparison before making any claim about that variation.
Compare version-sensitive instructions with the current upstream documentation.
Upstream documentation ↗Package rules: Mindustry v160.7 loader source · Official Java mod and plugin guide. The source check supports the illustrative layouts; the separately linked gameplay record supports only the published ModLab ZIP and its stated environment.