ChatAPI 1.0

Library for the creation and sending of vanilla chat components.

  1. Rustywolf
    Contributors:
    Rustywolf
    ChatAPI
    Chat Components API for Bukkit
    1. Introduction​
    2. Installation and usage​
    3. Explanation & Examples​
    4. Javadocs & Github​
    1. Introduction

    Hello! By reading this you have agreed to my terms and conditions and therefore i will be visiting you in 10 years time to collect your first born. However, for now I suppose you're interested in the ChatAPI.

    The API was designed to allow simple use of the IChatBaseComponent system and it's implementations in the vanilla minecraft server. For those unaware of what this system is or how it functions, it's the code that handles 'complicated' chat message that you may have seen created using JSON, such as:​
    Code (Text):
    {text:"Click.",clickEvent:{action:run_command,value:"/say Clicked."}}
    (Credit to Skylinerw for enabling my laziness)

    I've tried to make this API as simple and intuitive as simple as possible while keeping it completely flexible. If the system allows it, then it's possible with this API. Feel free to leave comments, contributions or feedback. I'll get around to reading it all :)

    2. Installation and usage

    Installation is simple. Simply drop the .jar for this plugin in your server's plugin directory. To use this within a plugin, add it to your project's dependencies and add "depend: [ChatAPI]" into your plugin.yml, as demonstrated below:

    [​IMG]

    3. Explanation & Examples

    Before we begin, i'd like to dive into how the API is structured and how it works, as it will help you get an understanding of how it works.
    The API is based on a parent/child design, with each ChatComponent having the ability to have children added to it. Each child added can have it's own children, and so on and so forth.
    Due to an interesting ChatModifier(NMS) inheritance bug in vanilla, i handle the inheritance of chat colours and formatting from parents within the API. Any colours or formats that have been set for a parent will be inherited to the child unless the child has had .reset() called on it's own chat modifier, or has had that property set itself.
    The class you will be using the most is ChatMessage. This component comes with a .send(Player...) method to send the message you have crafted to players. I've provided a factory method for this, ChatAPI.create();

    Anyway, here are a few uses of the API to give you an idea of how it runs and what it can do.

    Simple hello message

    [​IMG]
    Code (Text):
    ChatAPI.create().setFormatting(ChatColor.RED)
            .addText("Hello ")
            .addText("Rustywolf").setFormatting(ChatColor.DARK_RED)
            .addText("!")
            .send([players]);
     
    Starting basic, shows that "Hello " and "!" have inherited the red from their parent. the player name is dark red, as specified by the call to setFormatting after adding that text.

    RawTextChatComponent usage

    [​IMG]
    Code (Text):
    ChatAPI.create()
            .addRawText(ChatColor.GRAY + "Hello" + ChatColor.YELLOW + "World")
            .addText("!").setFormatting(ChatColor.BOLD)
            .send([players]);
     
    The RawTextChatComponent will convert legacy text to chat components for use in chat messages. This is purely an example of it's usage, and not how you should actually use the class. An appropriate use of this class would be player display names. We can also see that the exclamation mark at the end is bold, but not yellow as the yellow was part of a separate child.

    Recreating an achievement

    [​IMG]
    Code (Text):
    ChatAPI.create()
        .addText(player.getName())
        .addText(" has earned the achievement ")
            .setFormatting(ChatColor.YELLOW)
        .addBranch()
            .setFormatting(ChatColor.GOLD)
            .setHover(HoverAction.SHOW_ACHIEVEMENT, "achievement.mineWood")
            .onLastChild(component -> {
                component.addText("[").addTranslation("achievement.mineWood").addText("]");
            })
        .send(Bukkit.getOnlinePlayers().toArray(new Player[0]));
    Getting a bit more complicated. Using inheritance on a BranchChatComponent to get the hover effect to apply to all of the text in the achievement notification (and have it be the same colour). Also notice the call to onLastChild, passing in a consumer that accepts a ChatComponent. The point of onLastChild is to allow for better chaining in message construction. And finally, the use of addTranslation will send a message that the client will read, and apply the correct translation from the language file.

    I'll be adding more examples shortly. If you guys have any requests feel free to post them and i'll add them here.


    4. Javadocs & Github

    Javadocs:
    http://javadocs.rusty.codes/chatapi/

    Github:
    https://github.com/Rustywolf/ChatAPI

    I think that's about it for now. Feel free to post any questions or feedback below.​