Installation & Setup

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+ installed and running
• PHP 8.1, 8.2, or 8.3 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:

Validation: Must start with 1., minor version 0-50. Normalised to major.minor. Cached 5 minutes.

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: 1.21.4"
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: 1.21 (Latest) through 1.7, with 1.12 (Popular) and 1.8 (Legacy) labels.

Verification Checklist

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-1.21.4.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