# histeriamc/customies architecture

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

- Interactive diagram: https://gitdiagram.com/histeriamc/customies
- Repository: https://github.com/histeriamc/customies

## Overview

##### Project Type and Purpose
- This is a plugin for PocketMine-MP designed to enhance Minecraft servers running PocketMine by introducing custom blocks, items, and entities.
- The README highlights its purpose (extending game functionality) and provides community and contribution details, which confirms that the plugin integrates deeply with game logic.

##### Analyzing the File Structure
- Top-Level Files: Notice files like README.md, composer.json (for dependency management), LICENSE, and plugin.yml (a critical configuration file for PocketMine plugins).
- The src directory is divided into further subdirectories:
- “block” – Contains files that likely define the custom block behaviors, block properties, factories, and even traits for permutation logic.
- “item” – Houses the implementation of custom items along with a set of components (each representing individual aspects like durability, display names, etc.).
- “entity” – Contains the custom entity factory that creates or manages custom in-game entities.
- “task” – Holds asynchronous tasks, for example handling tasks like block registration.
- “util” – Contains utility classes (e.g., for NBT handling).
- These directories suggest a modular, component-based approach where each aspect (blocks, items, entities) is encapsulated in its own module with shared utility functions and asynchronous capabilities.

##### Key Components to Highlight
a. Core Plugin Module:
- Customies Base: Represented by the main classes Customies.php and CustomiesListener.php. These serve as the entry point for the plugin and manage event handling.

b. Block System:
- Permutations: Detail the permutation submodule which manages block state variations (e.g., Permutable, Permutation, and traits like RotatableTrait and TogglePermutationTrait).

c. Item System:
- Item Handling: Represent the “item” module that includes factories and various component implementations under the “item/component” directory.
- Components: Each component (e.g., ArmorComponent, DurabilityComponent, IconComponent) can be depicted as building blocks that form the complete item’s behavior.

d. Entity System:
- Custom Entity Creation: The “entity” module, although smaller, is critical. It shows how custom entities are instantiated and managed.

e. Asynchronous and Utility Operations:
- Task Handling: Use the “task” directory (e.g., AsyncRegisterBlocksTask) to illustrate how asynchronous work is offloaded.
- Utilities: The “util” directory (e.g., NBT class) supports data handling and conversions necessary for in-game object serialization.

##### Relationships and Interactions
- Factories in each domain (block, item, entity) should be depicted as the components responsible for instantiating objects, with interactions drawn from the main plugin class.
- The event listener (CustomiesListener.php) should be shown receiving events from PocketMine’s core, which then trigger interactions with block/item modification components.
- Additionally, utility classes (like NBT) should be connected to both item and block components, highlighting their role in data manipulation.

##### Architectural Patterns and Design Principles
- Component-Based Architecture: Each item component is independent and can be composed into a full item.
- Factory Pattern: Both block and item creation use factories (CustomiesBlockFactory, CustomiesItemFactory) that encapsulate the instantiation logic.
- Asynchronous Task Handling: The design uses asynchronous workers to handle tasks (suggesting a decoupled processing model).
- Modularity: The clear separation into directories for blocks, items, entities, tasks, and utilities suggests the design emphasizes modularity and separation of concerns.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Plugin Core Module
    subgraph "Plugin Core"
        CP["Customies.php (Entry Point)"]:::core
        CL["CustomiesListener.php (Event Listener)"]:::core
    end

    %% Block System Module
    subgraph "Block System"
        BF["CustomiesBlockFactory.php"]:::block
        BP["BlockPalette.php"]:::block
        PERM["Block Permutations"]:::block
    end

    %% Item System Module
    subgraph "Item System"
        IF["CustomiesItemFactory.php"]:::item
        IC["ItemComponents.php"]:::item
        ISC["Item Subcomponents"]:::item
    end

    %% Entity System Module
    subgraph "Entity System"
        EF["CustomiesEntityFactory.php"]:::entity
    end

    %% Asynchronous Task Module
    subgraph "Async Task Handler"
        AT["AsyncRegisterBlocksTask.php"]:::task
    end

    %% Utility Operations
    subgraph "Utility Operations"
        NBT["NBT.php"]:::util
    end

    %% Relationships
    CP -->|"registers"| BF
    CP -->|"registers"| IF
    CP -->|"orchestrates"| EF

    CL -->|"triggers"| BF
    CL -->|"triggers"| IF

    BF -->|"uses"| BP
    BF -->|"applies"| PERM

    IF -->|"composes"| IC
    IC -->|"integrates"| ISC

    AT -->|"updates (async)"| BP

    NBT -->|"supports"| BP
    NBT -->|"supports"| IC

    %% Styles
    classDef core fill:#AED6F1,stroke:#1B4F72,stroke-width:2px;
    classDef block fill:#D6EAF8,stroke:#2874A6,stroke-width:2px;
    classDef item fill:#D5F5E3,stroke:#27AE60,stroke-width:2px;
    classDef entity fill:#E8DAEF,stroke:#8E44AD,stroke-width:2px;
    classDef task fill:#F9E79F,stroke:#B7950B,stroke-width:2px;
    classDef util fill:#FCF3CF,stroke:#B7950B,stroke-width:2px;

    %% Click Events
    click CP "https://github.com/histeriamc/customies/blob/master/src/Customies.php"
    click CL "https://github.com/histeriamc/customies/blob/master/src/CustomiesListener.php"
    click BF "https://github.com/histeriamc/customies/blob/master/src/block/CustomiesBlockFactory.php"
    click BP "https://github.com/histeriamc/customies/blob/master/src/block/BlockPalette.php"
    click PERM "https://github.com/histeriamc/customies/tree/master/src/block/permutations"
    click IF "https://github.com/histeriamc/customies/blob/master/src/item/CustomiesItemFactory.php"
    click IC "https://github.com/histeriamc/customies/blob/master/src/item/ItemComponents.php"
    click ISC "https://github.com/histeriamc/customies/tree/master/src/item/component"
    click EF "https://github.com/histeriamc/customies/blob/master/src/entity/CustomiesEntityFactory.php"
    click AT "https://github.com/histeriamc/customies/blob/master/src/task/AsyncRegisterBlocksTask.php"
    click NBT "https://github.com/histeriamc/customies/blob/master/src/util/NBT.php"
```
