Mods verwalten

Mods verwalten

Vollständige Anleitung zum Installiert-Tab — Anzeigen, Filtern, Aktualisieren, Aktivieren/Deaktivieren, Deinstallieren, Upload-Erkennung, ZIP-Export und alle möglichen Fehler.

Liste installierter Mods

Zwei Quellen:

1. Browser-installiert — Vollständiges Tracking (Anbieter, Version, Mod-ID, Download-URL, Update-Erkennung)
2. Manuell hochgeladen — Auto-erkannt durch Scanner, als „Manuell / Upload" mit eingeschränktem Tracking

Spalten

Upload-Erkennung

scanAndRegisterUploadedMods() läuft automatisch:

• Vergleicht Dateien auf der Festplatte (/mods/) mit Datenbankeinträgen
• Neue Dateien: Registriert mit Anbieter 'upload'. JAR wird geöffnet für Namensextraktion
• Gelöschte Dateien: Aus Datenbank entfernt (Bereinigung)
• Gleichzeitigkeitsschutz: Atomarer Lock mit 10-Sekunden-TTL
• Einschränkungen: Upload-Mods haben keine Auto-Update-Erkennung

Filtern

Mods mit Updates werden oben angezeigt, dann alphabetisch.

Mods aktualisieren

Wie Updates erkannt werden

• Plugin fragt Quellplattform per gespeicherter mod_id und provider ab
• Update-Metadaten 24 Stunden gecacht pro Mod
• 'upload'-Anbieter werden immer übersprungen
• Versionsvergleich nutzt Stringvergleich (nicht semantische Versionierung)

Bei gefundenem Update

1. „Update verfügbar"-Badge im Installiert-Tab
2. Konsolen-Widget: „Mod-Updates verfügbar — Jetzt aktualisieren"
3. Spalte „Neueste Version" zeigt neue Versionsnummer

Update durchführen

1. Update neben dem Mod klicken
2. Neue Version von Plattform heruntergeladen
3. Alte Version automatisch entfernt (falls aktiviert)
4. Benachrichtigung: „Mod-Installation gestartet"
5. Server neustarten um Update zu laden

Konsolen-Widget

• Synchronisiert Plugins beim Laden
• Update-Check mit 15-Minuten-Cache
• Warnung-Badge mit Weiterleitung zum Mod Browser

Mods aktivieren / deaktivieren

Mechanismus im Detail

Dateiumbennung mit -bak-Suffix via Lesen+Schreiben+Löschen (für Daemon-API-Kompatibilität):

Hinweis: Drei Daemon-API-Aufrufe pro Umschaltvorgang. Server muss ggf. gestoppt werden.

Benachrichtigungen

Anwendungsfälle

• Absturz-Diagnose: Mods einzeln deaktivieren um Absturzursache zu finden
• Leistungstests: Messen mit/ohne bestimmte Mods
• Konflikt-Erkennung: Verdächtigen Mod deaktivieren
• Vorbereitung: Mods deaktiviert installieren, alle während Wartung aktivieren

Mods deinstallieren

Vorgang

1. Deinstallieren klicken → Warnung bestätigen
2. JAR-Datei aus /mods/ gelöscht
3. Datenbankeintrag entfernt
4. Benachrichtigung: „Mod deinstalliert"
5. Server neustarten um Mod vollständig zu entladen

Was NICHT entfernt wird

Mods-Ordner öffnen

Springt zu /mods/ im Dateimanager. Nützlich für:

• Tatsächliche Dateien auf der Festplatte prüfen
• Manuelle Uploads
• Konfigurations-Verzeichnisse nach Deinstallation bereinigen
• -bak-Erweiterungen deaktivierter Mods prüfen

ZIP-Export

Vorgang

1. Alle als ZIP herunterladen klicken
2. Benachrichtigung: „ZIP-Download gestartet"
3. Server komprimiert alle Dateien in /mods/
4. JWT-signierte URL generiert (läuft nach 30 Minuten ab)
5. Download startet automatisch

Enthält: Alle Mods (aktiv + deaktiviert)

Bei Fehler

