Feature Request: Add Developer API for Chat Interception and Message Filtering

[virgil698]

Feature Request: Add Developer API for Chat Interception and Message Filtering

Description

I would like to request the addition of a comprehensive developer API for SlimeRanks that would allow third-party plugins to interact with and intercept chat messages before they are processed and displayed with rank formatting.

Use Case

I am developing a plugin that needs to filter/intercept certain chat messages based on custom logic before they reach SlimeRanks for rank prefix processing. Currently, there's no clean way to integrate with SlimeRanks' chat handling system, which can lead to conflicts or incomplete message processing.

Requested API Features

1. Chat Event Hooks

// Pre-processing hook - before SlimeRanks formats the message
public interface SlimeRanksChatPreProcessor {
    ChatProcessResult onPreProcess(Player player, String message, ChatContext context);
}

// Post-processing hook - after SlimeRanks formats the message
public interface SlimeRanksChatPostProcessor {
    void onPostProcess(Player player, Component formattedMessage, ChatContext context);
}

2. Message Filtering API

// Register custom message filters
public interface SlimeRanksAPI {
    void registerChatFilter(ChatFilter filter, EventPriority priority);
    void unregisterChatFilter(ChatFilter filter);
    
    // Allow cancellation of chat processing
    boolean cancelChatProcessing(Player player, String messageId);
}

3. Integration Points

• Event Priority Management: Allow developers to specify when their filters should run relative to SlimeRanks processing
• Message Cancellation: Ability to prevent messages from being processed by SlimeRanks entirely
• Context Access: Access to rank information, player data, and formatting context
• Async Support: Proper handling for async chat processing

Benefits

1. Better Plugin Compatibility: Reduces conflicts between chat-related plugins
2. Enhanced Customization: Allows server owners to create more sophisticated chat filtering systems
3. Developer Friendly: Provides clean integration points for third-party development
4. Performance: Efficient event handling without duplicating chat listeners

Suggested Implementation

• Add a new SlimeRanksAPI class as the main entry point
• Implement event-driven architecture with proper priority handling
• Provide comprehensive JavaDoc documentation
• Include example usage in the plugin documentation
• Maintain backward compatibility with existing functionality

Example Usage Scenario

// Register a custom chat filter
SlimeRanksAPI api = SlimeRanksAPI.getInstance();

api.registerChatFilter(new ChatFilter() {
    @Override
    public FilterResult filter(Player player, String message, ChatContext context) {
        // Custom filtering logic
        if (shouldInterceptMessage(message)) {
            return FilterResult.CANCEL; // Prevent SlimeRanks processing
        }
        return FilterResult.CONTINUE; // Allow normal processing
    }
}, EventPriority.HIGH);

Additional Considerations

• Support for both Paper's new AsyncChatEvent and legacy AsyncPlayerChatEvent
• Folia compatibility (as mentioned in your features)
• MiniMessage integration for custom formatting
• Thread-safe operations for async processing

Environment

• Server Software: Paper/Purpur/Folia
• SlimeRanks Version: Latest
• Minecraft Version: 1.21+

This API would greatly enhance SlimeRanks' extensibility and make it easier for developers to create complementary plugins that work seamlessly with your rank system.

Thank you for considering this feature request!

[Lxca128]

Hey @virgil698

thanks a lot for taking the time to write such a detailed issue!

You’re absolutely right; having an API that allows other plugins to interact with SlimeRanks would be a very useful feature. In fact, that’s already on my roadmap, alongside many other planned improvements.

That said, I usually only work on SlimeRanks occasionally, since I’m primarily focused on larger projects. An API will definitely make its way into SlimeRanks at some point, but I can’t promise it’ll happen very soon.

In the next few days, my main priority will be updating SlimeRanks to 1.21.9, along with some optimizations in both the codebase and general handling of the plugin. This will also help lay the groundwork to implement an API more efficiently in the future.

As soon as I have any updates on the API or related functionality, I’ll make sure to let you know here in the issue.

^^Luca