# karthiksambhur/customitem architecture

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

- Interactive diagram: https://gitdiagram.com/karthiksambhur/customitem
- Repository: https://github.com/karthiksambhur/customitem

## Overview

##### Project Type and Purpose
- Project Type: A Minecraft server plugin (Bukkit/Spigot plugin).
- Purpose: On player join, grant configurable custom items to the player; on item right‐click, execute configured commands. Configuration is driven by a YAML file (`config.yml`).

##### Key Architectural Patterns
- Event‐Driven Architecture (observer pattern): Listeners respond to server events (player join, item interaction).
- Command Pattern: Separate classes handle plugin commands and subcommands.
- Configuration‐Driven Behavior: `config.yml` drives item definitions.

##### Main Components
A. Minecraft Server (Bukkit/Spigot)
– Plugin Loader / Lifecycle (onEnable/onDisable)
– Event Dispatcher
– Command Registry

B. Plugin Core
1. Main Plugin Class (`CustomItem.java`)
- Reads `config.yml` on startup
- Registers Listeners & Commands
2. Configuration Module
- `config.yml` (defines world settings + up to 9 items)
- YAML parser (built‐in Bukkit API)
3. Command Module
- `CustomItemCommand` (entry point)
- Subcommands (`giveCommand`, `giveallCommand`, `helpCommand`, `reloadCommand`, `sendCommand`)
- Tab completion (`TabCompletion.java`)
4. Event Listeners
- `PlayerJoinListener` – upon join, uses `ItemGenerator` to give items
- `RightClickListener` – intercepts item right‐click events, executes configured command
5. Utility Module
- `ItemGenerator` – builds `ItemStack` objects per config
- `TabCompletion` – provides player tab‐complete hints

C. External Dependencies
- PlaceholderAPI – allows placeholders in commands or item names

##### Relationships & Data Flow
1. Server starts → PluginLoader calls `onEnable()` in `CustomItem.java`.
2. `CustomItem.java` reads `config.yml` and populates internal data structures.
3. `CustomItem.java` registers:
– Event Listeners with Server Event Dispatcher
– Command executors & tab completers with Command Registry
4. PlayerJoin Event → `PlayerJoinListener` invokes `ItemGenerator` → grants items to player inventory
5. Player Right‐Click Event → `RightClickListener` reads which item was clicked → executes the associated command (via server dispatcher)
6. User enters `/customitem` commands → `CustomItemCommand` routes to appropriate subcommand class → performs action (e.g., give, reload)

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "Minecraft Server"
        direction TB
        PluginLoader["Plugin Loader / Lifecycle"]:::serverComp
        EventDispatcher["Event Dispatcher"]:::serverComp
        CommandRegistry["Command Registry"]:::serverComp
        subgraph "CustomItem Plugin"
            direction TB
            subgraph "Core Module"
                MainClass["CustomItem.java"]:::pluginComp
            end
            subgraph "Config Module"
                ConfigYml["config.yml"]:::config
                PluginYml["plugin.yml"]:::config
            end
            subgraph "Command Module"
                CICmd["CustomItemCommand"]:::pluginComp
                giveCmd["giveCommand"]:::pluginComp
                giveallCmd["giveallCommand"]:::pluginComp
                helpCmd["helpCommand"]:::pluginComp
                reloadCmd["reloadCommand"]:::pluginComp
                sendCmd["sendCommand"]:::pluginComp
                TabComp["TabCompletion.java"]:::pluginComp
            end
            subgraph "Event Listeners"
                pjListener["PlayerJoinListener"]:::pluginComp
                rcListener["RightClickListener"]:::pluginComp
            end
            subgraph "Utilities"
                itemGen["ItemGenerator"]:::pluginComp
            end
        end
    end
    PlaceholderAPI["PlaceholderAPI"]:::external

    PluginLoader -->|"onEnable()"| MainClass
    MainClass -->|"read config"| ConfigYml
    MainClass -->|"load plugin descriptor"| PluginYml
    MainClass -->|"register listeners"| EventDispatcher
    MainClass -->|"register commands"| CommandRegistry

    EventDispatcher -->|"PlayerJoinEvent"| pjListener
    EventDispatcher -->|"RightClickEvent"| rcListener

    pjListener -->|"invoke"| itemGen
    rcListener -->|"execute command"| CommandRegistry

    CommandRegistry -->|"execute command entry"| CICmd
    CICmd -->|"delegate to"| giveCmd
    CICmd -->|"delegate to"| giveallCmd
    CICmd -->|"delegate to"| helpCmd
    CICmd -->|"delegate to"| reloadCmd
    CICmd -->|"delegate to"| sendCmd
    CommandRegistry -->|"tab complete"| TabComp

    itemGen -->|"reads definitions"| ConfigYml
    PlaceholderAPI -->|"provides placeholders"| ConfigYml

    click MainClass "https://github.com/karthiksambhur/customitem/blob/master/src/main/java/ga/pixelplayz/customitem/CustomItem.java"
    click ConfigYml "https://github.com/karthiksambhur/customitem/blob/master/src/main/resources/config.yml"
    click PluginYml "https://github.com/karthiksambhur/customitem/blob/master/src/main/resources/plugin.yml"
    click CICmd "https://github.com/karthiksambhur/customitem/blob/master/src/main/java/ga/pixelplayz/customitem/commands/CustomItemCommand.java"
    click giveCmd "https://github.com/karthiksambhur/customitem/blob/master/src/main/java/ga/pixelplayz/customitem/commands/subcommands/giveCommand.java"
    click giveallCmd "https://github.com/karthiksambhur/customitem/blob/master/src/main/java/ga/pixelplayz/customitem/commands/subcommands/giveallCommand.java"
    click helpCmd "https://github.com/karthiksambhur/customitem/blob/master/src/main/java/ga/pixelplayz/customitem/commands/subcommands/helpCommand.java"
    click reloadCmd "https://github.com/karthiksambhur/customitem/blob/master/src/main/java/ga/pixelplayz/customitem/commands/subcommands/reloadCommand.java"
    click sendCmd "https://github.com/karthiksambhur/customitem/blob/master/src/main/java/ga/pixelplayz/customitem/commands/subcommands/sendCommand.java"
    click pjListener "https://github.com/karthiksambhur/customitem/blob/master/src/main/java/ga/pixelplayz/customitem/listeners/PlayerJoinListener.java"
    click rcListener "https://github.com/karthiksambhur/customitem/blob/master/src/main/java/ga/pixelplayz/customitem/listeners/RightClickListener.java"
    click itemGen "https://github.com/karthiksambhur/customitem/blob/master/src/main/java/ga/pixelplayz/customitem/miscellaneous/ItemGenerator.java"
    click TabComp "https://github.com/karthiksambhur/customitem/blob/master/src/main/java/ga/pixelplayz/customitem/miscellaneous/TabCompletion.java"

    classDef pluginComp fill:#bbdefb,stroke:#1e88e5
    classDef serverComp fill:#c8e6c9,stroke:#388e3c
    classDef external fill:#c8e6c9,stroke:#2e7d32,stroke-dasharray: 5 5
    classDef config fill:#fff9c4,stroke:#fbc02d
```
