d735e3d9db
Admin Panel (view.blade.php): - Changed CurseForge API key from password dots to plain text - Fixed callouts: dark theme (#1a1a2e) with Frost/Fire accent borders - Improved code tag styling for readability - Changed support link to firefrostgaming.com/discord README.md: - Added Prerequisites section (PHP 8.1+, Node.js 18+, Yarn, Blueprint) Reviewed by: Michael 'Frostystyle' Krause (The Wizard) Signed-off-by: Claude (Chronicler #63) <claude@firefrostgaming.com>
309 lines
10 KiB
Markdown
309 lines
10 KiB
Markdown
# 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](#features)
|
|
2. [Architecture Overview](#architecture-overview)
|
|
3. [File Structure](#file-structure)
|
|
4. [Installation](#installation)
|
|
5. [Configuration](#configuration)
|
|
6. [Usage](#usage)
|
|
7. [Development](#development)
|
|
8. [API Reference](#api-reference)
|
|
9. [Troubleshooting](#troubleshooting)
|
|
10. [Support](#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:
|
|
```bash
|
|
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:
|
|
```bash
|
|
# 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:
|
|
```bash
|
|
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:
|
|
```bash
|
|
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
|
|
```bash
|
|
# 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:**
|
|
```json
|
|
{
|
|
"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:**
|
|
```json
|
|
{
|
|
"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](https://discord.firefrostgaming.com)
|
|
- **Email:** dev@firefrostgaming.com
|
|
- **Website:** [firefrostgaming.com](https://firefrostgaming.com)
|
|
|
|
---
|
|
|
|
## Credits
|
|
|
|
**Developed by:** Firefrost Gaming / Frostystyle
|
|
**Architecture Review:** Gemini AI
|
|
|
|
**Part of Firefrost Gaming**
|
|
*Fire + Frost + Foundation = Where Love Builds Legacy* 🔥❄️💙
|