Mod Browser
Eranio
Mod Browser
Complete guide to the Mod Browser, searching, browsing, filtering, mod details, installation, dependency resolution, and provider-specific behaviour.
On phones
On small screens the tabs and the action buttons move out of the header into one of two layouts:
- Bar at the bottom: "Browse", "Installed", the actions (ZIP, Folder, Cache and Version when shown) and "Dropdown" to switch the layout. Up to five fields fit. If there are more, the last ones move into "More".
- Dropdown: a field below the title shows the current tab. Tapping it lists both tabs, the actions and the switch back to the bar.
The actions behave exactly like the buttons on a computer, including confirmation dialogs. The update count of "Installed" is shown as a small badge, and tapping it opens the list filtered to mods with an update. The layout choice is saved in the browser and shared with Hytale Admin and the other plugin.
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: 26.3" prefix
- Common versions: loaded live from Mojang's version list, currently 26.3 (Latest), 26.2, 26.1, 1.21, 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
pluginIdwhen 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
downloadUrlis 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