Server-side mod management for Hytale dedicated servers. Add, install, update, and remove mods directly from in-game or console commands.
- Multiple Sources - CurseForge plus CFWidget (fallback for no API key) and Modtale (alpha, API key required). More to come.
- Full Mod Lifecycle - Add, install, update, remove mods via commands
- Update Management - Check for updates, upgrade individual mods or all at once
- Release Channels - Choose Release, Beta, or Alpha versions (global + per-mod)
- Import Existing Mods - Scan and import unmanaged mods with auto-matching
- Self-Upgrade - Update ModSync itself from GitHub Releases
- Resilient Downloads - Automatic retries with exponential backoff
- (optional) Bootstrap Plugin - Handles Windows file locking for seamless updates
- Java 25
- Hytale Server (release patchline)
- CurseForge API key (optional, but recommended for full functionality)
- Modtale API key (optional, required for Modtale)
- Download
modsync-<version>.jarfrom Releases - Place in your server's
mods/folder - Start server
- (Optional) Set your API key:
/modsync config key <provider> <key>
Get your API key from CurseForge Console or Modtale API
Note: Without an API key, ModSync uses CFWidget as fallback. CFWidget supports URL-based lookups but not search-based import matching.
| Command | Description |
|---|---|
/modsync add <url> |
Add mod from CurseForge URL |
/modsync list |
Show all managed mods with install status, version, and identifier |
/modsync install |
Install all mods from your list |
/modsync install <name> |
Install a specific mod by name, slug, or identifier |
/modsync remove <name> |
Remove mod by name, slug, or identifier |
/modsync remove all |
Remove all mods |
/modsync check |
Check for available updates (shows installed vs. latest version) |
/modsync upgrade |
Upgrade all installed mods to latest version |
/modsync upgrade <name> |
Upgrade a specific mod by name, slug, or identifier |
/modsync scan |
List unmanaged mods in the mods folder |
/modsync import |
Auto-match and import all unmanaged mods |
/modsync import <target> |
Auto-match and import a specific unmanaged mod |
/modsync import <target> --url= <url> |
Import an unmanaged mod with a specific CurseForge URL |
/modsync config |
Show all configuration settings |
/modsync config channel <value> |
Set default release channel (release/beta/alpha) |
/modsync config key <provider> <key> |
Set API key for a provider |
/modsync config welcome <on|off> |
Enable or disable the admin welcome message |
/modsync setchannel <mod> <channel> |
Set per-mod release channel override |
/modsync selfupgrade |
Check for ModSync plugin updates |
/modsync selfupgrade apply |
Download and install the latest ModSync version |
/modsync status |
Show current configuration and version |
/modsync reload |
Reload configuration from disk |
Target formats: mod name, slug, or identifier (Group:Name)
Tip: Use quotes for names with spaces:
/modsync install "My Mod"
When you install a mod, ModSync:
- Downloads the JAR file from CurseForge
- Validates the plugin manifest and calculates file hash
- Detects the plugin type (regular or early plugin) from CurseForge category
- Saves to the appropriate folder (
mods/orearlyplugins/) - Registers the mod in the installed mods registry
Note: A server restart is required to load newly installed mods.
When you remove a mod, ModSync:
- Unloads the mod if currently loaded
- Attempts to delete the JAR file
- If the file is locked (common on Windows), queues it for deletion on restart
The /modsync check command shows:
- Which mods have updates available
- Current installed version vs. latest available version
- Example:
1.0.1 -> 1.0.2
The /modsync upgrade command:
- Checks each mod for available updates
- Downloads and installs the new version
- Queues the old version for deletion
Note: A server restart is required to load upgraded mods.
Use /modsync scan to find unmanaged mods, then /modsync import to bring them under ModSync control:
- Auto-matching tries slug lookup and name search on CurseForge
- Manual import with URL:
/modsync import mymod.jar https://curseforge.com/hytale/mods/example
Note: Import and scan currently require a CurseForge API key for auto-matching. CFWidget and Modtale do not support search-based imports.
Control which release types are considered for installation and updates:
| Channel | Versions Included |
|---|---|
release |
Stable releases only (default) |
beta |
Beta and stable releases |
alpha |
All versions including alpha |
/modsync config channel beta # Set global default
/modsync setchannel MyMod alpha # Override for specific mod
/modsync setchannel MyMod default # Remove override, use global
Automatic Fallback: If a mod has no releases for your configured channel (e.g., only Beta versions but you're on Release), ModSync automatically falls back to Beta, then Alpha. A warning is shown so you know which version type was used.
The config.json file in mods/Onyxmoon_ModSync/ contains:
{
"apiKeys": {
"CURSEFORGE": "your-api-key"
},
"defaultReleaseChannel": "RELEASE",
"earlyPluginsPath": "earlyplugins",
"checkForPluginUpdates": true,
"includePrereleases": false,
"disableAdminWelcomeMessage": false
}
| Setting | Description |
|---|---|
apiKeys |
API keys per provider (currently CurseForge and Modtale) |
defaultReleaseChannel |
Global release channel (RELEASE, BETA, ALPHA) |
earlyPluginsPath |
Path for early plugins folder (default: earlyplugins) |
checkForPluginUpdates |
Check for ModSync updates on startup |
includePrereleases |
Include prerelease versions in self-upgrade checks |
disableAdminWelcomeMessage |
Disable the admin welcome message on join |
All data is stored in mods/Onyxmoon_ModSync/:
| File | Purpose |
|---|---|
config.json |
API keys and plugin settings |
mods.json |
Your mod list (shareable between servers) |
mods.lock.json |
Installation state (machine-specific) |
pending_deletions.json |
Files queued for deletion on restart |
On Windows, JAR files are locked while loaded by the JVM. This prevents deletion of old mod versions during upgrades.
The bootstrap plugin is an early plugin that runs before normal plugins load:
- Reads
pending_deletions.json - Deletes queued files before they get loaded
- Normal plugin loading proceeds
Installation (only if you have deletion issues):
- Download from modsync-bootstrap
- Place in
earlyplugins/folder - Start server with
--early-plugins --accept-early-pluginsflags
Note: On Linux dedicated servers, file locking is typically not an issue and the bootstrap plugin is usually not needed.
- Server restart required - Installing, upgrading, or removing mods requires a server restart
- Mod distribution - Mods can only be downloaded if the author has enabled "Allow Mod Distribution" in their CurseForge project settings
- No automatic restart - There is no way to trigger a server restart via the Mod API; you must restart manually
- Provider fallback - Without a CurseForge API key, ModSync uses CFWidget which supports URL lookups but not search
- Modtale (alpha) - Modtale support is experimental and requires an API key
gradlew.bat build # Windows
./gradlew build # Unix
Output: build/libs/modsync-<version>.jar
modsync/
├── src/main/java/ # Main plugin
│ └── de/onyxmoon/modsync/
│ ├── api/ # Provider interfaces, models
│ ├── command/ # All commands
│ ├── provider/ # CurseForge, CFWidget providers
│ ├── service/ # Download, scan, upgrade services
│ ├── storage/ # Config, mod registry storage
│ └── util/ # Helpers and utilities
└── bootstrap/ # Early plugin for file deletion
Provider System: SPI-based via ServiceLoader. Implement ModListProvider and register in META-INF/services to add new mod sources.
- Use for personal/non-commercial purposes
- Commercial use requires author permission