Configuration
Configuration
Complete reference for all settings, environment variables, caching behaviour, and detailed per-provider setup with error documentation.
Admin Panel Settings
Open settings via the gear icon on the Mod Browser page. Changes save immediately.
Settings Reference
| Setting |
Default |
Range |
Env Variable |
Description |
| Cache Duration |
30 min |
0–1440 min |
MODS_CACHE_DURATION (seconds, default 1800) |
How long API responses are cached |
| Request Timeout |
10 sec |
1–30 sec |
MODS_REQUEST_TIMEOUT |
Max wait for platform API response |
| Mods Per Page |
20 |
5–100 |
MODS_PER_PAGE |
Results per browse page |
| Auto-Replace |
On |
Toggle |
MODS_AUTO_REPLACE_VERSIONS |
Remove old versions on update |
| CurseForge API Key |
— |
Text |
CURSEFORGE_API_KEY |
Required for CurseForge (password field, reveal button) |
| Modtale API Key |
— |
Text |
MODTALE_API_KEY |
Optional for Modtale (password field, reveal button) |
Detailed Cache TTLs
| What Is Cached |
Cache Key Pattern |
TTL |
| Browse/search results |
browse_mods__{uuid}__{provider}__{gameVersion}__{loader}__{hash}__{page} |
15 minutes |
| Installed mods list |
mods_server_{uuid} |
10 minutes |
| Version lists per mod |
mod_versions_cache_{uuid}_{provider}_{modId} |
1 hour |
| Update metadata |
mod_update__{uuid}__{modId} |
24 hours |
| Detected MC version |
minecraft_version_{uuid} |
5 minutes |
| Enriched installed data |
game_mods_data__{uuid} |
24 hours |
| Server mod filenames |
server_{uuid}_mod_filenames |
1 hour |
| Console widget updates |
mod_updates_{uuid} |
Widget-specific |
The cache uses a file-based system with prefix GM_. SafeCacheService auto-creates directories with 0755 permissions. Flushing iterates all tracked keys.
All Environment Variables
| Variable |
Default |
Description |
MODS_CACHE_DURATION |
1800 |
Cache duration in seconds |
MODS_REQUEST_TIMEOUT |
10 |
API timeout in seconds |
MODS_PER_PAGE |
20 |
Mods per browse page |
MODS_AUTO_REPLACE_VERSIONS |
true |
Auto-remove old versions |
CURSEFORGE_API_KEY |
— |
CurseForge API key (shared with Modpacks + Plugins) |
MODTALE_API_KEY |
— |
Modtale API key (optional) |
After changes: php artisan config:clear
Provider: Modrinth (Detailed)
Overview
No configuration required. Recommended platform for best experience.
Technical Specifications
| Property |
Value |
| API Base |
https://api.modrinth.com/v2 |
| Authentication |
None |
| Search Method |
POST /search with facets JSON |
| Auto-Facets |
[["project_type:mod"], ["server_side:required","server_side:optional"]] |
| Download Method |
Direct CDN URL from files[0].url |
| Integrity |
SHA-1 hash available for verification |
| Rate Limits |
Fair use (no published hard limit) |
Search Capabilities
- Full text search across names, slugs, descriptions
- Minecraft version filter: Passed as facet
- Mod loader filter: Passed as facet. Values
'all' and 'any' are automatically excluded
- Results include: icon URL, name, author, description, downloads, date created, slug
Dependency Resolution
- Dependencies with
dependency_type === 'required' are detected
- If a specific
version_id is in the dependency data → that exact version is fetched
- If no version_id → plugin searches for the latest compatible version
- Dependencies installed before or alongside the main mod
Modrinth-Specific Errors
| Error / Symptom |
Cause |
Solution |
| No search results |
API temporarily unavailable |
Check status.modrinth.com, retry later |
| Download failed |
CDN URL expired or unreachable |
Clear cache, re-search, retry |
| Empty version list |
No server-side versions for your MC version + loader |
Try different version/loader filter |
| Slow responses |
API under load |
Increase timeout to 20-30s |
| Facet error |
Invalid loader or version value sent |
Clear cache, check version format |
Provider: CurseForge (Detailed)
Overview
Requires free API key. Largest mod library. Get key at console.curseforge.com.
Getting Your API Key
- Visit console.curseforge.com
- Create account (free) or sign in
- Go to "API Keys" → create new key
- Copy key → paste in plugin settings CurseForge API Key field
- Click Save
This key is shared across Game Mods, Modpacks, and Plugins via CURSEFORGE_API_KEY.
Technical Specifications
| Property |
Value |
| API Base |
https://api.curseforge.com/v1 |
| Authentication |
x-api-key header |
| Game IDs |
Minecraft = 432, Hytale = 70216 |
| Class ID |
9137 (Mods) |
| Max Page Size |
50 items per request |
| Total Results Cap |
10,000 maximum |
| Description Enrichment |
Separate /mods/{modId}/description call (HTML) |
| Slug Helper |
/mods/{modId} fetch for URL generation |
Search Capabilities
- Full text search
- Sort options (12 available):
| Sort Field |
ID |
Default Sort Order |
| Featured |
1 |
Descending (used when query present) |
| Popularity |
2 |
Descending (used when no query) |
| LastUpdated |
3 |
Descending |
| Name |
4 |
Ascending (only one that's ascending) |
| Author |
5 |
Descending |
| TotalDownloads |
6 |
Descending |
| Category |
7 |
Descending |
| GameVersion |
8 |
Descending |
| EarlyAccess |
9 |
Descending |
| FeaturedReleased |
10 |
Descending |
| ReleasedDate |
11 |
Descending |
| Rating |
12 |
Descending |
| Loader |
CurseForge ID |
| Forge |
1 |
| Cauldron |
2 |
| LiteLoader |
3 |
| Fabric |
4 |
| Quilt |
5 |
| NeoForge |
6 |
- Version extraction: From
gameVersions array, filtered by \d+\.\d+ regex
Dependency Resolution
relationType=3 = required dependency- Resolution is recursive (dependencies of dependencies are resolved too)
- Each dependency resolved by CurseForge mod ID
Special: Manual Download Required
Some mod authors restrict direct downloads. When downloadUrl is empty:
- Mod flagged as
requires_manual_download: true
- Plugin shows link to CurseForge page for manual download
- This is a CurseForge policy, not a plugin limitation
CurseForge-Specific Errors
| Error / Symptom |
Cause |
Solution |
| "CurseForge API key not set" |
No key configured |
Enter key in settings or set CURSEFORGE_API_KEY env var |
| HTTP 403 Forbidden |
Key invalid or lacks permissions |
Re-generate key at console.curseforge.com |
| HTTP 429 Too Many Requests |
Rate limit exceeded |
Increase cache duration, wait, reduce frequency |
| Empty download URL |
Author restricted downloads |
Download manually from CurseForge website |
| "CurseForge request failed" |
Network/API error |
Check connectivity to api.curseforge.com, increase timeout |
| Description not loading |
Enrichment API call failed |
Non-critical, mod still works |
| Slow responses |
CurseForge under heavy load |
Increase timeout to 20-30s |
| Wrong game results |
Game ID mismatch |
Verify egg tags match expected game |
Provider: Modtale (Detailed)
Overview
API key optional but provides extended rate limits.
Getting API Key (Optional)
- Visit modtale.net/dashboard/developer
- Register developer account
- Generate API key
- Enter in plugin settings Modtale API Key field
Technical Specifications
| Property |
Value |
| API Base |
https://api.modtale.net/api/v1 |
| CDN |
https://cdn.modtale.net/ |
| Authentication |
Optional X-MODTALE-KEY header |
| Pagination |
0-based (page 0 = first page, unlike Modrinth/CurseForge which use 1) |
| Icons |
cdn.modtale.net/{thumbnail_path} |
| Downloads |
cdn.modtale.net/{file_download_path} |
Modtale-Specific Errors
| Error / Symptom |
Cause |
Solution |
| Slow results |
Modtale API slower than others |
Increase timeout |
| Rate limited |
Too many requests without key |
Add Modtale API key |
| CDN download failed |
cdn.modtale.net unreachable |
Check firewall, retry |
| No dependencies shown |
Modtale API doesn't provide dependency info |
Install dependencies manually |
Search Query Sanitisation
All platforms: characters < > { } ' " are automatically stripped from search queries.
Troubleshooting
Settings Not Saving
- Check
storage/ is writable
php artisan config:clear- Check browser console (F12) for JS errors
Cache Not Clearing
- SafeCacheService
flush() iterates all tracked keys
- If
storage/framework/cache/ is missing or unwritable, cache operations fail
- Error notification shows
$e->getMessage() from the caught exception
- Log: "Error clearing cache and scanning mods"
API Responses Returning Old Data
- Each cache type has its own TTL (see table above)
- Update metadata is cached 24 hours — click Clear Cache for immediate refresh
- Browse results cached 15 minutes, installed list 10 minutes