DOCSEARCHbyAlgolia
Submit Docs

Kapi Documentation

website·Indexed 30 days ago

https://kapimc.github.io/docs

A framework for creating Minecraft plugins, designed as an alternative to Spigot and Paper. Features include a command creation system with @Literal and @SubCommand, task scheduling via TaskBuilder and KapiTask, SQLite database integration with SqliteDB and QueryBuilder, and null-safety utilities like Option<T> and Result<T>.

Tokens
3.5K
Snippets
22
Records
34
Agent score
71%

What's inside Kapi

  1. Overview of Kapi framework benefits over Spigot and Paper

    Kapi is a "batteries included" framework designed to reduce the boilerplate and repetitive utility function implementation common in the Spigot API. It simplifies the development of both simple and complex plugins by providing a more comprehensive set of built-in tools compared to the minimal Spigot/Paper APIs.

  2. Use Built-in Particle Templates and Systems

    The system provides built-in particle templates for common shapes such as circles, squares, and lines. These templates include auto-scaling functionality to reduce boilerplate code when creating visual effects.

  3. Create custom items with the Custom Items Builder

    The Custom Items Builder allows for the creation of items with defined display names, lore, materials, and persistent data (NBT/components). It supports:

    • Event handling: Defining logic for onRightClick and onLeftClick.
    • Unique identification: Using #unique() to uniquely identify an item.
    • Integration: Tools for registering recipes and other item utilities.

  4. Implement the Command Creation System

    The Command Creation System provides a streamlined way to develop commands with the following features:

    • Type-safe arguments (e.g., restricting input to integers or player names).
    • Automatic handling and validation of invalid user input.
    • Automatic generation of tab completions based on argument types (e.g., suggesting all online players for a 'Player' argument).

  5. Use Jspecify annotations for nullability hints

    Kapi bundles the Jspecify library to provide static analysis hints about whether a variable can be null. Use @NonNull for values that cannot be null and @Nullable for values that may be null. This helps developers identify where null checks are required.
    @NonNull String name; // Cannot be null
@Nullable String middleName; // May be null

  6. Build SQL queries programmatically with QueryBuilder

    The QueryBuilder allows you to construct SQL queries without writing raw strings, reducing typos and the risk of SQL injection. Calling .build() on a QueryBuilder returns a SqlQuery object, which can be passed directly into db.executeUpdate() or db.executeQuery().
    SqliteDB db = ...;
SqlQuery query = QueryBuilder.insertInto("players")
    .columns("name")
    .values("Steve")
    .build();

db.executeUpdate(query);

  7. Handle task completion with onFinish

    Use the .onFinish() method to define a callback that executes when a task finishes its execution cycle (e.g., after reaching a stopping condition).
    TaskBuilder.create(() -> {
    System.out.println("Task Started");
}).onFinish(() -> {
    System.out.println("Task Finished");
}).schedule();

  8. Implement custom commands using the Command System

    Kapi provides a Command System for creating and registering in-game commands. Developers can extend the Command class to define a command and use the @SubCommand annotation to mark specific methods within that class as subcommands. Commands are registered using KapiPlugin#registerCommand(String, Command). The system supports automatic reporting of possible subcommands to the user when no exact match is found.
    // Example structure
public class MyCommand extends Command {
    @SubCommand
    public void execute(ArgumentParser<String> arg) {
        // Command logic
    }
}

// Registration in KapiPlugin
plugin.registerCommand("mycommand", new MyCommand());

  9. Create custom argument parsers for commands

    The Command System uses ArgumentParser<T> to parse generic types within subcommand methods. Users can implement their own parsers for custom types and register them via the ArgumentRegistry. Built-in parsers are already available for primitives, enums, arrays, List<T>, Option<T>, Location, and Player.

  10. Schedule a basic task using TaskBuilder

    Use TaskBuilder.create() to define a block of code and .schedule() to execute it. By default, a scheduled task without a delay will execute on the next server tick (1 tick = 0.05s). You can reuse a TaskBuilder instance to call schedule() multiple times or modify it between calls.
    TaskBuilder.create(() -> {
    // Your code
}).schedule();

  11. Create a new SQLite database

    Initialize a file-based SQLite database using the SqliteDB.create method. The database is stored as a single file in the plugin's data folder.
    SqliteDB db = SqliteDB.create("my_sqlite.db");

  12. Create and register a custom Kapi command

    To create a custom command, extend the io.github.kapimc.kapi.commands.Command class. You must register the command instance within the onPluginLoad() method of your main plugin class (which extends KapiPlugin) using registerCommand(). Additionally, the command must be declared in the plugin.yml file.
    import io.github.kapimc.kapi.commands.Command;

public class MyGiveCommand extends Command {
    // Command implementation
}

public class YourMainPluginClass extends KapiPlugin {
    @Override
    public void onPluginLoad() {
        registerCommand("mygive", new MyGiveCommand());
    }
}