Meteor Client Addon Development

This skill provides guidance for developing addons for Meteor Client, a Fabric-based Minecraft utility mod.

Key Resources

• •Template Repository: https://github.com/MeteorDevelopment/meteor-addon-template
• •Meteor Client Source: https://github.com/MeteorDevelopment/meteor-client
• •Addon Database: https://raw.githubusercontent.com/cqb13/meteor-addon-scanner/refs/heads/addons/addons.json

Workflow Overview

1. •Setup: Start from the template or clone existing addon
2. •Update Check: Verify template is current with Meteor/Minecraft versions
3. •Development: Implement features following Meteor patterns
4. •Reference: Use filter_addons.py to find examples from verified addons when needed

When you need to find reference implementations, always use the filter_addons.py script to search the addon database rather than manually browsing GitHub or guessing repository URLs.

Starting a New Addon

From Template

Clone the meteor-addon-template and customize:

git clone https://github.com/MeteorDevelopment/meteor-addon-template my-addon
cd my-addon

Check if template needs updating by comparing against meteor-client:

1. •Clone meteor-client temporarily to workspace: git clone --depth=1 https://github.com/MeteorDevelopment/meteor-client
2. •Compare key files: build.gradle, gradle.properties, dependencies, Fabric/Minecraft versions
3. •Update your addon's files to match current versions

Key Files to Configure

• •gradle.properties: Set Minecraft version, Fabric API version, Meteor dependency
• •build.gradle: Configure repositories, dependencies, build settings
• •src/main/resources/fabric.mod.json: Define mod metadata, entrypoint
• •src/main/java/com/example/addon/Addon.java: Main addon class

Updating Existing Addons

When Minecraft or Meteor updates:

1. •Clone meteor-client for reference:

cd /path/to/workspace
git clone --depth=1 https://github.com/MeteorDevelopment/meteor-client

1. •

   Check version changes:

   • •Minecraft version in gradle.properties
   • •Fabric API version
   • •Meteor Client version/dependency format
   • •Java version requirements
2. •

   Update breaking changes:

   • •Check meteor-client commit history for API changes
   • •Look for deprecated methods or refactored classes
   • •Update imports and method calls
3. •

   Find updated examples: Use scripts/filter_addons.py to find verified addons on current version

Finding Reference Implementations

The addon database contains metadata about all known Meteor Client addons. Use the filter_addons.py script to find high-quality examples for reference.

Basic Usage

# Find verified addons for a specific Minecraft version
python scripts/filter_addons.py --mc-version 1.21.11 --verified

# Find all addons for a version (including unverified)
python scripts/filter_addons.py --mc-version 1.21.11 --no-verified

# Limit results
python scripts/filter_addons.py --mc-version 1.21.11 --verified --limit 10

# Get JSON output for programmatic use
python scripts/filter_addons.py --mc-version 1.21.11 --verified --json

Advanced Filtering

# Find addons with specific features
python scripts/filter_addons.py --feature-type modules --feature-name "AutoTotem"

# Filter by minimum stars
python scripts/filter_addons.py --mc-version 1.21.11 --min-stars 50

# Sort by different criteria
python scripts/filter_addons.py --mc-version 1.21.11 --sort-by last_update

# Include archived repositories (normally excluded)
python scripts/filter_addons.py --mc-version 1.21.11 --include-archived

Important Notes

1. •

   supported_versions field: Some addons list multiple compatible versions in their custom.supported_versions field. The filter script checks both mc_version and supported_versions when filtering.

2. •

   None handling: The addon database may contain null values for features lists or supported_versions. The filter script handles these gracefully.

3. •

   Default behavior: Without --no-verified, the script only shows verified addons by default.

Quality Filtering Rules

Always follow these rules when searching references:

1. •Skip archived addons - Unless specifically porting legacy code
2. •Prefer verified addons - Only use unverified if no verified examples exist
3. •Match versions - Ensure addon's Meteor/Minecraft versions are compatible with your project
4. •Consider stars - Higher star count often indicates better maintained code

Cloning References

Clone addons for analysis (stores in ai_reference/ or similar):

# Single addon
python scripts/clone_for_analysis.py https://github.com/owner/addon-name

# Multiple from filter results
python scripts/filter_addons.py --mc-version 1.21.1 --verified --limit 5 --json | \
    python scripts/clone_for_analysis.py --from-json

# Custom target directory
python scripts/clone_for_analysis.py https://github.com/owner/addon --target ./my_refs

Best practice: If an ai_reference/ directory exists in workspace, use it for storing cloned repos and keep them there (don't cleanup automatically).

Common Addon Structure

Meteor addons typically include:

• •Modules (extends Module): Features that can be toggled on/off
• •Commands (extends Command): Chat commands for addon functionality
• •HUD Elements (extends HudElement): On-screen display components
• •Categories: Organize modules in Meteor's GUI

Checking for Breaking Changes

When updating to newer Minecraft/Meteor versions:

1. •Clone meteor-client to workspace temporarily
2. •Check commit history: Look for "breaking" or version bump commits
3. •Compare API surfaces: Check if methods you use still exist
4. •Look at migration examples: Find other addons that updated successfully

Example workflow:

cd /workspace
git clone --depth=1 https://github.com/MeteorDevelopment/meteor-client
cd meteor-client
git log --oneline --grep="breaking" -20

Working with Legacy Versions

If working with older Minecraft/Meteor versions:

1. •Use --include-archived flag when searching if truly necessary
2. •Specify exact --mc-version when filtering
3. •Check addon's custom.supported_versions field for compatibility
4. •Be cautious - legacy code may use deprecated patterns

Troubleshooting

Template is Outdated

1. •Clone meteor-client for current API reference
2. •Use filter_addons.py to find recently updated verified addons
3. •Compare their gradle files and dependencies
4. •Update your project's files to match

Can't Find Version-Compatible Examples

1. •Check if the version exists in the database: python scripts/filter_addons.py --mc-version X.XX.XX --no-verified
2. •Remove --verified flag temporarily (less ideal but may be necessary)
3. •Sort by --sort-by last_update to find recently maintained addons
4. •Check meteor-client source directly for official examples

Need Specific Feature Implementation

1. •Search by feature type: python scripts/filter_addons.py --feature-type modules --feature-name YourFeature
2. •Look at multiple implementations for best practices
3. •Clone top 3-5 verified addons for comparison

Script Issues

If filter_addons.py encounters errors:

• •Ensure you have internet connectivity (script fetches from GitHub)
• •Check that Python 3 is installed and available
• •The script handles None values gracefully, but very old addon entries may have unexpected data formats
• •If a specific addon looks corrupted, use --limit to skip past it

Best Practices

• •Keep addon updated with latest Minecraft/Meteor versions
• •Follow Meteor's code style and patterns
• •Use verified addons as reference when possible
• •Store cloned references in ai_reference/ for easy access
• •Check meteor-client source for authoritative API documentation
• •Test with multiple Minecraft versions if supporting ranges