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

2. Check version changes:

   • Minecraft version in

     gradle.properties

   • Fabric API version
   • Meteor Client version/dependency format
   • Java version requirements

3. Update breaking changes:

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

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