# th3al3x/uessentials architecture

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

- Interactive diagram: https://gitdiagram.com/th3al3x/uessentials
- Repository: https://github.com/th3al3x/uessentials

## Overview

##### Main Components
- External Integration:
– Unturned Server and RocketMod: Since the plugin is deployed inside the Rocket folder and interfaces with the Unturned server API, indicate that the hosting environment is the Unturned server with RocketMod.
- Plugin Initialization & Loader:
– EssCore and the Main Plugin Class: Represent the entry point where the plugin is loaded, initializing other components.
- API Layer:
– Command API: Include interfaces (ICommand, ICommandArgs, ICommandManager) and supporting classes from the “src/Api/Command” directory. This layer abstracts command handling and provides extension points.
– Event API: Show the event interfaces (IEventManager, ICancellable) and event classes (e.g., CommandEvent) that underpin the custom events triggered in the plugin.
– Module API: Display the module abstraction (EssModule, ModuleInfo, ModuleManager) that supports the modular plugin system.
– Others: Include Permission and Task APIs, as well as the Unturned-specific API (UPlayer, UServer, etc.).
- Core Logic & Services:
– Command Manager (from “src/Core/Command”) that adapts API commands to implementation.
– Event Manager (from “src/Core/Event”) to route and manage events.
– Storage and Configuration managers (from “src/Core/Storage” and “src/Configuration”).
– Updater Component: Represent the GitHubUpdater service from “src/Updater,” showing how update checks are performed.
– Logging: Show how logging is handled (e.g., ConsoleLogger in “src/Logging”).
- Modules and Native Modules:
- Compatibility/Integration Components:
– Compatibility hooks and the HookManager (located in “src/Compatibility”) helping the plugin interface with other modules/plugins such as Uconomy or AviEconomy.
- Common Utilities:
– Utility libraries (from “src/Common/Util”) and helper classes that are used across different components.

##### Relationships and Data Flow
– The Unturned Server (with RocketMod) calls the plugin’s initialization (EssCore), which in turn initializes the API layer.
– The API layer (commands, events, modules, configuration) communicates with the Core layer to process commands.
– The Command Manager receives input (from players via text commands logged by the Unturned/Rocket environment) and relays it to the proper command handlers.
– Module components (Kit/Warp) register their commands and subscribe to events via ModuleManager and EventManager, with data flowing both ways.
– The Updater periodically checks GitHub for updates, potentially updating the Core or triggering events.
– API interfaces → Core implementations (commands, events, task execution).
– Core → Module system (delegation of command execution to the specific module, e.g., for warps or kits).

##### Architectural Patterns & Design Principles
- Modularity: The separation between the API layer, Core logic, and Native Modules highlights a clear modular architecture.
- Event-Driven: The use of command events and a centralized EventManager reveals an event-driven design.
- Command Pattern: The command classes and interfaces make use of the Command pattern to encapsulate executable operations.
- Dependency Separation: Clear layering helps isolate configuration, logging, and compatibility concerns from the business logic.

