Orion Discord Bot API

A clean, modular Discord bot API framework built with Java and JDA. Orion-API provides the core interfaces and contracts for building scalable Discord bots with a plugin-like module system, comprehensive permission management, and hot-reloadable components.

Note: This is the API layer providing interfaces and contracts. For a complete implementation, see Orion-Core.

🚀 Features

🔧 Core API Framework

Modular Architecture: Clean interfaces for plugin-like module system
Command System: Interfaces for slash commands with sub-command support
Event System: Clean event handling contracts
Configuration Management: Interfaces for YAML-based configuration
Permission System: Comprehensive permission management interfaces

🛠️ Developer Experience

Clean Contracts: Well-defined interfaces for all components
Flexible Implementation: Multiple implementations possible
Configuration: Flexible configuration system interfaces

🏗️ Architecture

Orion-API follows a clean architecture pattern with pure interface definitions:

fr.orion.api/              # Pure API interfaces
├── command/               # Command system interfaces
│   ├── Command.java
│   ├── CommandRegistry.java
│   └── ParentCommand.java
├── config/                # Configuration interfaces
│   ├── ModuleConfig.java
│   └── YamlModuleConfig.java
├── event/                 # Event system interfaces
│   └── EventRegistry.java
├── module/                # Module system interfaces
│   ├── Module.java
│   ├── AbstractModule.java
│   ├── ModuleManager.java
│   ├── ModuleDescriptor.java
│   └── loader/
├── permission/            # Permission system interfaces
│   ├── PermissionManager.java
│   ├── PermissionNode.java
│   └── impl/              # Default implementations
│       └── YamlPermissionManager.java
├── interfaction/          # UI interaction helpers
│   ├── EmbedTemplate.java
│   └── ConfirmationSystem.java
└── Bot.java               # Main bot interface

Design Principles

Interface Segregation: Small, focused interfaces
Dependency Inversion: Depend on abstractions, not concretions
Open/Closed: Open for extension, closed for modification
Single Responsibility: Each interface has one clear purpose

📦 Installation

Gradle

Add to your build.gradle:

repositories {
    mavenCentral()
    maven { url 'https://jitpack.io' }
}

dependencies {
    implementation("com.github.Arinonia:orion-api:v0.1.0-beta")
    implementation("net.dv8tion:JDA:5.5.1")
    implementation("org.yaml:snakeyaml:2.4")
    implementation("ch.qos.logback:logback-classic:1.5.13")
}

Maven

Add to your pom.xml:

<repositories>
    <repository>
        <id>jitpack</id>
        <url>https://jitpack.io</url>
    </repository>
</repositories>

<dependencies>
<dependency>
    <groupId>com.github.Arinonia</groupId>
    <artifactId>orion-api</artifactId>
    <version>v0.1.0-beta</version>
</dependency>
<dependency>
    <groupId>net.dv8tion</groupId>
    <artifactId>JDA</artifactId>
    <version>5.5.1</version>
</dependency>
<dependency>
    <groupId>org.yaml</groupId>
    <artifactId>snakeyaml</artifactId>
    <version>2.4</version>
</dependency>
<dependency>
    <groupId>ch.qos.logback</groupId>
    <artifactId>logback-classic</artifactId>
    <version>1.5.13</version>
</dependency>
</dependencies>

🧩 Core Concepts

Bot Interface

The main entry point providing access to all subsystems:

public interface Bot {
    CommandRegistry getCommandRegistry();
    EventRegistry getEventRegistry();
    JDA getJDA();
    ModuleManager getModuleManager();
    PermissionManager getPermissionManager();
}

Module System

Modules are the building blocks of functionality:

public interface Module {
    void onEnable();
    void onDisable();
    boolean isEnabled();
    ModuleConfig getConfig();
    boolean hasPermission(Member member, String permission);
}

Permission System

Granular permission control with wildcards:

public interface PermissionManager {
    boolean hasPermission(Member member, String permission);
    void addUserPermission(String userId, String permission);
    void addRolePermission(String roleId, String permission);
    Set<String> getEffectivePermissions(Member member);
}

📦 Module Development

Creating a Module

Extend the provided AbstractModule class:

public class MyModule extends AbstractModule {
    
    @Override
    public void onEnable() {
        // Register commands
        registerCommand(new MyCommand());
        
        // Register event listeners
        registerListener(new MyEventListener());
        
        getLogger().info("MyModule enabled!");
    }
    
    @Override
    public void onDisable() {
        getLogger().info("MyModule disabled!");
    }
}

Module Descriptor

