# essentialsx/essentials architecture

> Architecture diagram of the GitHub repository essentialsx/essentials, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-02-26). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/essentialsx/essentials
- Repository: https://github.com/essentialsx/essentials

## Overview

##### Main Components
- Core Plugin Module (Essentials): Contains the main classes (e.g., Essentials.java), event listeners (player, block, command, plugin events), configuration management, messaging, utility classes, and API interfaces.
- Sub‑Modules: Separate directories hold additional features like EssentialsAntiBuild, EssentialsChat, EssentialsDiscord, EssentialsDiscordLink, EssentialsGeoIP, EssentialsProtect, EssentialsSpawn, and EssentialsXMPP. Each sub‑module adds a specific aspect (e.g., chat processing for EssentialsChat or external Discord integrations for EssentialsDiscord).
- Providers: A set of modules (e.g., providers/1_12Provider, providers/1_8Provider, BaseProviders, NMSReflectionProvider, and PaperProvider) that abstract server or Minecraft version differences. These ensure that the core functionality can work across multiple Minecraft versions by encapsulating version‑specific implementations.
- Build & Infrastructure: Gradle build scripts (build.gradle, build-logic, settings.gradle.kts) coordinate project compilation, tests, and distribution. Configuration files like plugin.yml in resources provide metadata for the server plugin lifecycle.
- External Dependencies & Integrations:
– Integration with third‑party plugins (e.g., Vault for permissions, LuckPerms recommended for groups),
– The EssentialsX API for plugin integration with other plugins,
– External messaging and Discord bots (integrated within the EssentialsDiscord and EssentialsDiscordLink modules).

##### Relationships and Interactions
- The Core Module (Essentials) acts as the orchestrator. It loads configuration files, sets up event listeners, and exposes its API (with defined interfaces such as IEssentials, IUser, and ITeleport).
- Each Sub‑Module plugs into the core:
– They register their own command sets, event listeners, and features.
– They depend on shared libraries (utilities, config classes, common event frameworks) in the core.
- The Providers act as abstraction layers between the core (and sub‑modules) and the underlying server implementations (e.g., differences between various Minecraft versions).
- Build scripts and Gradle tasks coordinate compiling each module, testing them, and then packaging them into JARs.
- The README and Maven coordinates indicate integration points for external dependency management (Vault, LuckPerms, etc.).

##### Important Architectural Patterns and Design Principles
- Modularity: Clear separation between the core functionality and additional modules based on features.
- Abstraction via Provider Pattern: The provider modules abstract underlying implementations for different server versions.
- Event‑Driven Architecture: Extensive use of event listeners for in‑game events (player actions, chat events, Discord events) to decouple modules.
- API Exposure: Public interfaces (in the “api” directories) to allow third‑party integration and extension.
- Separation of Concerns: Different packages and modules are responsible for specific areas such as economy, chat, commands, configuration, and external integrations.

##### Technologies, Frameworks, and Tools
- Programming Language: Java (targeting Java 8 or later)
- Build Tool: Gradle (with Kotlin DSL in build-logic)
- Server Platforms: CraftBukkit, Spigot, and Paper
- External Integrations: Vault for economy and permissions, Discord (through JDA or similar libraries), and compatibility with third‑party API integrations.
- Testing: JUnit based tests in the “src/test” directories.

## Diagram (Mermaid)

```mermaid
flowchart TD
    A("Essentials Core Module"):::core
    subgraph "Sub Modules"
        B("EssentialsAntiBuild"):::sub
        C("EssentialsChat"):::sub
        D("EssentialsDiscord"):::sub
        E("EssentialsDiscordLink"):::sub
        F("EssentialsGeoIP"):::sub
        G("EssentialsProtect"):::sub
        H("EssentialsSpawn"):::sub
        I("EssentialsXMPP"):::sub
    end
    J("Provider Modules"):::provider
    K("Build & Infrastructure"):::build
    L("Vault Economy Integration"):::external
    M("LuckPerms Integration"):::external
    N("Discord API Integration"):::external

    L -->|"dependency"| A
    M -->|"dependency"| A
    A -->|"exposesAPI"| B
    A -->|"exposesAPI"| C
    A -->|"exposesAPI"| D
    A -->|"exposesAPI"| E
    A -->|"exposesAPI"| F
    A -->|"exposesAPI"| G
    A -->|"exposesAPI"| H
    A -->|"exposesAPI"| I
    A -->|"abstracts"| J
    K -->|"builds"| A
    K -->|"builds"| J
    N -->|"calls"| D
    N -->|"calls"| E

    click A "https://github.com/essentialsx/essentials/blob/2.x/Essentials/src/main/java/com/earth2me/essentials/Essentials.java"
    click B "https://github.com/essentialsx/essentials/tree/2.x/EssentialsAntiBuild/"
    click C "https://github.com/essentialsx/essentials/tree/2.x/EssentialsChat/"
    click D "https://github.com/essentialsx/essentials/tree/2.x/EssentialsDiscord/"
    click E "https://github.com/essentialsx/essentials/tree/2.x/EssentialsDiscordLink/"
    click F "https://github.com/essentialsx/essentials/tree/2.x/EssentialsGeoIP/"
    click G "https://github.com/essentialsx/essentials/tree/2.x/EssentialsProtect/"
    click H "https://github.com/essentialsx/essentials/tree/2.x/EssentialsSpawn/"
    click I "https://github.com/essentialsx/essentials/tree/2.x/EssentialsXMPP/"
    click J "https://github.com/essentialsx/essentials/tree/2.x/providers/"
    click K "https://github.com/essentialsx/essentials/blob/2.x/build.gradle"
    click L "https://github.com/essentialsx/essentials/blob/2.x/Essentials/src/main/java/com/earth2me/essentials/economy/vault/VaultEconomyProvider.java"

    classDef core fill:#ffcccc,stroke:#cc0000,stroke-width:2px;
    classDef sub fill:#ccffcc,stroke:#009900,stroke-width:2px;
    classDef provider fill:#ccccff,stroke:#0000cc,stroke-width:2px;
    classDef build fill:#ffffcc,stroke:#cccc00,stroke-width:2px;
    classDef external fill:#ffe6cc,stroke:#ff6600,stroke-width:2px;
```
