Managing Modpacks

Managing Modpacks

View installed modpack status, update to new versions, change modpacks, and understand the tracking system.

Installed Modpack View

The Installed tab shows information about the currently installed modpack:

This data comes from .installed_modpack.json on the server root.

Updating a Modpack

How Update Detection Works

When viewing a modpack you already have installed:

1. Plugin reads .installed_modpack.json for current version
2. Compares with available versions from the provider
3. Newer versions shown with Update option

Update Options

When updating (🟠 type), you get two choices:

Recommended: "Keep configs" for most updates — preserves your customizations.

After Updating

1. Wait for the 8-step progress to complete
2. Restart the server
3. Verify the modpack loads correctly
4. Check merged configs for any issues

Changing to a Different Modpack

Changing modpacks (🔴 type) is the most destructive operation:

1. Full backup created automatically
2. All files deleted (except worlds, plugins, logs)
3. Cross-plugin cleanup runs (Game Mods + Minecraft Plugins data cleared)
4. New modpack downloaded and installed
5. Important files restored

Warning: Changing modpacks clears all mod and plugin tracking data from other Eranio plugins.

Reinstalling the Current Modpack

Reinstalling (🔵 type) re-downloads and re-installs the same modpack and version:

• Useful for fixing corrupted installations
• Backup created before reinstall
• Configs can be kept or replaced

Console Widget

A widget on the server console page tracks modpack status:

• Cache: 5 minutes for update checks
• Shows installed modpack info
• Alerts when updates are available with redirect to Modpack Browser

Troubleshooting

".installed_modpack.json" is missing

• No modpack has been installed via the plugin yet
• File was manually deleted
• The plugin treats this as a Fresh install

Tracking file is invalid

• One or more of the 6 required fields is missing
• File contains invalid JSON
• Treated as Fresh install

Modpack loads but crashes on start

1. Check server console for error messages
2. Verify Java version matches modpack requirements (8, 11, 16, 17, or 21)
3. Check RAM allocation — modpacks often need 4-8+ GB
4. Verify mod loader version compatibility
5. Try reinstalling with "Delete configs" option

Config merge caused issues

• Some mods change config format between versions — merge can conflict
• Solution: Reinstall with "Delete configs", then manually re-apply your changes
• Check storage/logs/laravel.log for merge warnings

Server stuck on installer egg

• Installation may have failed during Step 4-5
• Manually switch the egg back to runtime in Admin Panel → Servers → [Server] → Build
• Check logs for timeout or download errors

Cross-plugin data not cleared

• Other plugins (Game Mods, Minecraft Plugins) may not be installed
• Log shows "GameMods classes not found" or "MinecraftPlugins classes not found"
• Non-critical — can manually clear via each plugin's "Clear Cache" button

⚠️ "Clear Cache" clears everything

• The modpack plugin's clearCache() uses Cache::flush() which is a global cache flush
• This clears ALL cached data for ALL plugins and the entire panel
• After clearing: other plugins may be slow until their caches repopulate
• Use sparingly — prefer waiting for TTL expiry when possible

Provider Internal Functions Reference

This section documents the internal PHP code for each provider integration, including API parameters, response schemas, rate limits, and response processing logic.

CurseForge Provider (Modpacks) — Complete Reference

Uses the same CurseForge API as the other plugins but with classId=4471 (Modpacks).

API Endpoint Parameters — GET /v1/mods/search

Response Schema — Search Results

Rate Limits

// Modpack search (classId=4471) — the only difference from mods/plugins
$response = Http::withHeaders(['x-api-key' => $apiKey])
    ->timeout($timeout)
    ->get('https://api.curseforge.com/v1/mods/search', [
        'gameId'        => 432,      // Minecraft
        'classId'       => 4471,     // ⚠ Modpacks — NOT 9137 (Mods) or 5 (Plugins)!
        'searchFilter'  => $query,
        'sortField'     => $query ? 1 : 2,
        'sortOrder'     => 'desc',
        'gameVersion'   => $mcVersion,
        'pageSize'      => $perPage,
        'index'         => ($page - 1) * $perPage,
    ]);

// Response processing — modpacks to card data
$results = $response->json('data', []);
$packs = collect($results)->map(function ($mod) {
    return [
        'id'         => $mod['id'],
        'name'       => $mod['name'],
        'slug'       => $mod['slug'],
        'summary'    => $mod['summary'],
        'author'     => $mod['authors'][0]['name'] ?? 'Unknown',
        'downloads'  => $mod['downloadCount'],
        'icon_url'   => $mod['logo']['url'] ?? null,
        'provider'   => 'curseforge',
    ];
});