Create module.yml in your resources:

id: "my_module"
name: "My Awesome Module"
version: "1.0.0"
main: "com.example.MyModule"
description: "A sample module for Orion"
author: "YourName"
dependencies: []
softDependencies: []

Commands with Permissions

public class MyCommand extends ParentCommand {
    
    public MyCommand(MyModule module) {
        registerSubcommand("test", "Test command", 
            null,
            new SubcommandHandler() {
                @Override
                public void execute(SlashCommandInteractionEvent event) {
                    // Check permission using the API
                    if (!module.hasPermission(event.getMember(), "test")) {
                        event.reply("❌ Insufficient permissions").setEphemeral(true).queue();
                        return;
                    }
                    
                    event.reply("✅ Test successful!").queue();
                }
                
                @Override
                public SubcommandData getSubcommandData() {
                    return new SubcommandData("test", "Test command");
                }
            }
        );
    }
    
    @Override
    public String getName() { return "mycommand"; }
    
    @Override
    public String getDescription() { return "My custom command"; }
}

Event Listeners

public class MyEventListener extends ListenerAdapter {
    private final MyModule module;
    
    public MyEventListener(MyModule module) {
        this.module = module;
    }
    
    @Override
    public void onGuildMemberJoin(GuildMemberJoinEvent event) {
        // Use module's logger
        module.getLogger().info("New member joined: {}", event.getUser().getAsTag());
        
        // Access configuration
        String welcomeMessage = module.getConfig().getString("welcomeMessage");
        
        // Send welcome message
        TextChannel channel = event.getGuild().getTextChannelById("CHANNEL_ID");
        if (channel != null) {
            channel.sendMessage(welcomeMessage + " " + event.getMember().getAsMention()).queue();
        }
    }
}

🔒 Permission System

Permission Structure

The API defines a flexible permission system following the pattern: module.action

my_module.test - Specific action permission
my_module.* - All permissions for the module
* - Global administrator access

Permission Interfaces

public interface PermissionManager {
    // Check permissions
    boolean hasPermission(Member member, String permission);
    boolean hasPermission(User user, String permission);
    boolean hasPermission(Role role, String permission);
    
    // Manage user permissions
    void addUserPermission(String userId, String permission);
    void removeUserPermission(String userId, String permission);
    Set<String> getUserPermissions(String userId);
    
    // Manage role permissions
    void addRolePermission(String roleId, String permission);
    void removeRolePermission(String roleId, String permission);
    Set<String> getRolePermissions(String roleId);
    
    // Utility methods
    Set<String> getEffectivePermissions(Member member);
    void clearUserPermissions(String userId);
    void clearRolePermissions(String roleId);
}

Using Permissions in Modules

// In your module - automatic prefix with module ID
if (!hasPermission(member, "action")) {
    // Permission denied - checks "my_module.action"
}

// Cross-module permission check - full permission string
if (getPermissionManager().hasPermission(member, "other_module.action")) {
    // Advanced features
}

// Check wildcard permissions
if (getPermissionManager().hasPermission(member, "my_module.*")) {
    // User has all module permissions
}

Permission Node Utility

public class PermissionNode {
    public PermissionNode(String permission);
    public boolean matches(String requiredPermission);
    public boolean isWildcard();
    public String getModule();
}

// Usage
PermissionNode node = new PermissionNode("my_module.*");
boolean matches = node.matches("my_module.test"); // true

Default Implementation (YamlPermissionManager)

The API now includes a production-ready YAML-based implementation of PermissionManager:

import fr.orion.api.permission.impl.YamlPermissionManager;

// Create the permission manager
Path dataDir = Paths.get("data");
PermissionManager permissionManager = new YamlPermissionManager(dataDir);

// Add permissions to users
permissionManager.addUserPermission("123456789", "moderation.kick");
permissionManager.addUserPermission("123456789", "moderation.ban");

// Add permissions to roles
permissionManager.addRolePermission("987654321", "music.*");

// Batch operations for better performance
YamlPermissionManager yamlPM = (YamlPermissionManager) permissionManager;
yamlPM.addUserPermissions("123456789", List.of(
    "economy.balance",
    "economy.transfer",
    "economy.shop"
));

// Check permissions
if (permissionManager.hasPermission(member, "moderation.kick")) {
    // User has permission through direct user permission or role
}

// Get all effective permissions
Set<String> allPerms = permissionManager.getEffectivePermissions(member);

Storage format (permissions.yml):

users:
  "123456789":
    - "moderation.kick"
    - "moderation.ban"
