Mod Browser
Mod Browser
Complete guide to the Mod Browser — searching, browsing, filtering, mod details, installation, dependency resolution, and provider-specific behaviour.
Browser Interface
| Tab |
Purpose |
| Browse |
Search and discover new mods from all platforms |
| Installed |
View and manage installed mods (see "Managing Mods" guide) |
Searching for Mods
How Search Works
- Type a mod name or keyword in the search bar
- Results load after a 300ms debounce (prevents excessive API calls while typing)
- Searches the currently selected platform only
- Queries are sanitised:
< > { } ' " characters are stripped
- Results displayed as a grid of mod cards
Search Tips
| Tip |
Example |
| Search by exact mod name |
Sodium, Create, JEI |
| Search by keyword |
optimisation, minimap, storage |
| Use short names |
ic2 instead of IndustrialCraft 2 |
| Different platforms have different content |
Try multiple tabs |
| Empty search |
Shows popular/featured mods (sort depends on platform) |
Platform-Specific Search Behaviour
| Platform |
Empty Search Behaviour |
With Query |
Sort Default |
| Modrinth |
Popular mods with facets |
Full text search with facets |
Relevance |
| CurseForge |
Sort by Popularity (ID 2, descending) |
Sort by Featured (ID 1, descending) |
See Configuration guide |
| Modtale |
Browse all by game |
Full text search |
Default order |
Filters
| Filter |
Description |
Default |
| Minecraft Version |
Only show compatible mods |
Auto-detected version ("🟢 Detected: X.X.X") |
| Mod Loader |
Forge, Fabric, NeoForge, Quilt |
All loaders |
| Provider |
Switch platform tabs |
Modrinth |
Version Dropdown Contents
- Auto-detected version (if available) — "🟢 Detected: 1.21.4" prefix
- Common versions: 1.21 (Latest), 1.20, 1.19, 1.18, 1.17, 1.16, 1.15, 1.14, 1.13, 1.12 (Popular), 1.11, 1.10, 1.9, 1.8 (Legacy), 1.7
Mod Loader by Platform
| Loader |
Modrinth |
CurseForge (Enum ID) |
Modtale |
| Forge |
✓ |
1 |
Game-based |
| Fabric |
✓ |
4 |
Game-based |
| NeoForge |
✓ |
6 |
Game-based |
| Quilt |
✓ |
5 |
Game-based |
Mod Cards
Each result shows:
| Element |
Description |
| Icon |
Mod logo from platform CDN |
| Name |
Mod title |
| Author |
Creator's username |
| Summary |
Short description |
| Downloads |
Total across all versions |
| Updated |
Last version's publish date |
| 🟢 Installed |
Green indicator if already installed |
Mod Detail View
Click any mod card to open the detail panel:
- Full description — CurseForge: HTML via enrichment endpoint
/mods/{modId}/description. Modrinth: Markdown
- Author and link to platform page (CurseForge uses
getModSlug() for URL)
- Total downloads
- "View on [Platform]" button
Version Selection
| Label |
Meaning |
| 🟢 installed prefix |
This version is installed on your server |
| (Latest) |
Newest published version |
| (Popular) |
Most downloaded version (if different from Latest) |
| (Legacy) |
Older version |
Versions cached 1 hour per mod per provider.
Installing a Mod
What Happens Step by Step
| Step |
Detail |
| 1. Pre-check |
Validates download URL exists |
| 2. Old version check |
Looks for existing installation by mod ID in database |
| 3. Download |
DaemonFileRepository::pull() to /mods/ directory |
| 4. cURL fallback |
If pull() fails → cURL download with 60s timeout. Logged: "Error downloading mod" |
| 5. Filename detection |
3 retries: 200ms → 300ms → 500ms. Checks for mod ID in filenames. UUID prefixes (server's uuid_short) cleaned |
| 6. JAR metadata |
Opens JAR (≤30 MB, 256 MB memory limit). Reads plugin.yml, fabric.mod.json, META-INF/mods.toml. On fail: "Failed to extract mod name from JAR" |
| 7. Database save |
Records: provider, mod_id, mod_slug, mod_url, version_id, version_number, version_name, filename, download_url, installed_at |
| 8. Old version cleanup |
If auto-replace enabled → deleteFiles() removes old version |
| 9. Done |
Success: "Mod installation started". Logged: "Successfully installed mod" |
Failure Notification
- Title: "Mod installation failed"
- Body: "Installation failed" with error details
- Full error logged to
storage/logs/laravel.log
Automatic Dependency Resolution
Modrinth Dependencies
dependency_type === 'required' triggers auto-install- Specific
version_id → exact version fetched
- No version_id → latest compatible version searched
- Each dependency goes through full installation flow
CurseForge Dependencies
relationType=3 (required) triggers auto-install- Recursive: Dependencies of dependencies also resolved
- Each resolved by CurseForge mod ID
Modtale Dependencies
- Not available — Modtale API doesn't provide dependency data
- You must install dependencies manually
Dependency Notification
"Installing X additional library mods required for this mod to function"
Troubleshooting
No Search Results
- Check internet:
curl -I https://api.modrinth.com
- Check platform status (visit website directly)
- Click Clear Cache
- Broaden search terms
- Check version filter — wrong version hides results
- Try a different platform tab
- Check
storage/logs/laravel.log
- CurseForge: verify API key is set
"Mod download failed"
- Expired URL: Clear cache, re-search, retry
- CDN down: Platform CDN temporarily unavailable → wait and retry
- cURL fallback triggered: If primary
pull() fails, 60s cURL download tried. Log: "Error downloading mod"
- Disk full: No space on game server
- Large file timeout: Increase request timeout in settings
"Installation failed"
/mods/ directory not writable → check permissions- Disk space full
- Filename detection failed after 3 retries → log: "Failed to detect filename after download"
- Database write error
"Mod identification not found!"
- Empty
pluginId when attempting install/manage
- Re-search the mod for fresh metadata
- Clear cache and retry
Mod Name Shows Filename Instead of Name
- JAR metadata extraction failed (file >30 MB, or no
plugin.yml/fabric.mod.json/META-INF/mods.toml)
- Log: "Failed to extract mod name from JAR"
- Cosmetic only — mod works correctly
CurseForge Returns "Manual Download Required"
- Author restricted direct downloads
downloadUrl is empty in API response- Plugin shows link to CurseForge page
- Download manually and upload via SFTP/file manager
Search Results Differ Between Platforms
- Each platform has its own index and search algorithm
- CurseForge sort changes with/without query (Popularity vs. Featured)
- Modrinth uses facet-based filtering (server_side required/optional only)
- Modtale uses 0-based pagination
Version Detection Retry
- Click Detect Version button to retry
- Detection uses 11 methods in sequence
- Result cached 5 minutes — wait 5 min before retrying or clear cache