Installing Modpacks

Installing Modpacks

Complete guide to the 8-step installation process, egg switching, backup creation, file preservation, config merging, direct install, and all possible errors.

Before You Install

Installation Type Detection

The plugin reads .installed_modpack.json from the server root to determine the installation type:

Tracking File Structure

.installed_modpack.json requires 6 fields:

{
    "provider": "modrinth",
    "modpack_id": "abc123",
    "modpack_name": "Create: Above and Beyond",
    "version_id": "xyz789",
    "version_name": "1.0.0",
    "installed_at": "2024-01-01T12:00:00.000Z"
}

If any field is missing, the tracking file is considered invalid → treated as Fresh install.

Tracking File Reading

The plugin uses multiple DaemonFileRepository methods to read the file, with fallbacks:

• getContent() → primary method
• getFileContents() → fallback
• Additional API methods → further fallbacks

The 8-Step Installation Process

Step 1: Preserve (💾)

Important files are saved to memory before any deletion:

Root files preserved:

• server.properties
• eula.txt
• ops.json
• banned-players.json
• banned-ips.json
• whitelist.json
• usercache.json

Directories preserved (recursive):

• /config/ — Mod configuration files
• /plugins/ — Plugin JARs and configs

Log: "[Modpack] Files preserved successfully"

Step 2: Backup (📦)

An automatic backup is created with a German-language name based on the installation type:

• Backup count is managed — oldest deleted when limit reached
• Log: "[Modpack] Backup created" with backup name and server UUID
• On failure: Log error "[Modpack] Failed to create backup" — installation continues

Step 3: Delete (🗑️)

All server files are deleted except protected directories:

Protected (never deleted):

• worlds — World data
• plugins — Plugin directory
• logs — Server logs

Log: "[Modpack] Files deleted successfully" On failure: Log error "[Modpack] Failed to delete server files"

Step 4: Download (⬇️)

1. Server is killed (stopped forcefully)
2. Egg switched to "Minecraft Modpack Installer"
3. Variables set: MODPACK_PROVIDER, MODPACK_ID, MODPACK_VERSION_ID
4. Server reinstalled — triggers the download
5. Wait for download — max 300 seconds timeout

Log: "[Modpack] Switched to installer egg" Timeout warning: "[Modpack] Download timeout" with elapsed and max_wait

Step 5: Extract (📦→📂)

After download completes, extraction is monitored:

• File stability monitoring: Checks file sizes repeatedly
• 3 consecutive stable checks = decompression complete
• Dynamic timeout based on file stability

Log/timeout: "[Modpack] Decompression timeout" if stability never reached

Step 6: Restore (♻️)

Preserved files are restored to the server:

• Root files restored to their original locations
• /config/ and /plugins/ conditionally restored:
  • If Update (keep configs): Skip /config/ and /plugins/ (they'll be merged in Step 7)
  • If Change/Fresh/Update (delete): Restore everything

Log on failure: "[Modpack] Failed to restore important files"

Step 7: Merge (🔀)

Config files are intelligently merged, preserving your custom values while incorporating new structure:

Wait: Up to 45 seconds for mods/ and config/ directories to appear after extraction.

Config Merge Strategies

Log success: "[Modpack] Config file merged successfully" with file, old_size, merged_size Log warning: "[Modpack] Could not merge config file" with file and error

Plugin Config Merging

After root config merge, the plugin also merges /plugins/PluginName/ subdirectories:

• Scans each plugin's config directory
• Merges individual config files using the same format strategies
• Skips files where old or new content is empty
• Log: "[Modpack] Plugin config file merged successfully"

Step 8: Finalize (✅)

1. Egg switched back to "Minecraft Modpack Runtime"
2. Tracking file saved: .installed_modpack.json with all 6 fields
3. Installation complete

Log: "[Modpack] Switched to runtime egg" Log: "[Modpack] Installation completed successfully" with server UUID and elapsed time

Installation Actions Matrix

Cross-Plugin Cleanup

When a modpack is installed or changed, the plugin automatically cleans up data from other plugins:

Game Mods Cleanup

• Dynamically resolves Eranio\GameMods\Services\SafeCacheService and CacheKeyService
• Clears server_installed_mods table for the server
• Flushes Game Mods cache
• Log: "Cleaned database mods for server {uuid}"
• Warning if class not found: "GameMods classes not found. Skipping cache cleanup."

Minecraft Plugins Cleanup

• Dynamically resolves Eranio\MinecraftPlugins\Services\SafeCacheService and CacheKeyService
• Clears minecraft_installed_plugins table for the server
• Flushes Minecraft Plugins cache
• Log: "Cleaned database plugins for server {uuid}"
• Warning if class not found: "MinecraftPlugins classes not found. Skipping cache cleanup."

Table Not Found Handling

If a table doesn't exist (plugin not installed): "Table '{table}' does not exist. Skipping cleanup."

Post-Response Execution

The installation runs after the HTTP response via app()->terminating() callback. This prevents Livewire serialization errors and allows the progress widget to display immediately.

Progress Widget

During installation, a custom progress widget shows all 8 steps:

Translation Keys for Steps

Complete Error Reference

Installation Start

Backup Errors

Download Errors

Extraction Errors

Restore Errors

Merge Errors

Cross-Plugin Cleanup Errors

File Operation Errors

• moveFileOrDirectory() — tries 5 rename methods with fallbacks
• writeFileToRepository() — tries 3 signature attempts for daemon compatibility
• readFileFromDaemon() — primary method + API fallback