roles:
  "987654321":
    - "music.*"
    - "economy.balance"

📚 API Reference

Core Interfaces

Bot Interface

public interface Bot {
    CommandRegistry getCommandRegistry();
    EventRegistry getEventRegistry();
    JDA getJDA();
    ModuleManager getModuleManager();
    PermissionManager getPermissionManager();
}

Module Interface

public interface Module {
    void onEnable();
    void onDisable();
    boolean isEnabled();
    ModuleConfig getConfig();
    boolean hasPermission(Member member, String permission);
}

PermissionManager Interface

public interface PermissionManager {
    boolean hasPermission(Member member, String permission);
    void addUserPermission(String userId, String permission);
    void addRolePermission(String roleId, String permission);
    Set<String> getEffectivePermissions(Member member);
}

Utility Classes

EmbedTemplate

// Success message
EmbedTemplate.success("Title", "Description").build()

// Error message
EmbedTemplate.error("Title", "Description").build()

// Info message
EmbedTemplate.info("Title", "Description").build()

// Warning message
EmbedTemplate.warning("Title", "Description").build()

ConfirmationSystem

ConfirmationSystem.ConfirmationMessage confirmation = ConfirmationSystem.createConfirmation(
    "Are you sure?",
    confirmEvent -> { /* Handle confirm */ },
    cancelEvent -> { /* Handle cancel */ }
);

event.replyEmbeds(confirmation.embed())
     .addActionRow(confirmation.confirmButton(), confirmation.cancelButton())
     .queue();

💡 Examples

Example 1: Simple Command Module

public class GreetingModule extends AbstractModule {
    
    @Override
    public void onEnable() {
        registerCommand(new GreetingCommand(this));
    }
    
    @Override
    public void onDisable() {
        // Cleanup if needed
    }
}

public class GreetingCommand extends ParentCommand {
    private final GreetingModule module;
    
    public GreetingCommand(GreetingModule module) {
        this.module = module;
        
        registerSubcommand("hello", "Say hello", null, new SubcommandHandler() {
            @Override
            public void execute(SlashCommandInteractionEvent event) {
                if (!module.hasPermission(event.getMember(), "greet")) {
                    event.reply("❌ No permission").setEphemeral(true).queue();
                    return;
                }
                
                event.reply("👋 Hello, " + event.getUser().getAsMention() + "!").queue();
            }
            
            @Override
            public SubcommandData getSubcommandData() {
                return new SubcommandData("hello", "Say hello");
            }
        });
    }
    
    @Override
    public String getName() { return "greeting"; }
    
    @Override
    public String getDescription() { return "Greeting commands"; }
}

Example 2: Event Listener Module

public class WelcomeModule extends AbstractModule {
    
    @Override
    public void onEnable() {
        registerListener(new WelcomeListener(this));
    }
    
    @Override
    public void onDisable() {
        // Auto cleanup
    }
}

public class WelcomeListener extends ListenerAdapter {
    private final WelcomeModule module;
    
    public WelcomeListener(WelcomeModule module) {
        this.module = module;
    }
    
    @Override
    public void onGuildMemberJoin(GuildMemberJoinEvent event) {
        TextChannel welcomeChannel = event.getGuild().getTextChannelById("CHANNEL_ID");
        if (welcomeChannel != null) {
            welcomeChannel.sendMessage("Welcome " + event.getMember().getAsMention() + "!").queue();
        }
    }
}

Example 3: Configuration Usage

public class ConfigTestModule extends YamlModuleConfig {

    public ConfigTestModule(Path rootPath) {
        super(rootPath, "config");
    }
    
    @Override
    protected void ensureDefaultValues() {
        if (!this.contains("welcomeMessage")) {
            this.set("welcomeMessage", "");
        }
    }

    public String getWelcomeMessage() {
        return this.getString("welcomeMessage");
    }
}

public class TestModule extends AbstractModule {
    @Override
    protected ModuleConfig createConfig(Path dataDirectory) {
        return new ConfigTestModule(dataDirectory);
    }

    @Override
    public ConfigTestModule getConfig() {
        return (ConfigTestModule) super.getConfig();
    }
}

🏭 Implementations

Orion-API is a pure interface library. To use it, you need an implementation:

Official Implementation

Orion-Core - The official implementation providing:

Complete bot implementation with all API contracts
YAML-based permission storage
Module hot-reloading system
Built-in management commands
File-based configuration system

repositories {
    mavenCentral()
    maven { url 'https://jitpack.io' }
}

