# zortax/minecraftinjectionapi architecture

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

- Interactive diagram: https://gitdiagram.com/zortax/minecraftinjectionapi
- Repository: https://github.com/zortax/minecraftinjectionapi

## Overview

##### Project type and purpose
- This is an open-source Java library (MinecraftInjectionAPI) that uses the Java Instrumentation API and MCP (Minecraft Coder Pack) deobfuscation mappings to allow runtime code injection into a running Minecraft VM.
- It provides two main capabilities:
- A Java Agent + Transformer framework driven by annotations (FunctionHook, Flags, InjectPosition).
- A reflection-wrapper module that downloads MCP mappings and exposes obfuscated Minecraft classes via human-readable MCP names.

##### File structure
- Top-level build and CI: `.travis.yml`, `build.sh`, `pom.xml`.
- src/main/java/de/zortax/injection/injector:
- RuntimeInjector.java – entry point for attaching the agent.
- McAgent.java – manages transformer registration.
- McClassTransformer.java – implements java.lang.instrument.ClassFileTransformer.
- FunctionHook, Flags, InjectPosition – annotation and flags controlling injection behavior.
- src/main/java/de/zortax/injection/mcp:
- McpManager.java – downloads and caches MCP deobfuscation mappings.
- WrappedClass.java / MinecraftInstance.java – reflection-based accessors.
- gen/WrapperClassBuilder.java + GenType.java – dynamic wrapper class generator.
- Resources: `META-INF/MANIFEST.MF` defines the agent manifest.
- src/test/java shows a usage example (MinecraftTransformer) that drives the API.

##### README for additional insights
- Describes how to attach at runtime (`RuntimeInjector.attachToVm`) and how to declare hooks via `@FunctionHook`.
- Explains the reflection wrapper usage (`McpManager.getWrappedClass(...)`).
- Notes integration points for Forge / deobfuscated environments.

##### Essential architectural elements to capture
- Agent lifecycle: attach → premain/agentmain → transformer registration
- Hook discovery: annotation scanning → transformer
- Bytecode modification flow into Minecraft classes
- Dynamic mapping download & wrapper generation
- Runtime reflective access paths

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% User Layer
    subgraph "User / Example Code"
        direction TB
        UserApp["MinecraftTransformer"]:::user
    end

    %% Core Injection API
    subgraph "Injection API" 
        direction TB
        RI["RuntimeInjector & Attach API"]:::injection
        subgraph "Java Agent (agent.jar)"
            direction TB
            Manifest["MANIFEST.MF"]:::doc
            MA["McAgent"]:::injection
            MCT["McClassTransformer"]:::injection
            subgraph "Annotations"
                direction TB
                FH["FunctionHook"]:::injection
                FLG["Flags"]:::injection
                IP["InjectPosition"]:::injection
            end
        end
    end

    %% Reflection Wrapper
    subgraph "Reflection Wrapper"
        direction TB
        MM["McpManager"]:::reflection
        subgraph "Wrapper Generator"
            direction TB
            WCB["WrapperClassBuilder"]:::reflection
            GT["GenType"]:::reflection
        end
        subgraph "Reflection Facade"
            direction TB
            WC["WrappedClass"]:::reflection
            MI["MinecraftInstance"]:::reflection
        end
    end

    %% External Systems
    subgraph "External Systems"
        direction TB
        JVM["Minecraft JVM"]:::external
        Repo["MCP Mapping Repository"]:::external
    end

    %% Build & CI
    subgraph "Build & CI"
        direction TB
        Travis[".travis.yml"]:::ci
        BuildSh["build.sh"]:::ci
        POM["pom.xml"]:::ci
    end

    %% Relationships - control flow
    UserApp -->|"calls attachToVm"| RI
    RI -->|"attach via Attach API"| MA
    MA -->|"registers transformer"| MCT
    Manifest -->|"defines premain/agentmain"| MA
    MCT -->|"transforms bytecode"| JVM
    UserApp -->|"uses wrappers"| WC

    %% Relationships - data flow
    MM -.->|"downloads mappings"| Repo
    MM -->|"feeds mappings"| WCB
    WCB -->|"generates wrappers"| WC

    %% Click Events
    click UserApp "https://github.com/zortax/minecraftinjectionapi/blob/master/src/test/java/de/zortax/injection/example/transformer/MinecraftTransformer.java"
    click RI "https://github.com/zortax/minecraftinjectionapi/blob/master/src/main/java/de/zortax/injection/injector/RuntimeInjector.java"
    click MA "https://github.com/zortax/minecraftinjectionapi/blob/master/src/main/java/de/zortax/injection/injector/McAgent.java"
    click MCT "https://github.com/zortax/minecraftinjectionapi/blob/master/src/main/java/de/zortax/injection/injector/McClassTransformer.java"
    click FH "https://github.com/zortax/minecraftinjectionapi/blob/master/src/main/java/de/zortax/injection/injector/FunctionHook.java"
    click FLG "https://github.com/zortax/minecraftinjectionapi/blob/master/src/main/java/de/zortax/injection/injector/Flags.java"
    click IP "https://github.com/zortax/minecraftinjectionapi/blob/master/src/main/java/de/zortax/injection/injector/InjectPosition.java"
    click MM "https://github.com/zortax/minecraftinjectionapi/blob/master/src/main/java/de/zortax/injection/mcp/McpManager.java"
    click WC "https://github.com/zortax/minecraftinjectionapi/blob/master/src/main/java/de/zortax/injection/mcp/WrappedClass.java"
    click MI "https://github.com/zortax/minecraftinjectionapi/blob/master/src/main/java/de/zortax/injection/mcp/MinecraftInstance.java"
    click WCB "https://github.com/zortax/minecraftinjectionapi/blob/master/src/main/java/de/zortax/injection/mcp/gen/WrapperClassBuilder.java"
    click GT "https://github.com/zortax/minecraftinjectionapi/blob/master/src/main/java/de/zortax/injection/mcp/gen/GenType.java"
    click Manifest "https://github.com/zortax/minecraftinjectionapi/blob/master/src/main/resources/META-INF/MANIFEST.MF"
    click Travis "https://github.com/zortax/minecraftinjectionapi/blob/master/.travis.yml"
    click BuildSh "https://github.com/zortax/minecraftinjectionapi/blob/master/build.sh"
    click POM "https://github.com/zortax/minecraftinjectionapi/blob/master/pom.xml"

    %% Styles
    classDef injection fill:#cce5ff,stroke:#004085,color:#004085
    classDef reflection fill:#d4edda,stroke:#155724,color:#155724
    classDef user fill:#fff3cd,stroke:#856404,color:#856404
    classDef external fill:#e2e3e5,stroke:#6c757d,color:#6c757d
    classDef ci fill:#f8d7da,stroke:#721c24,color:#721c24
    classDef doc fill:#d6d8d9,stroke:#1b1e21,color:#1b1e21
```
