# moo-ack-productions/mcprep architecture

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

- Interactive diagram: https://gitdiagram.com/moo-ack-productions/mcprep
- Repository: https://github.com/moo-ack-productions/mcprep

## Overview

##### Main Components
- Core Addon Module: The heart of the project is the “MCprep_addon” directory which contains the core functionality. This module is divided into several submodules for handling different features:
– Material Preparation (e.g., prep materials functions in materials/generate.py, prep.py, sync.py)
– Mesh Swapping (MCprep_addon/meshswap/…)
– Skin Swapper and UI (mcprep_ui.py and skin-related code)
– Spawner modules for mobs, blocks, and items (MCprep_addon/spawner, import_bridge, and wheels as a placeholder)
– Utility and helper functions (commonmcobj_parser.py, util.py, addon_updater.py)
- External Integration/Bridge: The “import_bridge” module integrates importing functions from external Minecraft world exporters like jmc2obj or Mineways.
- Resource and Localization: The “MCprep_resources” folder along with language files (.po and .pot) demonstrates internationalization efforts.
- Action Scripts: Located in “action-scripts,” these include build-patches, translation scripts, and debug tools for deployment/updating.
- Testing and CI: The presence of “test_files” along with GitHub workflows and scripts (e.g., run_tests.py, .github/workflows/run_tests.yaml) show that automated testing and continuous integration are managed separately.
- Documentation & Developer Support: The “docs” folder and READMEs (e.g., BlenderChanges.md, install_readme.txt) provide additional developer guidance.

##### Relationships and Interactions
- The Blender environment (via its Python API, bpy) calls the core addon (through __init__.py), which then delegates to specialized modules (materials, spawner, skin, etc.) based on user input.
- The MCprep Addon presents its UI in Blender, which then triggers backend operations like material preps, mesh swapping, or mob spawning. For example, UI events from mcprep_ui.py interact with the underlying logic in the materials and spawner modules.
- The “import_bridge” handles conversion or adaptation of external data (imported 3D world models) into the formats and operations expected by the addon.
- Action Scripts are used during build time to patch or update source code, run translations, and optimize resource integration. They interact with the source code but are not part of the runtime in Blender.
- Continuous integration (CI) workflows run tests in “test_files” to validate addon functionality.

##### Architectural Patterns and Design Principles
- Modularity: The code is separated into clear modules (materials, spawner, import_bridge, etc.), each encapsulating a part of the functionality.
- Separation of Concerns: UI, logic, and integration with external tools are separated, allowing independent updates to spawner logic or material optimization.
- Extensibility: The addon is built in a way that supports adding new asset types (skins, mobs, blocks, effects) through conventions (naming, file organization) and configurable parameters.
- Testability: The existence of a “test_files” directory and GitHub CI workflows indicates unit tests and integration tests to ensure stability.

##### Relevant Technologies, Frameworks, and Libraries
- Python Scripting in Blender, using the bpy module.
- Blender’s native UI and node-based material systems.
- External tools such as jmc2obj or Mineways for exporting Minecraft worlds.
- Localization via PO files for multiple languages.
- CI/CD technologies (GitHub Workflows) to run tests upon changes.
- Packaging via pyproject.toml and requirements.txt to manage dependencies.

##### Final Detailed Steps for the Principal Software Engineer
- Inside the core addon, separate out each major feature (materials, mesh swap, spawner, skin, import bridge) and clearly indicate how they’re interconnected.
- Role of “action-scripts” and “docs” as supporting components that facilitate building, testing, and maintaining the project.
- Incorporate any specific naming conventions (e.g., matching material names for meshswap) that illustrate how extensibility is handled.

## Diagram (Mermaid)

```mermaid
flowchart TD
    A["Blender Environment (UI & Python API)"]:::ui -->|"calls"| B["MCprep Addon Core"]:::core

    subgraph "MCprep Addon Core"
        B1["Material Preparation"]:::module
        B2["Mesh Swapping"]:::module
        B3["Skin Swapper & UI"]:::module
        B4["Spawner Modules"]:::module
        B5["Import Bridge"]:::module
        B6["Utility & Helper Functions"]:::module
    end

    B -->|"delegates to"| B1
    B -->|"delegates to"| B2
    B -->|"delegates to"| B3
    B -->|"delegates to"| B4
    B -->|"delegates to"| B5
    B -->|"calls"| B6

    subgraph "Material Preparation Details"
        C1["Materials (generate.py, prep.py, sync.py)"]:::submodule
        C2["Skin Module (skin.py)"]:::submodule
    end
    B1 -->|"contains"| C1
    B1 -->|"contains"| C2

    subgraph "Mesh Swapping Detail"
        D1["Mesh Swap (meshswap.py)"]:::submodule
    end
    B2 -->|"implemented in"| D1

    subgraph "Spawner Modules Detail"
        D2["Spawner Scripts (mobs.py, entities.py, item.py, spawn_util.py)"]:::submodule
    end
    B4 -->|"handles"| D2

    subgraph "Import Bridge Detail"
        D3["Bridge Components (bridge.py, connector_common.py, mineways_connector.py)"]:::submodule
    end
    B5 -->|"integrates"| D3

    subgraph "Utility Functions Detail"
        D4["Common Parser, Util, Updater (addon_updater.py, etc.)"]:::submodule
    end
    B6 -->|"provides"| D4

    E["Resource & Localization (PO/POT files)"]:::external
    F["Action Scripts & Build Tools"]:::external
    G["Testing & CI Pipeline"]:::external
    H["Documentation & Developer Support"]:::external

    B1 -->|"uses"| E
    B2 -->|"uses"| E
    B3 -->|"interacts with"| B1
    B3 -->|"interacts with"| B4

    A -->|"receives updates from"| F
    F -->|"patches/update"| B
    F -->|"triggers tests in"| G
    H -->|"guides"| B

    %% Click Events based on Component Mapping
    click B "https://github.com/moo-ack-productions/mcprep/tree/master/MCprep_addon"
    click C1 "https://github.com/moo-ack-productions/mcprep/tree/master/MCprep_addon/materials"
    click D1 "https://github.com/moo-ack-productions/mcprep/blob/master/MCprep_addon/spawner/meshswap.py"
    click B3 "https://github.com/moo-ack-productions/mcprep/blob/master/MCprep_addon/mcprep_ui.py"
    click C2 "https://github.com/moo-ack-productions/mcprep/blob/master/MCprep_addon/materials/skin.py"
    click D2 "https://github.com/moo-ack-productions/mcprep/tree/master/MCprep_addon/spawner"
    click D3 "https://github.com/moo-ack-productions/mcprep/tree/master/MCprep_addon/import_bridge"
    click D4 "https://github.com/moo-ack-productions/mcprep/blob/master/MCprep_addon/util.py"
    click E "https://github.com/moo-ack-productions/mcprep/tree/master/MCprep_addon/MCprep_resources"
    click F "https://github.com/moo-ack-productions/mcprep/tree/master/action-scripts"
    click G "https://github.com/moo-ack-productions/mcprep/tree/master/test_files"
    click H "https://github.com/moo-ack-productions/mcprep/tree/master/docs"

    %% Styles
    classDef ui fill:#f9c,stroke:#333,stroke-width:2px;
    classDef core fill:#cfc,stroke:#333,stroke-width:2px;
    classDef module fill:#fc9,stroke:#333,stroke-width:2px;
    classDef submodule fill:#9cf,stroke:#333,stroke-width:2px;
    classDef external fill:#ffc,stroke:#333,stroke-width:2px;
```