dependencies {
    implementation("com.github.Arinonia:orion-api:v0.1.0-beta")
    implementation("net.dv8tion:JDA:5.5.1")
    implementation("org.yaml:snakeyaml:2.4")
    implementation("ch.qos.logback:logback-classic:1.5.13")
}

Creating Your Own Implementation

You can implement the API contracts yourself:

public class MyBot implements Bot {
    private final JDA jda;
    private final CommandRegistry commandRegistry;
    private final PermissionManager permissionManager;
    // ... other components
    
    @Override
    public CommandRegistry getCommandRegistry() {
        return commandRegistry;
    }
    
    @Override
    public PermissionManager getPermissionManager() {
        return permissionManager;
    }
    
    // ... implement other methods
}

🛠️ Usage with Implementation

Custom Implementation

public class Main {
    public static void main(String[] args) {
        OrionBot orionBot = new OrionBot("TOKEN", "GUILD_ID");
        orionBot.start();
    }
}

public class OrionBot implements Bot {
    private static final Logger log = LoggerFactory.getLogger(OrionBot.class);

    private final String token;
    private final String guildId;

    private JDA jda;
    private ModuleManager moduleManager;
    private CommandRegistry commandRegistry;
    private EventRegistry eventRegistry;
    private PermissionManager permissionManager;

    public OrionBot(String token, String guildId) {
        log.info("Initializing OrionBot... v0.0.1");
        this.token = token;
        this.guildId = guildId;
    }

    public void start() {
        log.info("Starting OrionBot...");

        initializeJDA();
        initializeRegistries();
        loadModules();
        registerCommands();
        logBotStatistics();

        log.info("OrionBot started successfully");
    }

    private void initializeJDA() {
        log.info("Initializing JDA...");

        try {
            JDABuilder builder = JDABuilder.createDefault(token)
                    .enableIntents(EnumSet.of(
                            GatewayIntent.GUILD_MESSAGES,
                            GatewayIntent.GUILD_MEMBERS,
                            GatewayIntent.MESSAGE_CONTENT,
                            GatewayIntent.GUILD_VOICE_STATES,
                            GatewayIntent.GUILD_MESSAGE_REACTIONS
                    ));
            this.jda = builder.build().awaitReady();
            log.info("JDA initialized successfully");
        } catch (Exception e) {
            log.error("Failed to initialize JDA", e);
            throw new RuntimeException("Failed to initialize JDA", e);
        }
    }

    private void initializeRegistries() {
        log.info("Initializing registries...");

        this.eventRegistry = new SimpleEventRegistry(this.jda);
        this.commandRegistry = new SimpleCommandRegistry(this.jda, this.guildId);

        this.eventRegistry.registerListener((EventListener) this.commandRegistry);
        this.eventRegistry.registerListener(new ConfirmationSystem());

        this.permissionManager = new YamlPermissionManager(Path.of("permissions"));
        Path modulePath = Path.of("modules");
        this.moduleManager = new DefaultModuleLoader(modulePath, this);

    }

    private void loadModules() {
        log.info("Loading modules...");

        int loadedModules = this.moduleManager.loadModules();
        int enabledModules = this.moduleManager.enableModules();
        log.info("Loaded {} modules, enabled {} modules", loadedModules, enabledModules);
    }

    private void registerCommands() {
        log.info("Registering commands...");
        //add your built-in commands here
        //this.commandRegistry.registerCommand(new PermissionCommand(this.permissionManager));
        //this.commandRegistry.registerCommand(new ModulesCommand(this.moduleManager, this.permissionManager));
        this.commandRegistry.synchronizeCommands();
        log.info("Commands registered successfully");
    }

    private void logBotStatistics() {
        log.info("=== Orion Bot Statistics ===");
        log.info("Guild ID: {}", this.guildId != null ? this.guildId : "Not specified (using global commands)");
        log.info("Modules: {} ({} enabled)",
                this.moduleManager.getModules().size(),
                this.moduleManager.getEnabledModules().size());
        log.info("Commands: {} registered", this.commandRegistry.getCommands().size());
        log.info("Permissions: {} users, {} roles",
                this.permissionManager.getAllUsersWithPermissions().size(),
                this.permissionManager.getAllRolesWithPermissions().size());
        log.info("============================");

        for (Module module : this.moduleManager.getModules()) {
            String status = module.isEnabled() ? "ENABLED" : "DISABLED";
            if (module.getModuleDescriptor() != null) {
                log.debug("Module: {} [{}] - {}",
                        module.getModuleDescriptor().name(),
                        status,
                        module.getModuleDescriptor().description());
            } else {
                log.debug("Module: {} [{}] - No descriptor available",
                        module.getClass().getSimpleName(),
                        status);
            }
        }
    }