##### Technologies and Libraries
- .NET/C# is used as the primary language, as indicated by the csproj and solution files.
- NuGet packages such as Newtonsoft.Json and RocketModFix libraries are central to JSON handling and integration with the Rocket API.
- The plugin’s integration into the Rocket environment emphasizes its reliance on the specific APIs (Rocket.API, Rocket.Core, etc.).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Integration
    ext["Unturned Server & RocketMod Integration"]:::external

    %% Plugin Initialization & Loader
    corePlugin["EssCore (Plugin Loader)"]:::plugin

    %% API Layer Subgraph
    subgraph "API Layer"
        cmdApi["Command API"]:::api
        evtApi["Event API"]:::api
        confApi["Configuration API"]:::api
        modApi["Module API"]:::api
        permTaskApi["Permission & Task APIs"]:::api
        unturnedApi["Unturned API"]:::api
    end

    %% Core Logic Subgraph
    subgraph "Core Logic"
        cmdMgr["Command Manager"]:::core
        evtMgr["Event Manager"]:::core
        storageMgr["Storage Manager"]:::core
        configMgr["Configuration Manager"]:::core
        updater["Updater Component"]:::core
        log["Logging"]:::core
    end

    %% Modules Subgraph
    subgraph "Modules"
        kitMod["Kit Module"]:::module
        warpMod["Warp Module"]:::module
    end

    %% Compatibility/Integration Components
    subgraph "Integration"
        hookMgr["Hook Manager"]:::integration
    end

    %% Common Utilities
    subgraph "Utilities"
        util["Common Utilities"]:::utility
    end

    %% Relationships
    ext --> corePlugin
    corePlugin --> cmdApi
    corePlugin --> evtApi
    corePlugin --> confApi
    corePlugin --> modApi
    corePlugin --> permTaskApi
    corePlugin --> unturnedApi

    %% API Layer to Core Logic
    cmdApi -->|"implements"| cmdMgr
    evtApi -->|"routesTo"| evtMgr
    confApi -->|"loadsSaves"| configMgr
    modApi -->|"registersModules"| cmdMgr
    modApi -->|"subscribesEvents"| evtMgr
    permTaskApi -->|"supportsCommands"| cmdMgr
    unturnedApi -->|"integratesWith"| corePlugin

    %% External input from Unturned Server
    ext -->|"commandInput"| cmdMgr

    %% Updater triggers events
    updater -->|"triggersUpdate"| evtMgr

    %% Modules registering with Core
    kitMod -->|"registersCommands"| cmdMgr
    kitMod -->|"subscribesEvents"| evtMgr
    warpMod -->|"registersCommands"| cmdMgr
    warpMod -->|"subscribesEvents"| evtMgr

    %% Compatibility hook integration
    hookMgr -->|"integrationHook"| modApi

    %% Common utilities used by various components
    cmdApi -.-> util
    evtApi -.-> util
    confApi -.-> util
    modApi -.-> util
    permTaskApi -.-> util
    unturnedApi -.-> util
    cmdMgr -.-> util
    evtMgr -.-> util
    kitMod -.-> util
    warpMod -.-> util

    %% Click Events
    click ext "https://github.com/th3al3x/uessentials/tree/dev/packages"
    click corePlugin "https://github.com/th3al3x/uessentials/blob/dev/src/Core/EssCore.cs"
    click cmdApi "https://github.com/th3al3x/uessentials/tree/dev/src/Api/Command"
    click evtApi "https://github.com/th3al3x/uessentials/tree/dev/src/Api/Event"
    click confApi "https://github.com/th3al3x/uessentials/tree/dev/src/Api/Configuration"
    click modApi "https://github.com/th3al3x/uessentials/tree/dev/src/Api/Module"
    click permTaskApi "https://github.com/th3al3x/uessentials/tree/dev/src/Api/Permission"
    click unturnedApi "https://github.com/th3al3x/uessentials/tree/dev/src/Api/Unturned"
    click cmdMgr "https://github.com/th3al3x/uessentials/blob/dev/src/Core/Command/CommandManager.cs"
    click evtMgr "https://github.com/th3al3x/uessentials/blob/dev/src/Core/Event/EventManager.cs"
    click storageMgr "https://github.com/th3al3x/uessentials/tree/dev/src/Core/Storage"
    click configMgr "https://github.com/th3al3x/uessentials/tree/dev/src/Configuration"
    click updater "https://github.com/th3al3x/uessentials/blob/dev/src/Updater/GithubUpdater.cs"
    click log "https://github.com/th3al3x/uessentials/blob/dev/src/Logging/ConsoleLogger.cs"
    click kitMod "https://github.com/th3al3x/uessentials/tree/dev/src/NativeModules/Kit"
    click warpMod "https://github.com/th3al3x/uessentials/tree/dev/src/NativeModules/Warp"
    click hookMgr "https://github.com/th3al3x/uessentials/blob/dev/src/Compatibility/HookManager.cs"
    click util "https://github.com/th3al3x/uessentials/tree/dev/src/Common/Util"

    %% Styles
    classDef external fill:#ffcccc,stroke:#cc0000,stroke-width:2px;
    classDef plugin fill:#ffffcc,stroke:#999900,stroke-width:2px;
    classDef api fill:#ccffcc,stroke:#339933,stroke-width:2px;
    classDef core fill:#cce5ff,stroke:#0066cc,stroke-width:2px;
    classDef module fill:#e6ccff,stroke:#9933cc,stroke-width:2px;
    classDef integration fill:#ffebcc,stroke:#ff9900,stroke-width:2px;
    classDef utility fill:#f2f2f2,stroke:#999999,stroke-width:2px;
```
