API Reference

public abstract class JavaPlugin extends PluginBase {
    public JavaPlugin(@Nonnull JavaPluginInit init);

    // Lifecycle methods
    public void setup();     // Register systems, load configs
    public void start();     // Register events, commands
    public void shutdown();  // Save data, cleanup

    // Registry access
    public EventRegistry getEventRegistry();
    public CommandRegistry getCommandRegistry();
    public TaskRegistry getTaskRegistry();
    public EntityStoreRegistry getEntityStoreRegistry();

    // Utilities
    public HytaleLogger getLogger();
    public Path getDataDirectory();
    public <T> T withConfig(String filename, Codec<T> codec);
}

// Basic registration
eventBus.register(EventClass.class, event -> { ... });

// With priority
eventBus.register(EventPriority.FIRST, EventClass.class, event -> { ... });

// With custom priority value
eventBus.register((short) -1000, EventClass.class, event -> { ... });

// Key-based registration
eventBus.register(EventClass.class, keyValue, event -> { ... });

// Global handler (all keys)
eventBus.registerGlobal(EventClass.class, event -> { ... });

// Fallback handler (when no other handler handles it)
eventBus.registerUnhandled(EventClass.class, event -> { ... });

// Async registration
eventBus.registerAsync(EventClass.class, future -> {
    return future.thenApply(event -> {
        // Process async
        return event;
    });
});

// Synchronous dispatch
eventBus.dispatchFor(MyEvent.class).dispatch(new MyEvent());

// Dispatch with key
eventBus.dispatchFor(MyEvent.class, keyValue).dispatch(new MyEvent());

// Async dispatch (returns CompletableFuture)
CompletableFuture<MyEvent> future = eventBus.dispatchForAsync(MyEvent.class).dispatch(event);

// Check if handlers exist
boolean hasHandlers = eventBus.hasListener(MyEvent.class);

// Store registration for later
EventRegistration reg = eventBus.register(MyEvent.class, handler);

// Unregister
reg.unregister();

// Check if enabled
boolean active = reg.isEnabled();

// Combine multiple registrations
EventRegistration combined = EventRegistration.combine(reg1, reg2, reg3);

ShutdownEvent.DISCONNECT_PLAYERS = -48  // First: disconnect players
ShutdownEvent.UNBIND_LISTENERS = -40    // Then: unbind listeners
ShutdownEvent.SHUTDOWN_WORLDS = -32     // Finally: shutdown worlds

public interface CommandContext {
    // Get the command sender
    CommandSender getSender();

    // Get player (if sender is player)
    Player getPlayer();

    // Get arguments
    <T> T getArgument(String name, Class<T> type);
    <T> T getArgumentOrDefault(String name, T defaultValue);

    // Send messages
    void sendMessage(String message);
    void sendError(String message);
}

// Get component from entity
MyComponent comp = entityRef.getComponent(MyComponent.class);

// Check if entity has component
boolean has = entityRef.hasComponent(MyComponent.class);

// Set component on entity
entityRef.setComponent(new MyComponent());

// Get player inventory
Inventory inventory = player.getInventory();

// ItemStack is immutable
ItemStack stack = inventory.getItem(slotIndex);

// Item IDs use namespace:name format
String itemId = "hytale:iron_sword";

// Get teleport component
TeleportComponent teleport = entity.getComponent(TeleportComponent.class);

// Set new position
teleport.setPosition(new Vector3d(x, y, z));

public class MyPlugin extends JavaPlugin {
    private MyConfig config;

    public MyPlugin(@Nonnull JavaPluginInit init) {
        super(init);

        // Load with Codec
        this.config = withConfig("config.json", MyConfigCodec.INSTANCE);

        // Or with custom filename
        this.config = withConfig("settings.json", MyConfigCodec.INSTANCE);
    }
}

public class MyCustomEvent implements IEvent<Void> {
    private final String message;

    public MyCustomEvent(String message) {
        this.message = message;
    }

    public String getMessage() {
        return message;
    }
}

public class PlayerTeleportEvent implements IEvent<Void>, ICancellable {
    private final Player player;
    private Vector3d destination;
    private boolean cancelled = false;

    public PlayerTeleportEvent(Player player, Vector3d destination) {
        this.player = player;
        this.destination = destination;
    }

    public Player getPlayer() { return player; }
    public Vector3d getDestination() { return destination; }
    public void setDestination(Vector3d dest) { this.destination = dest; }

    @Override
    public boolean isCancelled() { return cancelled; }

    @Override
    public void setCancelled(boolean cancelled) { this.cancelled = cancelled; }
}

public class PlayerScoreEvent implements IEvent<UUID> {
    private final UUID playerId;
    private final int score;

    public PlayerScoreEvent(UUID playerId, int score) {
        this.playerId = playerId;
        this.score = score;
    }

    // Key for filtering
    public UUID getPlayerId() { return playerId; }
    public int getScore() { return score; }
}