firefrost-services/services/modpack-version-checker/blueprint-extension/README.md

ModpackChecker — Pterodactyl Blueprint Extension

Version: 1.0.0
Author: Firefrost Gaming / Frostystyle
License: Commercial License - Unauthorized redistribution, resale, or sharing of this source code is strictly prohibited.

A Pterodactyl Panel extension that checks modpack versions across CurseForge, Modrinth, FTB, and Technic platforms. Shows update status on the dashboard and provides manual version checks from the server console.

---

Table of Contents

1. Features
2. Architecture Overview
3. File Structure
4. Installation
5. Configuration
6. Usage
7. Development
8. API Reference
9. Troubleshooting
10. Support

---

Features

Dashboard Badge

• Shows a colored dot next to each server name on the dashboard
• 🟠 Orange (Fire #FF6B35): Update available
• 🟢 Teal (Frost #4ECDC4): Up to date
• Hover for version details tooltip
• Single API call per page load (cached with 60s TTL)

Console Widget

• "Check for Updates" button on each server's console page
• Real-time version check against platform API
• Rate limited: 2 checks per minute per server
• Shows modpack name and latest version

Admin Panel

• Configure CurseForge API key
• View supported platforms
• PRO features: Discord notifications, custom check intervals

Supported Platforms

Platform	ID Type	API Key Required	Status
CurseForge	Numeric project ID	✅ Yes	✅ Working
Modrinth	Project ID or slug	❌ No	✅ Working
FTB	Numeric modpack ID	❌ No	✅ Working
Technic	URL slug	❌ No	✅ Working

---

Architecture Overview

┌─────────────────────────────────────────────────────────────────────────────┐
│                           MODPACK VERSION CHECKER                            │
└─────────────────────────────────────────────────────────────────────────────┘

                    ┌─────────────────────────────────────┐
                    │     CRON JOB (runs every 4-6 hrs)   │
                    │     php artisan modpackchecker:check │
                    └──────────────────┬──────────────────┘
                                       │
                                       ▼
                    ┌─────────────────────────────────────┐
                    │         DATABASE CACHE              │
                    │     modpackchecker_servers table    │
                    │                                     │
                    │  • server_uuid                      │
                    │  • platform, modpack_id             │
                    │  • current_version, latest_version  │
                    │  • status (string)                  │
                    │  • last_checked timestamp           │
                    └──────────────────┬──────────────────┘
                                       │
                    ┌──────────────────┴──────────────────┐
                    │                                     │
                    ▼                                     ▼
    ┌───────────────────────────┐       ┌───────────────────────────┐
    │    DASHBOARD BADGE        │       │    CONSOLE WIDGET         │
    │    (UpdateBadge.tsx)      │       │    (wrapper.tsx)          │
    │                           │       │                           │
    │  • Reads from cache ONLY  │       │  • Manual "Check" button  │
    │  • 60-second TTL          │       │  • LIVE API call          │
    │  • Shows 🟠 or 🟢 dot     │       │  • Rate limited (2/min)   │
    └───────────────────────────┘       └───────────────────────────┘

---

File Structure

blueprint-extension/
├── README.md
├── CHANGELOG.md
├── conf.yml
├── build.sh
├── icon.png
│
├── app/
│   ├── Console/Commands/
│   │   └── CheckModpackUpdates.php
│   ├── Http/Controllers/
│   │   └── ModpackAPIController.php
│   └── Services/
│       └── ModpackApiService.php
│
├── admin/
│   ├── controller.php
│   └── view.blade.php
│
├── database/migrations/
│   └── 2026_04_06_000000_create_modpackchecker_servers_table.php
│
├── routes/
│   └── client.php
│
└── views/
    ├── server/wrapper.tsx
    └── dashboard/UpdateBadge.tsx

---

Installation

Prerequisites

• Pterodactyl Panel v1.11+
• Blueprint Framework (beta-2026-01 or newer)
• PHP 8.1+
• Node.js 18+
• Yarn package manager

Standard Installation (BuiltByBit)

1. Upload the downloaded modpackchecker.blueprint file to your Pterodactyl panel's root directory (usually /var/www/pterodactyl).

2. Run the Blueprint installation command:

   blueprint -install modpackchecker
   

3. The framework will automatically inject the frontend components and rebuild the panel assets.

4. Set up the cron job for automated checks:

   # Add to crontab
   0 */6 * * * www-data cd /var/www/pterodactyl && php artisan modpackchecker:check >> /dev/null 2>&1
   

Developer/Manual Installation

If installing from raw source:

cp -r blueprint-extension /var/www/pterodactyl/.blueprint/extensions/modpackchecker
chown -R www-data:www-data /var/www/pterodactyl/.blueprint/extensions/modpackchecker
blueprint -build

---

Configuration

Server Egg Variables

For modpack detection, set these variables in your server's egg:

Variable	Description	Example
MODPACK_PLATFORM	Platform name	modrinth, curseforge, ftb, technic
MODPACK_ID	Platform-specific ID	adrenaserver (Modrinth slug)
MODPACK_CURRENT_VERSION	Installed version	1.7.0

CurseForge API Key

CurseForge requires an API key:

1. Apply for API access at https://console.curseforge.com/
2. Go to Admin Panel → Extensions → ModpackChecker
3. Enter your API key and save

---

Usage

Dashboard Badge

Badges appear automatically for servers that:

• Have MODPACK_PLATFORM egg variable set
• Have been checked by the cron job at least once

Manual Check

1. Go to any server's console page
2. Click "Check for Updates" button
3. View results showing modpack name and version status

Cron Command

Run manually for testing:

php artisan modpackchecker:check

---

Development

Adding a New Platform

1. Open app/Services/ModpackApiService.php
2. Add your new platform check method (e.g., private function checkNewPlatform(string $id): array)
3. Add the platform key to the match() statement inside the fetchLatestVersion() method
4. The Controller and Cron Command will automatically inherit the new logic
5. Update this README to reflect the newly supported platform

Testing API Endpoints

# Manual check (requires auth token)
curl -X POST "https://panel.example.com/api/client/extensions/modpackchecker/servers/{uuid}/check" \
  -H "Authorization: Bearer {token}"

# Get all statuses
curl "https://panel.example.com/api/client/extensions/modpackchecker/status" \
  -H "Authorization: Bearer {token}"

---

API Reference

POST /api/client/extensions/modpackchecker/servers/{server}/check

Manual version check for a specific server. Triggers a live API call to the modpack platform.

Rate Limit: 2 requests per minute per server

Response:

{
    "success": true,
    "platform": "modrinth",
    "modpack_id": "adrenaserver",
    "modpack_name": "Adrenaserver",
    "latest_version": "1.7.0+1.21.1.fabric",
    "status": "checked"
}

GET /api/client/extensions/modpackchecker/status

Get cached status for all servers accessible to the authenticated user.

Response:

{
    "a1b2c3d4-...": {
        "update_available": true,
        "modpack_name": "All The Mods 9",
        "current_version": "0.2.51",
        "latest_version": "0.2.60"
    }
}

---

Troubleshooting

Badge not showing

1. Check server has MODPACK_PLATFORM variable set
2. Run cron command manually: php artisan modpackchecker:check
3. Check modpackchecker_servers table for entries

"CurseForge API key not configured"

1. Go to Admin → Extensions → ModpackChecker
2. Enter your CurseForge API key
3. Key must have mod read permissions

500 errors on check

1. Check PHP error log: tail -f /var/log/php8.3-fpm.log
2. Verify controller namespace: Pterodactyl\Http\Controllers
3. Restart PHP-FPM: systemctl restart php8.3-fpm

"Rate limit reached" message

The manual check is limited to 2 requests per minute per server. Wait 60 seconds and try again.

---

Support

Need help? Join our Discord for support:

• Discord: discord.firefrostgaming.com
• Email: dev@firefrostgaming.com
• Website: firefrostgaming.com

---

Credits

Developed by: Firefrost Gaming / Frostystyle
Architecture Review: Gemini AI

Part of Firefrost Gaming
Fire + Frost + Foundation = Where Love Builds Legacy 🔥❄️💙