• Benachrichtigung: „ZIP-Download fehlgeschlagen"
• Temporären Speicherplatz prüfen
• Große Sammlungen (100+ Mods) können Timeout verursachen

Vollständige Fehlerreferenz

„Installierte Mods konnten nicht gelesen werden"

• /mods/-Verzeichnis existiert nicht → Server einmal starten
• Verzeichnis nicht lesbar → Daemon-Berechtigungen prüfen
• Festplatte voll
• Daemon-Verbindung unterbrochen

„Mod konnte nicht deaktiviert/aktiviert werden"

• Berechtigungen: Lesen + Schreiben + Löschen auf /mods/ erforderlich
• Datei gesperrt: Laufender Server sperrt Dateien → Server zuerst stoppen
• Gleichzeitiger Zugriff: Backup/Dateimanager greift gleichzeitig zu
• Datei nicht gefunden: Extern umbenannt oder gelöscht
• Daemon-Fehler: Jeder der 3 Schritte (Lesen/Schreiben/Löschen) kann fehlschlagen

„Alte Versionen konnten nicht gelöscht werden"

• Alte Datei vom laufenden Server gesperrt → Server stoppen
• Dateiberechtigungsproblem
• Datei bereits manuell entfernt
• storage/logs/laravel.log prüfen

Updates werden nicht angezeigt

• Update-Metadaten 24 Stunden gecacht → Cache leeren
• 'upload'-Mods werden immer übersprungen
• Versionsvergleich ist stringbasiert
• Plattform hat Update evtl. noch nicht propagiert

„Deinstallation fehlgeschlagen"

• Datei bereits manuell gelöscht
• Datei vom Serverprozess gesperrt → stoppen und erneut versuchen
• Daemon-Verbindungsproblem

Mod lässt Server nach Installation abstürzen

1. Konsolenausgabe / Absturzbericht prüfen — nennt den problematischen Mod
2. Mod deaktivieren (nicht löschen!) + neustarten zur Bestätigung
3. Abhängigkeiten installiert?
4. Mod-Loader-Kompatibilität prüfen (Fabric auf Forge = Absturz)
5. Ältere stabile Version versuchen
6. Java-Version prüfen (17 für MC 1.18+, 21 für MC 1.21+)
7. Issue-Tracker des Mods auf der Plattform prüfen

„Cache leeren fehlgeschlagen"

• Fehler in Benachrichtigung zeigt $e->getMessage()
• SafeCacheService flush() konnte Schlüssel nicht entfernen
• storage/framework/cache/ muss existieren und beschreibbar sein (0755)
• Log: „Error clearing cache and scanning mods"

Interne Provider-Funktionen (Referenz)

Dieser Abschnitt dokumentiert den internen PHP-Code jeder Provider-Integration. Das Verständnis dieser Muster hilft bei der Fehlerdiagnose und erklärt, wie Mods gesucht, aufgelöst und installiert werden.

CurseForge Provider — Vollständige Referenz

API-Endpunkt-Parameter — GET /v1/mods/search

Antwort-Schema — Suchergebnisse

Rate-Limits

// Such-Anfrage — der vollständige interne Ablauf
$response = Http::withHeaders(['x-api-key' => $apiKey])
    ->timeout($timeout)
    ->get('https://api.curseforge.com/v1/mods/search', [
        'gameId'        => $gameId,    // 432 für Minecraft, 70216 für Hytale
        'classId'       => 9137,       // Mods-Klasse (NICHT 5=Plugins, NICHT 4471=Modpacks!)
        'searchFilter'  => $query,
        'sortField'     => $query ? 1 : 2,  // Featured beim Suchen, Popularität beim Browsen
        'sortOrder'     => 'desc',
        'modLoaderType' => $loaderEnum,
        'gameVersion'   => $mcVersion,
        'pageSize'      => $perPage,
        'index'         => ($page - 1) * $perPage,
    ]);