// Server pack detection — prefer server pack over client pack
// Some CurseForge modpacks offer a separate "server pack" file
if (!empty($fileData['serverPackFileId'])) {
    $serverPack = $this->getFile($modId, $fileData['serverPackFileId']);
    // Use server pack instead for server installations — smaller, no client-side mods
}

// Modpack file structure — overrides/ folder + manifest.json
// CurseForge modpacks contain Murmur2-fingerprinted modules
foreach ($file['modules'] as $module) {
    // module['name']        => e.g. "overrides", "manifest.json"
    // module['fingerprint'] => Murmur2 hash for file integrity verification
    // overrides/ folder is extracted to the server root
}

CurseForge Modpacks Provider Error Map

Modrinth Provider (Modpacks) — Complete Reference

API Endpoint Parameters — GET /v2/search

Modpack-Specific Facets

// The plugin builds facets specifically for modpacks
$facets = [
    ['project_type:modpack'],                    // Must be modpack, not mod/plugin
];
if ($mcVersion) $facets[] = ["versions:$mcVersion"];
if ($loader)    $facets[] = ["categories:$loader"];  // e.g., categories:forge

$params['facets'] = json_encode($facets);

Response Schema — Search Results

Rate Limits

// Modpack search with modpack-specific facets
$response = Http::timeout($timeout)
    ->get('https://api.modrinth.com/v2/search', [
        'query'  => $query,
        'facets' => json_encode([
            ['project_type:modpack'],
            $mcVersion ? ["versions:$mcVersion"] : [],
            $loader ? ["categories:$loader"] : [],
        ]),
        'limit'  => $perPage,
        'offset' => ($page - 1) * $perPage,
    ]);

// Response processing
$hits = $response->json('hits', []);
$packs = collect($hits)->map(function ($hit) {
    return [
        'id'         => $hit['project_id'],
        'name'       => $hit['title'],
        'slug'       => $hit['slug'],
        'summary'    => $hit['description'],
        'author'     => $hit['author'],
        'downloads'  => $hit['downloads'],
        'icon_url'   => $hit['icon_url'] ?? null,
        'versions'   => $hit['versions'] ?? [],
        'provider'   => 'modrinth',
    ];
});

// Modrinth modpacks use .mrpack format (ZIP file)
// Structure: modrinth.index.json + overrides/
$manifest = json_decode($zip->getFromName('modrinth.index.json'), true);
foreach ($manifest['files'] as $file) {
    // $file['path']            => target path relative to server root
    // $file['downloads']       => array of download mirror URLs
    // $file['hashes']['sha1']  => SHA-1 for integrity check
    // $file['hashes']['sha512'] => SHA-512 for integrity check
    // $file['fileSize']        => expected file size in bytes
}
// overrides/ directory is extracted to server root

Modrinth Modpacks Provider Error Map

FeedTheBeast (FTB) Provider — Complete Reference

FTB API at https://api.feed-the-beast.com/v1. No authentication required. Uses a unique two-step loading pattern.

API Endpoint Parameters — GET /v1/modpacks/public/modpack/all

API Endpoint Parameters — GET /v1/modpacks/public/modpack/{packId}

API Endpoint Parameters — GET /v1/modpacks/public/modpack/search/{limit}

Response Schema — All Packs

Response Schema — Pack Details

Response Schema — Search

Rate Limits

// Step 1: Get all FTB pack IDs
$all = Http::timeout($timeout)
    ->get('https://api.feed-the-beast.com/v1/modpacks/public/modpack/all');
// Returns: { "packs": [100, 200, 300, ...], "total": 150 }
// ⚠ Pack ID 81 is FTB's test pack — MUST be filtered out!
$packIds = collect($all->json('packs', []))->reject(fn ($id) => $id === 81);

// Step 2: Fetch details for each pack (batched with concurrency control)
$packs = $packIds->map(function ($id) use ($timeout) {
    $pack = Http::timeout($timeout)
        ->get("https://api.feed-the-beast.com/v1/modpacks/public/modpack/{$id}")
        ->json();

    return [
        'id'         => $pack['id'],
        'name'       => $pack['name'],
        'summary'    => $pack['synopsis'] ?? '',
        'icon_url'   => collect($pack['art'] ?? [])->firstWhere('type', 'square')['url'] ?? null,
        'downloads'  => $pack['installs'] ?? 0,
        'versions'   => collect($pack['versions'] ?? [])->pluck('name')->toArray(),
        'provider'   => 'ftb',
    ];
});

