العربية Беларуская Български Čeština Dansk Deutsch Ελληνικά English Español Suomi Français עברית Magyar Bahasa Indonesia Italiano 日本語 한국어 Lietuvių Nederlands Norsk ☠ Pirate Polski Português (BR) Português (PT) Română Русский Slovenčina Српски Svenska Türkçe Українська 简体中文 繁體中文

Plugin Browser

Plugin Browser

Complete guide to the Plugin Browser — searching, browsing, filtering, plugin details, installation, dependency resolution, and provider-specific behavior.

Browser Interface

Tab Purpose
Browse Search and discover new plugins across all providers
Installed Manage installed plugins (see "Managing Plugins" guide)

The Installed tab shows an orange badge with the count of available updates. Clicking the tab auto-applies the has_updates filter.

Searching Plugins

How Search Works

  1. Enter a plugin name or keyword in the search bar
  2. Results load after debounce delay
  3. Searches only the currently selected provider
  4. Query sanitized: < > { } ' " removed
  5. Results displayed as plugin cards

Search Retry

If search with MC version filter returns zero results, the plugin automatically retries without the version filter — so you'll see results for all MC versions rather than an empty page.

Provider-Specific Search

Provider Empty Search With Query Notes
SpigotMC Sort by -downloads Full-text via Spiget Total from X-Total header
CurseForge Popularity (ID 2, desc) Featured (ID 1, desc) Dynamic sorting
Modrinth Popular with facets Full-text with facets Plugin-type facets
Hangar Browse all Full-text Owner/slug format for IDs
GeyserMC 6 hardcoded projects No search Fixed project list

GeyserMC: Always shows exactly 6 projects. The search bar has no effect. These are the officially maintained Geyser ecosystem plugins.

Filters

Filter Description Default
Minecraft Version Only compatible plugins Auto-detected version
Provider Platform tab switch SpigotMC

Version Filter Visibility

  • Shown for: SpigotMC, CurseForge, Modrinth
  • Hidden for: PaperMC/Hangar, GeyserMC (version-agnostic providers)

The auto-detected version is displayed with a "🟢 Detected" prefix.

Common Versions Dropdown

15 entries from 1.21 to 1.7 with special labels:

  • 1.21.x — "Latest"
  • 1.12.x — "Popular"
  • 1.8.x — "Legacy"

Plugin Cards

Element Description
Icon Plugin logo from provider CDN
Name Plugin title
Author Creator username
Summary Short description
Downloads Total download count
Updated Last version release date
🟢 Installed Green indicator if already installed

Plugin Detail View

Click a plugin card to see:

  • Full description — CurseForge: HTML enrichment. Modrinth: Markdown
  • Author and platform link
  • Total downloads
  • "View on [Provider]" button

Version Selection

Label Meaning
🟢 installed This version is installed
(Current) Latest version
(Popular) Most downloaded version
(Legacy) Older version

Versions cached 1 hour per plugin per provider.

Installing a Plugin

Step-by-Step Process

Step Detail
1. Validation Download URL verified
2. Old version check Existing installation searched by plugin_id
3. Download DaemonFileRepository::pull() to /plugins/
4. Filename detection 3 retries: 200ms → 300ms → 500ms. Checks for plugin_id in filenames → fallback to provided filename. UUID prefix cleaned
5. JAR metadata Opens JAR, reads plugin.yml → name field for display name. Fallback: filename with version regex stripping
6. Database Saves to MinecraftInstalledPlugin model
7. Old version cleanup If auto-replace on → deleteFiles() removes old version
8. Done Success: "Plugin installation started"

GeyserMC Special Download Flow

GeyserMC bypasses the normal download:

  1. cURL downloads JAR to temp file (custom User-Agent)
  2. Upload via DaemonFileRepository::putContent()
  3. No pull() used — entirely different flow

Dependency Resolution

CurseForge

  • relationType=3 = required dependency
  • Recursive: Dependencies of dependencies resolved too
  • Each dependency triggers a separate Filament notification
  • Dependencies installed before the main plugin

Modrinth

  • dependency_type === 'required' → auto-install
  • Specific version_id → exact version
  • No version_id → search latest compatible

SpigotMC

  • No dependency API — dependencies must be installed manually

PaperMC/Hangar

  • pluginDeps with required: true → auto-install
  • Only Paper platform dependencies

GeyserMC

  • No dependency API — Geyser is typically a dependency for Floodgate

Notification

"X additional library plugins will be installed that are required for this plugin"

Troubleshooting

No search results

  1. Check internet connection
  2. Verify provider API is online
  3. Clear Cache button
  4. For CurseForge: API key set?
  5. Try a different provider tab
  6. Auto-retry without version filter should trigger — if still empty, broaden search
  7. Check storage/logs/laravel.log

"Plugin download failed"

  • Expired URL: Clear cache, search again, retry
  • CDN unreachable: Provider CDN temporarily down
  • SpigotMC premium: HEAD check returned HTML → manual download required
  • GeyserMC: Check download.geysermc.org accessible
  • Disk full: No space on game server

"Installation failed"

  • /plugins/ directory not writable → check permissions
  • Disk space full
  • Filename detection failed after 3 retries → Log: "Failed to detect filename after download"
  • Database write error

"Plugin identification not found!"

  • Empty pluginId when trying to install/manage
  • Re-search the plugin for fresh metadata
  • Clear cache and retry

Plugin name shows filename instead of name

  • JAR metadata extraction failed (no plugin.yml in JAR or file too large)
  • Only cosmetic — plugin functions correctly

CurseForge shows "Manual download required"

  • Author restricted direct downloads
  • downloadUrl empty in API response
  • Download manually from CurseForge website and upload via SFTP

SpigotMC shows "Manual download required"

  • HEAD request returned text/html instead of JAR
  • Plugin is premium or download-restricted
  • Purchase/download from SpigotMC and upload via SFTP
Configuration Managing Plugins