// Antwort-Verarbeitung — wie Ergebnisse für die Oberfläche aufbereitet werden
$results = $response->json('data', []);
$mods = collect($results)->map(function ($mod) {
    // Unterstützte MC-Versionen aus gameVersions per Regex extrahieren
    $versions = collect($mod['latestFilesIndexes'] ?? [])
        ->pluck('gameVersion')
        ->filter(fn ($v) => preg_match('/^\d+\.\d+/', $v))
        ->unique()->sort()->values();

    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,
        'updated_at'    => $mod['dateModified'],
        'versions'      => $versions->toArray(),
        'provider'      => 'curseforge',
    ];
});

// Abhängigkeitsauflösung — rekursiv mit relationType-Prüfung
foreach ($file['dependencies'] as $dep) {
    if ($dep['relationType'] === 3) {  // 3 = Pflicht-Abhängigkeit
        $depMod = $this->fetchMod($dep['modId']);
        $this->installMod($depMod);  // Rekursiv — löst Sub-Abhängigkeiten auf
    }
    // relationType 1 = EmbeddedLibrary (übersprungen)
    // relationType 2 = OptionalDependency (übersprungen)
    // relationType 4 = Tool (übersprungen)
    // relationType 5 = Incompatible (übersprungen)
    // relationType 6 = Include (übersprungen)
}

// Manueller-Download-Erkennung — CurseForge-Autoreneinschränkung
if (empty($file['downloadUrl'])) {
    $mod['requires_manual_download'] = true;
    // Nutzer sieht „Auf CurseForge herunterladen"-Link statt Installations-Button
    // Das ist eine CurseForge-Autorenrichtlinie, kein Plugin-Bug
}

CurseForge Provider Fehler-Zuordnung

Modrinth Provider — Vollständige Referenz

API-Endpunkt-Parameter — GET /v2/search

Facetten-Struktur

Facetten sind ein JSON-Array aus Arrays. Innere Arrays werden ODER-verknüpft, äußere Arrays werden UND-verknüpft:

// Wie das Plugin Facetten intern aufbaut
$facets = [
    ['project_type:mod'],                  // MUSS ein Mod sein
    ['server_side:required', 'server_side:optional'],  // Server-kompatibel
];

// Optionale Facetten werden bedingt hinzugefügt:
if ($mcVersion) {
    $facets[] = ["versions:$mcVersion"];   // Muss diese MC-Version unterstützen
}
if ($loader && !in_array($loader, ['all', 'any'])) {
    $facets[] = ["categories:$loader"];    // Muss diesen Loader unterstützen
}

// ⚠ 'all' und 'any' werden ausgeschlossen — Modrinth akzeptiert diese nicht als Facetten
$params['facets'] = json_encode($facets);

Antwort-Schema — Suchergebnisse

Rate-Limits

// Antwort-Verarbeitung — wie Modrinth-Ergebnisse zugeordnet werden
$hits = $response->json('hits', []);
$mods = 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,
        'updated_at'    => $hit['date_modified'],
        'versions'      => $hit['versions'] ?? [],
        'provider'      => 'modrinth',
    ];
});

// Versions-Abruf — mit Loader- und Versionsfilterung
$versions = Http::get("https://api.modrinth.com/v2/project/{$projectId}/version", [
    'loaders'       => json_encode([$loader]),      // z.B. ["fabric"]
    'game_versions' => json_encode([$mcVersion]),   // z.B. ["1.20.1"]
])->json();

// Jede Version enthält:
// - id, version_number, name, date_published
// - files[0].url = direkter CDN-Download-Link
// - files[0].hashes.sha1 = Integritäts-Hash
// - dependencies[] = Pflicht-/Optionale Abhängigkeiten

// Abhängigkeitsauflösung — mit zwei Strategien
foreach ($version['dependencies'] as $dep) {
    if ($dep['dependency_type'] === 'required') {
        if (!empty($dep['version_id'])) {
            // Strategie 1: Exakte Version angegeben
            $depVersion = Http::get("https://api.modrinth.com/v2/version/{$dep['version_id']}")->json();
        } else {
            // Strategie 2: Neueste kompatible Version für das Projekt suchen
            $depVersions = Http::get("https://api.modrinth.com/v2/project/{$dep['project_id']}/version", [
                'loaders'       => json_encode([$loader]),
                'game_versions' => json_encode([$mcVersion]),
            ])->json();
            $depVersion = $depVersions[0] ?? null;  // Neueste kompatible
        }
        if ($depVersion) {
            $this->installVersion($depVersion);
        }
    }
    // 'optional' und 'incompatible' Typen werden ignoriert
}