// Search FTB packs — returns pack IDs that match, then fetch details
$search = Http::timeout($timeout)
    ->get("https://api.feed-the-beast.com/v1/modpacks/public/modpack/search/100", [
        'term' => $query,
    ]);
// Returns: { "packs": [100, 200], "curseforge": [], "total": 2 }
// The numeric suffix (100) is the max result count
// "curseforge" array contains cross-referenced CurseForge mod IDs

// Server pack download — requires version ID for platform-specific download
$serverUrl = "https://api.feed-the-beast.com/v1/modpacks/public/modpack/{$packId}/versions/{$versionId}/server/linux";
// Alternative: .../server/windows for Windows servers
// Downloads a server installer script/ZIP

FTB-specific behaviours:

• Two-step loading: First GET .../all for IDs → then GET .../{id} per pack for details
• Search returns pack IDs (not full objects) — requires second step to get details
• Pack ID 81 is always filtered out — it's FTB's internal test pack
• art array has type: "square" (logo) and type: "splash" (banner)
• status: "released" = public; "private" = needs special access code
• Server downloads are platform-specific: /server/linux or /server/windows
• Version type can be "Release", "Beta", or "Alpha" — only Release shown by default
• Modpack data is cached for 24 hours per pack

FTB Provider Error Map

Technic Platform Provider — Complete Reference

Technic API at https://api.technicpack.net. Requires a build parameter for launcher version compatibility.

API Endpoint Parameters — GET /search/modpacks/{query}

API Endpoint Parameters — GET /modpack/{slug}

Response Schema — Search (Dictionary Format!)

Response Schema — Pack Details

Rate Limits

// Search Technic modpacks — note dictionary response format
$response = Http::timeout($timeout)
    ->get("https://api.technicpack.net/search/modpacks/{$query}", [
        'build' => 822,  // ⚠ Must be a valid Technic Launcher build number!
    ]);

// IMPORTANT: Technic returns a DICTIONARY keyed by slug, not an array!
$modpacks = $response->json('modpacks', []);
// $modpacks = { "tekkit": { ... }, "hexxit": { ... } }
// Must use array_values() or collect() to iterate
$packs = collect($modpacks)->map(function ($pack, $slug) {
    return [
        'id'         => $slug,
        'name'       => $pack['displayName'] ?? $pack['name'],
        'summary'    => '', // Technic search doesn't return descriptions
        'downloads'  => $pack['runs'] ?? 0,
        'mc_version' => $pack['minecraft'] ?? 'Unknown',
        'provider'   => 'technic',
    ];
});

// Get specific modpack details — includes download URL
$pack = Http::timeout($timeout)
    ->get("https://api.technicpack.net/modpack/{$slug}", [
        'build' => 822,
    ])->json();

// Response processing — extract pack metadata
$result = [
    'name'        => $pack['displayName'] ?? $pack['name'],
    'url'         => $pack['url'],              // Direct ZIP download URL
    'platform'    => $pack['platformUrl'],       // Technic website page
    'mc_version'  => $pack['minecraft'] ?? '',   // MC version string
    'runs'        => $pack['runs'] ?? 0,
    'icon'        => $pack['icon']['url'] ?? null,
    'logo'        => $pack['logo']['url'] ?? null,
];
// url field → direct download of modpack ZIP (server or client)

Technic-specific behaviours:

• Search returns a dictionary keyed by slug, not an array — must be converted
• build parameter is required — controls API compatibility version
• minecraft field contains the MC version string directly (not an array)
• platformUrl links to the Technic website page for the pack
• url field → direct ZIP download (used for both client and server packs)
• runs counts the number of times the modpack has been launched (not downloads)
• No server-specific packs — same ZIP for client and server; manual extraction needed
• No pagination — search returns all matching packs at once

Technic Provider Error Map

ATLauncher Provider — Complete Reference

ATLauncher uses a GraphQL API at https://api.atlauncher.com/v2/graphql. This is the only GraphQL-based provider.

GraphQL Endpoint — POST /v2/graphql

Available Query Fields

Rate Limits

// GraphQL query for ATLauncher pack listing
$query = <<<'GRAPHQL'
{
    packs(first: 20) {
        edges {
            node {
                id
                name
                description
                type
                versions {
                    version
                    minecraft
                }
            }
        }
    }
}
GRAPHQL;