    private void shutdown() {
        log.info("Shutting down OrionBot...");

        if (this.moduleManager != null) {
            this.moduleManager.disableModules();
        }

        if (this.jda != null) {
            this.jda.shutdown();
            log.info("JDA shutdown complete");
        }
        log.info("OrionBot shutdown completed successfully");
    }

    @Override
    public CommandRegistry getCommandRegistry() {
        return this.commandRegistry;
    }

    @Override
    public EventRegistry getEventRegistry() {
        return this.eventRegistry;
    }

    @Override
    public JDA getJDA() {
        return this.jda;
    }

    @Override
    public ModuleManager getModuleManager() {
        return this.moduleManager;
    }

    @Override
    public PermissionManager getPermissionManager() {
        return this.permissionManager;
    }
}

🤝 Contributing

Development Setup

Fork the repository

Clone your fork:

git clone https://github.com/Arinonia/Orion-API.git

Create a feature branch:
```
git checkout -b feature/new-interface
```
Make changes and test
Commit your changes:
```
git commit -m "Add new interface for X"
```
Push to your fork:
```
git push origin feature/new-interface
```
Create a Pull Request

API Design Guidelines

When contributing to the API:

Keep interfaces focused: Single responsibility principle
Avoid implementation details: Pure contracts only
Use generics wisely: Type safety without complexity
Consider extensibility: Will future implementations need flexibility?
Backward compatibility: Don't break existing contracts

Code Style

Use Java 17 features in interfaces where appropriate
Follow standard Java naming conventions
Use meaningful parameter and return type names
Keep method signatures simple and intuitive

Testing

# Compile API
./gradlew build

# Check JavaDoc generation
./gradlew javadoc

# Run any interface validation tests
./gradlew test

API Evolution

When proposing API changes:

Discuss first: Open an issue to discuss major changes
Deprecation path: Provide clear migration for breaking changes
Version appropriately: Follow semantic versioning
Document changes: Update README and JavaDoc

📈 Roadmap

API Enhancements

Event System: More granular event interfaces
Configuration: Advanced configuration validation interfaces
Metrics: Built-in metrics and monitoring interfaces
Security: Enhanced permission system interfaces

Ecosystem

Plugin Marketplace: Standard interfaces for plugin distribution
IDE Integration: Better development tools and templates
Documentation: Interactive API documentation
Testing Framework: Standard testing utilities for modules

Community

Community Modules: Showcase popular community modules
Examples Repository: More comprehensive examples
Best Practices: Guidelines for API usage
Migration Tools: Tools for upgrading between API versions

📝 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

JDA - Java Discord API that this builds upon
SnakeYAML - Referenced for configuration interfaces
SLF4J - Logging interfaces

📞 Support

API Documentation: Check JavaDoc and this README
Issues: GitHub Issues
Discussions: GitHub Discussions
Implementation Support: See Orion-Core for implementation-specific help TODO

🔗 Related Projects

Orion-Core - Official implementation TODO
Orion-Examples - Example modules and usage TODO
Orion-Templates - Project templates for quick start TODO

Orion-API: Clean interfaces for Discord bot development ✨

FilesExpand file tree

README.md

Latest commit

History

README.md

File metadata and controls

Orion Discord Bot API

🚀 Features

🔧 Core API Framework

🛠️ Developer Experience

📋 Table of Contents

🏗️ Architecture

Design Principles

📦 Installation

Gradle

Maven

🧩 Core Concepts

Bot Interface

Module System

Permission System

📦 Module Development

Creating a Module

Module Descriptor

Commands with Permissions

Event Listeners

🔒 Permission System

Permission Structure

Permission Interfaces

Using Permissions in Modules

Permission Node Utility

Default Implementation (YamlPermissionManager)

📚 API Reference

Core Interfaces

Bot Interface

Module Interface

PermissionManager Interface

Utility Classes

EmbedTemplate

ConfirmationSystem

💡 Examples

Example 1: Simple Command Module

Example 2: Event Listener Module

Example 3: Configuration Usage

🏭 Implementations

Official Implementation

Creating Your Own Implementation

🛠️ Usage with Implementation

Custom Implementation

🤝 Contributing

Development Setup

API Design Guidelines

Code Style

Testing

API Evolution

📈 Roadmap

API Enhancements

Ecosystem

Community

📝 License

🙏 Acknowledgments

📞 Support

🔗 Related Projects