Modrinth Provider Fehler-Zuordnung

Modtale Provider — Vollständige Referenz

API-Endpunkt-Parameter — GET /api/v1/mods

⚠ Wichtiger Unterschied: Modtale verwendet 0-basierte Paginierung. Seite 0 = erste Seite. Das Plugin konvertiert von seinem internen 1-basierten System: max(0, $page - 1).

Antwort-Schema

Rate-Limits

// Kompletter Anfrage + Antwort-Verarbeitungsablauf
$response = Http::timeout($timeout)
    ->when($apiKey, fn ($http) => $http->withHeaders(['X-MODTALE-KEY' => $apiKey]))
    ->get('https://api.modtale.net/api/v1/mods', [
        'page' => max(0, $page - 1),  // 1-basiert → 0-basiert konvertieren!
        'game' => $gameName,
    ]);

$results = $response->json('data', []);
$mods = collect($results)->map(function ($mod) {
    return [
        'id'            => $mod['id'],
        'name'          => $mod['name'],
        'summary'       => $mod['description'] ?? '',
        'author'        => $mod['author'] ?? 'Unknown',
        'downloads'     => $mod['download_count'] ?? 0,
        'icon_url'      => 'https://cdn.modtale.net/' . ($mod['thumbnail'] ?? ''),
        'updated_at'    => $mod['updated_at'],
        'provider'      => 'modtale',
    ];
});

// CDN-URL-Konstruktion — alle Assets nutzen das CDN-Präfix
$iconUrl     = 'https://cdn.modtale.net/' . $mod['thumbnail'];
$downloadUrl = 'https://cdn.modtale.net/' . $file['download_path'];

// ⚠ Keine Abhängigkeitsinformationen — Modtale API liefert keine Abhängigkeitsdaten
// Nutzer müssen Abhängigkeiten für Modtale-Mods manuell installieren

Modtale Provider Fehler-Zuordnung

Übergreifende Provider-Muster

Diese Code-Muster gelten für alle Provider:

// Suchabfrage-Bereinigung — schützt gegen Injection bei allen Providern
$query = preg_replace('/[<>{}\'"]+/', '', $query);
// Zeichen < > { } ' " werden vor jedem API-Aufruf entfernt

// Dateinamenerkennung nach Download — 3 Versuche mit Backoff
for ($attempt = 0; $attempt < 3; $attempt++) {
    usleep([200000, 300000, 500000][$attempt]);  // 200ms → 300ms → 500ms
    $files = $this->fileRepository->getDirectory('/mods/');
    $newFile = $this->findNewFile($files, $knownFiles);
    if ($newFile) break;
}
// Wenn nach 3 Versuchen keine neue Datei erkannt → Warnung geloggt

// UUID-Präfix-Bereinigung — Server fügt uuid_short zu Dateinamen hinzu
$cleanName = preg_replace('/^[a-f0-9]{8}_/', '', $filename);
// z.B. "a1b2c3d4_fabric-api-0.92.jar" → "fabric-api-0.92.jar"

// JAR-Metadaten-Extraktion — liest Mod-Name aus Archiv
$zip = new ZipArchive();
ini_set('memory_limit', '256M');  // JAR-Dateien können groß sein
// Prüft in Reihenfolge: plugin.yml → fabric.mod.json → META-INF/mods.toml
// Maximale Dateigröße: 30MB für Metadaten-Scan

// Gleichzeitiger Scan-Schutz — atomare Sperre verhindert doppelte Scans
$lock = Cache::lock('mod_scan_' . $serverUuid, 10);  // 10 Sekunden TTL
if (!$lock->get()) {
    return;  // Ein anderer Scan läuft bereits
}

Vollständige Benachrichtigungs-Referenz

HTTP-Fehlercode-Referenz