firefrost-operations-manual/docs/planning/modpack-version-checker-research.md

Modpack Version Checker - Research Summary

Date: April 1, 2026
Researched by: Chronicler #52
Purpose: Gather technical resources for MVP development

---

Blueprint Framework - Key Resources

Official Documentation

• Main Site: https://blueprint.zip/
• Documentation: https://blueprint.zip/docs/
• Quick Start Guide: https://blueprint.zip/guides/dev/quickstart
• GitHub: https://github.com/BlueprintFramework/framework
• Templates Repo: https://github.com/BlueprintFramework/templates

Key Facts About Blueprint

• Open-source extension framework for Pterodactyl Panel
• Fiscally sponsored by The Hack Foundation (501c3 nonprofit)
• Industry-leading modding platform (well-established)
• Extensions install/remove in seconds via CLI
• No manual file editing or merge conflicts
• Laravel/PHP backend + React frontend support
• Active marketplace on BuiltByBit (already has Blueprint category)

Development Workflow

1. Create extension: blueprint -init
2. Development location: .blueprint/dev/ (relative to Pterodactyl directory)
3. Build/test: blueprint -build (apply changes to live panel)
4. Package: Creates .blueprint file for distribution
5. Install: blueprint -i extension.blueprint

Extension Structure (from docs)

extension-name/
├── conf.yml              # Extension metadata (name, author, version)
├── components.yml        # Component definitions
├── console.yml           # Console/CLI commands
├── admin/               # Admin panel views (Blade templates)
├── controllers/         # Custom PHP controllers
├── database/            # Migrations
└── public/              # Assets (CSS, JS, images)

---

CurseForge API

API Key Status

Michael says: "I think I already have the CurseForge API key"

Testing the API Key

curl -H "x-api-key: YOUR_KEY_HERE" \
  "https://api.curseforge.com/v1/mods/search?gameId=432&classId=4471"

What this tests:

• gameId=432 = Minecraft
• classId=4471 = Modpacks
• Should return JSON array of modpack data

Key Endpoints We'll Need

1. Search Modpacks: /v1/mods/search?gameId=432&classId=4471
2. Get Modpack Details: /v1/mods/{modId}
3. Get Modpack Files: /v1/mods/{modId}/files
4. Get Latest File: /v1/mods/{modId}/files (filter by latest)

Rate Limits (to verify)

• Need to check CurseForge API docs for rate limits
• BYOK model means each buyer uses their own limits
• We cache results, so checking once per 12-24 hours is fine

---

Modrinth API

API Docs

• Main API: https://docs.modrinth.com/api-spec/
• No API key required (public API, rate limited by IP)
• User-Agent header required (per Gemini's guidance)

User-Agent Format (per Gemini)

FirefrostExtension/1.0 (Contact: admin@buyer-domain.com)

Key Endpoints We'll Need

1. Get Project: /v2/project/{id|slug}
2. Get Project Versions: /v2/project/{id|slug}/version
3. Search Projects: /v2/search?facets=[["project_type:modpack"]]

Rate Limits

• Public API, IP-based rate limiting
• Need to check exact limits in docs
• Same 12-24 hour caching strategy applies

---

BuiltByBit Marketplace

Key Facts

• Blueprint category already exists: https://builtbybit.com/resources/blueprint.29609/
• Active marketplace with lots of Blueprint extensions
• Pricing range for extensions: $5-$30 typically
• Gemini recommended: $15 (sweet spot)

Top Blueprint Extensions (for research)

From search results, popular extensions include:

• Announcements system
• Theme customizations
• Server management tools
• Analytics/monitoring tools

Submission Requirements (need to research)

• Product description
• Screenshots
• Installation guide
• Support policy
• License terms
• Refund policy

---

Pterodactyl Modpack Installer Egg

Environment Variables (per Gemini)

The Modpack Installer egg uses environment variables to specify platform:

• Common variable names: INSTALL_TYPE, PLATFORM, MODPACK_API
• Values: curseforge, modrinth, ftb, atlauncher, technic, voidswrath

Detection Strategy

// Pseudocode
$envVars = $server->environment;
$platform = $envVars['INSTALL_TYPE'] ?? $envVars['PLATFORM'] ?? 'unknown';

if (in_array($platform, ['curseforge', 'modrinth'])) {
    $is_supported = true;
} else {
    $is_supported = false;
    $unsupported_reason = "Platform '$platform' does not provide public API";
}

---

Database Schema (Final from Gemini)

CREATE TABLE modpack_version_tracker (
    id BIGINT PRIMARY KEY AUTO_INCREMENT,
    server_id INT NOT NULL,
    platform VARCHAR(50) NOT NULL,  -- Future-proof (not ENUM)
    project_id VARCHAR(255) NOT NULL,
    current_version_id VARCHAR(255),
    latest_version_id VARCHAR(255),
    is_supported BOOLEAN DEFAULT TRUE,
    unsupported_reason VARCHAR(255),  -- NULL if supported
    last_checked_at TIMESTAMP,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
    FOREIGN KEY (server_id) REFERENCES servers(id) ON DELETE CASCADE
);

---

Laravel Task Scheduler

How It Works (per Gemini)

• Pterodactyl already runs php artisan schedule:run every minute via cron
• We inject our version-checking logic into Laravel's Task Scheduler
• No separate systemd service needed (plug-and-play for buyers)

Implementation Pattern

// In our extension's service provider
protected function schedule(Schedule $schedule)
{
    $schedule->call(function () {
        // Check modpack versions
    })->everyTwelveHours(); // Configurable by buyer
}

---

Next Steps - Action Items

Immediate (Tonight/Tomorrow)

1. ✅ Test CurseForge API key (Michael to run curl command)
2. ⏳ Read Blueprint quick start guide (blueprint.zip/guides/dev/quickstart)
3. ⏳ Clone Blueprint templates repo (for extension scaffold)
4. ⏳ Read CurseForge API docs (endpoints, rate limits, authentication)
5. ⏳ Read Modrinth API docs (endpoints, User-Agent requirements)

Research Phase (1-2 days)

1. ⏳ Study Blueprint extension examples on GitHub
2. ⏳ Review BuiltByBit Blueprint marketplace listings
3. ⏳ Document exact API calls needed for both platforms
4. ⏳ Create development environment on Dev VPS
5. ⏳ Test API calls manually (curl/Postman)

Development Phase (After Research)

1. Scaffold extension with Blueprint CLI
2. Implement platform detection
3. Build API integration
4. Create admin UI
5. Test on Panel VPS

---

Questions to Answer During Research

1. CurseForge:

   • Exact rate limits?
   • How to detect deleted modpacks (404 handling)?
   • Best way to compare version IDs?

2. Modrinth:

   • Exact rate limits?
   • User-Agent format verification?
   • Version comparison logic?

3. Blueprint:

   • How to add admin settings page?
   • How to create database migrations?
   • How to schedule Laravel tasks from extension?
   • How to package for distribution?

4. Pterodactyl:

   • How to query server environment variables?
   • Where is server data stored in Panel database?
   • API vs direct database access?

---

Status: Research phase ready to begin
Next Action: Michael tests CurseForge API key
Timeline: 1-2 days research → 1-2 weeks development → Launch

---

Fire + Frost + Foundation = Where Love Builds Legacy 💙🔥❄️