Configuration

Eranio

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

Mod loader enum:

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