$response = Http::timeout($timeout)
    ->post('https://api.atlauncher.com/v2/graphql', ['query' => $query]);

// Response processing for ATLauncher GraphQL
$data = $response->json('data.packs.edges', []);
$packs = collect($data)->map(function ($edge) {
    $node = $edge['node'];
    $latestVersion = collect($node['versions'] ?? [])->first();
    return [
        'id'         => $node['id'],
        'name'       => $node['name'],
        'summary'    => Str::limit($node['description'] ?? '', 200),
        'mc_version' => $latestVersion['minecraft'] ?? 'Unknown',
        'pack_version' => $latestVersion['version'] ?? '',
        'type'       => $node['type'],  // "public", "semi-public", "private"
        'provider'   => 'atlauncher',
    ];
})->filter(fn ($p) => $p['type'] === 'public');  // Only show public packs

// Server download URL pattern — requires exact pack name and version
$serverUrl = "https://servers.atlauncher.com/server/{$packName}/{$version}";
// Not all packs have server distribution rights — 404 if unavailable

ATLauncher-specific behaviours:

• GraphQL only — no REST API endpoints available
• Pack types: "public" (open), "semi-public" (needs code), "private" (restricted)
• Only "public" packs shown in default listing — filtered client-side
• Server downloads at servers.atlauncher.com — not all packs have server distribution
• GraphQL queries have higher overhead than REST — slower response times expected
• Version list includes MC version mapping per pack version
• No search endpoint — filtering is done client-side on the returned list
• description may contain HTML — stripped to plain text for display

ATLauncher Provider Error Map

VoidsWrath Provider — Complete Reference

VoidsWrath uses a static JSON file — no dynamic API, no search, no pagination.

API Endpoint — GET /minecraft-modpack-server-installer/voidswrath.json

Response Schema — Pack Array

Rate Limits

// Fetch entire VoidsWrath catalogue — one request, all packs
$response = Http::timeout($timeout)
    ->get('https://www.ric-rac.org/minecraft-modpack-server-installer/voidswrath.json');

$allPacks = $response->json();
// Returns: Full array of all packs — typically <20 entries

// Response processing — no filtering needed
$packs = collect($allPacks)->map(function ($pack) {
    return [
        'id'         => Str::slug($pack['name']),         // Generated slug
        'name'       => $pack['name'],
        'summary'    => $pack['description'] ?? '',
        'mc_version' => $pack['mcVersion'] ?? 'Unknown',
        'version'    => $pack['version'] ?? '',
        'icon_url'   => $pack['icon'] ?? null,
        'download'   => $pack['url'],                      // Direct ZIP URL
        'server_url' => $pack['serverUrl'] ?? null,        // Server-specific URL
        'provider'   => 'voidswrath',
    ];
});

VoidsWrath-specific behaviours:

• No search — all packs loaded at once from a single static JSON file
• No pagination — entire catalogue in one request (typically <20 packs)
• No API versioning — if the JSON structure changes, fetching may break
• Downloads point directly to ZIP files — no CDN or mirror system
• Pack updates require full re-download — no differential/incremental updates
• serverUrl may be null for packs without server distribution
• Static file hosted on ric-rac.org — availability depends on this single host
• Very small catalogue compared to other providers
• Cache TTL should be generous (24h+) since data changes rarely

VoidsWrath Provider Error Map

Cross-Provider Patterns (Modpacks)

// Modpack installation flow (all providers)
// 1. Download pack archive (ZIP/mrpack)
// 2. Switch to installer egg if needed
// 3. Extract to server directory
// 4. Merge configs (if updating)
// 5. Switch back to game egg
// 6. Clear Game Mods + Plugins data (cross-plugin cleanup)

// Backup before install — creates timestamped archive
$backupName = "backup_" . date('Y-m-d_H-i-s') . ".tar.gz";
// If backup fails, installation proceeds with warning notification

// Search retry logic — same as other plugins
$results = $this->search($query, $mcVersion, $loader);
if (empty($results) && $mcVersion) {
    $results = $this->search($query, null, $loader);
    // Retry without version filter — version may not be indexed yet
}

Complete Notification Reference

HTTP Error Code Reference (All Providers)

Provider-Specific Error Table

CurseForge (Modpacks) Errors

Modrinth (Modpacks) Errors

FTB Errors

Technic Errors

ATLauncher Errors

VoidsWrath Errors