Color theme
العربية Беларуская Български Č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 Українська 简体中文 繁體中文

Installation & Setup

Eranio

Installation & Setup

Complete step-by-step guide to installing the Game Mods Installer plugin and activating it for your game servers.

Prerequisites

  • Pelican Panel version 1.0.0-rc.1+ installed and running
  • PHP 8.5 on the panel server
  • Writable directories: storage/ and bootstrap/cache/, permissions 0755, owned by web server user (e.g., www-data)
  • A game server managed by the panel
  • Database user with CREATE TABLE permission (the plugin creates a migration on first load)

Step 1: Install the Plugin

  1. Download the latest release of the game-mods plugin
  2. Place it in your Pelican Panel's plugins/ directory: 
    /var/www/pelican/plugins/game-mods/
  3. Verify the directory structure: 
    plugins/game-mods/
├── src/
├── config/
├── resources/
├── database/
└── plugin.json
  4. Clear the application cache: 
    php artisan cache:clear
php artisan config:clear
php artisan view:clear
  5. Verify the plugin appears in Admin Panel → Plugins as "Game Mods Installer"

The plugin automatically creates the server_installed_mods database table on first load.

Step 2: Activate for a Server

The plugin uses Feature Flags on Eggs to determine which servers show the Mod Browser.

  1. Go to Admin Panel → Eggs
  2. Edit the Egg used by your game server (e.g., "Minecraft Java", "Hytale Server")
  3. Add mods to the Features field: 
    ["mods"]
    If the Egg already has features: 
    ["steam_disk_space", "mods"]
  4. Click Save

Important: The feature flag must be exactly mods (lowercase). Mods, MODS, or mod will not work.

Step 3: Game Detection

The plugin auto-detects your game by checking (in order):

  1. Egg Tags, keywords like minecraft, hytale, bedrock
  2. Egg Name, scans the egg name
  3. Nest Name, checks the parent nest name

For Hytale servers with PATCHLINE="release": alpha, beta, RC, and dev versions are automatically filtered out.

Minecraft Version Detection (11 Methods)

For Minecraft servers, the version is detected using 11 methods in priority order:

Priority Method What It Checks
1 variables.txt Panel-stored server variables
2 server.properties Version-related properties
3 version.json Mojang's version manifest
4 Fabric JAR Fabric server JAR filename
5 Forge JAR Forge server JAR filename
6 Forge libraries Library directory structure
7 Recursive search Scans 7 directories (depth 1-6), skips node_modules, cache, temp, logs, crash-reports, world dirs, mods, plugins. Max path: 250 chars
8 server.jar Generic server JAR analysis
9 Paper JAR PaperMC filename
10 Spigot JAR Spigot filename
11 Purpur JAR Purpur filename

Validation: Legacy scheme 1.x (minor 0-50) or Mojang's year scheme since 2026 (26.1, 26.2, 26.3, year at most next year). Normalised to major.minor. Cached 5 minutes.

Searching by version: The selected version covers the whole version family. 26.1 also finds entries marked only for 26.1.1 or 26.1.2, 1.21 finds 1.21.1 to 1.21.11. The patch versions come live from Mojang's version list (cached 12 hours), new versions such as 26.3.1 or 27.1 are detected without a plugin update.

Step 4: First Launch

  1. Navigate to your server → click Mod Browser in sidebar
  2. The plugin scans to detect game and version (atomic lock, 10s TTL to prevent concurrent scans)
  3. If Minecraft detected: success notification "Minecraft version detected: 26.3"
  4. Platform tabs appear: Modrinth, CurseForge, Modtale
  5. Existing mods in /mods/ are auto-registered as "Manual / Upload"
  6. Ready to search and install!

If detection fails: "Could not detect Minecraft version". Use the manual dropdown. Common versions listed: 26.3 (Latest), 26.2, 26.1, 1.21 through 1.7, with 1.12 (Popular) and 1.8 (Legacy) labels.

Verification Checklist

Check Expected If Not Working
Plugin in Admin → Plugins "Game Mods Installer" listed Wrong path or cache not cleared
"Mod Browser" in sidebar Visible for mods-flagged servers Missing feature flag
Platform tabs Modrinth, CurseForge, Modtale Network or JS error
Version detection "Detected: X.X.X" Server never started or no JAR
server_installed_mods table Exists in DB Run php artisan migrate

Troubleshooting

Plugin Not Visible in Admin Panel

  • Ensure path is exactly plugins/game-mods/ (not plugins/GameMods/)
  • Run php artisan cache:clear and reload
  • Check that plugin.json exists in the plugin root
  • Check storage/logs/laravel.log for "Class not found" errors
  • Verify file permissions allow the web server to read the directory

"Mod Browser" Not in Server Sidebar

  • The Egg must have "mods" in Features, lowercase, exact
  • Save the Egg after editing
  • Clear config cache: php artisan config:clear
  • The plugin calls abort(403) if the feature is missing

"Could Not Detect Minecraft Version"

  • Start the server at least once to generate JAR + version.json
  • Rename custom JARs to recognisable names (server.jar, paper-26.3.jar)
  • JAR paths >250 chars are skipped
  • Use manual dropdown as workaround

Database Migration Error

  • Grant CREATE TABLE: GRANT CREATE ON your_database.* TO 'user'@'localhost';
  • Run manually: php artisan migrate
  • Check storage/logs/laravel.log

Permission Errors

  • chmod -R 755 storage/ bootstrap/cache/
  • chown -R www-data:www-data storage/ bootstrap/cache/
  • SafeCacheService auto-creates cache dirs with 0755 but parent must be writable
Configuration