# aeldrion/iris architecture

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

- Interactive diagram: https://gitdiagram.com/aeldrion/iris
- Repository: https://github.com/aeldrion/iris

## Overview

##### Project Type and Purpose
- Iris is a utility data pack for Minecraft: Java Edition (version 1.20.3+).
- Its purpose is to determine with micrometric precision what block or entity a player is targeting by performing raycasting, taking into account custom hitboxes, player coordinates, and rotation.
- It integrates with Minecraft’s command system via MC function files and uses a Python build script (gen_files.py) to generate some of these files based on external JSON reports (generated by IrisDataGen).

##### Analysis of the File Structure
- Top-level items: Standard repository files such as .gitignore, LICENSE, README.md, and pack.mcmeta.
- build/ directory:
- Contains Python scripts such as gen_files.py and util.py. These are used to generate missing files (e.g., block and entity hitbox definitions) during the build process.
- data/ directory:
- Contains the “iris” folder with multiple subdirectories for functions, predicates, and tags.
- get_hitbox: Functions and submodules to calculate block and entity hitboxes.
- get_position: Functions to extract and handle precise coordinates and rotations.
- raycast: Functions that perform the raycasting logic (including intersection methods, looping, and callbacks).
- set_coordinates: Function to teleport an entity using the computed precise position.
- setup: Setup-related functions including load routines for scoreboard and storage.
- data/iris/predicate and data/iris/tags support decision-making and filtering (e.g., checking for sneaking, swimming, or block offset).
- data/minecraft:
- Contains tag files, such as function tags for load, which ties into Minecraft’s datapack initialization system.

##### Key Architectural Components
a. Build & Generation Module:
- Python Build Scripts:
- gen_files.py & util.py in the build/ directory.
- Connects to external JSON inputs (blocks.json, entities.json generated via IrisDataGen) and produces/generated MC function files.
b. Raycasting Engine (Data Pack Core):
- Core Functions:
- get_target: Main entry for raycasting, which computes and returns hit information.
- raycast: A collection of functions that compute the progression through the Minecraft world via ray/plane intersection algorithms.
- Coordinate & Rotation Processing:
- get_position: Extracts and processes precise coordinates (integer and fractional parts) and computes rotation using a marker-based method.
- set_coordinates: Teleports an entity to the precise coordinates computed by get_position.
- Hitbox and Collision Calculation:
- get_hitbox: Looks up specific block or entity hitbox definitions (considering offsets) and groups similar hitboxes.
c. Setup and Configuration:
- Setup functions:
- Setup routines (load.mcfunction, scoreboard, and storage configuration) are found in the setup directory.
- These ensure that the necessary game state is initialized before raycasting.
- Settings Component:
- iris:settings storage holds configurable parameters like maximum recursion depth, target entity flag, blacklist/whitelist definitions.
d. Minecraft Data Pack Integration:
- Tags and Predicates:
- Tags (in data/iris/tags and data/minecraft/tags) manage how functions are loaded (e.g., during world load), and identify targeted blocks/entities.
- Predicates (in data/iris/predicate) check conditions for raycasting (e.g., baby, sneaking, swimming).
- Data Pack Structure:
- The pack.mcmeta file and folder organization confirm that this is a conventional Minecraft data pack.
e. External Dependences:
- JSON inputs from IrisDataGen (blocks.json, entities.json) fed into the build process.

##### Relationships and Data Flow
- Start at Build Phase: The build scripts take JSON files and produce necessary MC function files, which “populate” the data/iris structure.
- Runtime Flow in Minecraft:
- A player action triggers the execution of the “iris:get_target” function.
- This function calls into the raycasting engine, which uses sub-functions (from get_position and raycast) and then returns the hit outcome.
- Depending on the hit (block or entity), indicators (markers or tags) are set and stored in the iris:output storage.
- Optional functions (like iris:set_coordinates) use those outputs to teleport or place blocks based on user interaction.
- The directional flow in data is clearly from coordinate calculation → raycasting physics (hitbox detection) → output processing → execution of follow-up commands.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External JSON Input
    A["External JSON: IrisDataGen (blocks.json,entities.json)"]:::external

    %% Build Phase
    subgraph "Build Phase"
        B["Build Module: gen_files.py"]:::build
        C["Build Module: util.py"]:::build
        A -->|"feeds"| B
        A -->|"feeds"| C
        D["Generated MC Functions"]:::generated
        B --> D
        C --> D
    end

    %% Runtime Data Pack
    subgraph "Runtime Data Pack"
        E["Data Pack Metadata: pack.mcmeta"]:::metadata
        F["Setup: load,scoreboard,storage"]:::setup
        G["Raycasting Engine: get_target"]:::core
        H["Raycast Functions"]:::core
        I["Coordinate Processing: get_position"]:::coord
        J["Coordinate Processing: set_coordinates"]:::coord
        K["Hitbox Calculation: get_hitbox"]:::hitbox
        N["Output Storage: iris:output"]:::output
        M["Configuration: iris:settings"]:::config

        D --> G
        G --> H
        G --> I
        G --> K
        I --> J
        F --> G
        E --> F
        G --> N
        G --- M
        H --- M
        F -->|"initializes"| M

        %% Data Pack Integration: Predicates and Tags
        subgraph "Data Pack Integration"
            P["Predicates: data/iris/predicate"]:::integration
            T["Iris Tags: data/iris/tags"]:::integration
            U["Minecraft Tags: data/minecraft/tags/function/load.json"]:::integration
        end
        P --- G
        T --- G
        U --- G
        P --- H
        T --- H
        U --- H
        P --- K
        T --- K
        U --- K
    end

    %% External JSON feeds Build Phase
    %% (already connected at node A)

    %% Click Events
    click B "https://github.com/aeldrion/iris/blob/stable/build/gen_files.py"
    click C "https://github.com/aeldrion/iris/blob/stable/build/util.py"
    click G "https://github.com/aeldrion/iris/blob/stable/data/iris/function/get_target.mcfunction"
    click H "https://github.com/aeldrion/iris/tree/stable/data/iris/function/raycast"
    click I "https://github.com/aeldrion/iris/tree/stable/data/iris/function/get_position"
    click J "https://github.com/aeldrion/iris/tree/stable/data/iris/function/set_coordinates"
    click K "https://github.com/aeldrion/iris/tree/stable/data/iris/function/get_hitbox"
    click F "https://github.com/aeldrion/iris/tree/stable/data/iris/function/setup"
    click E "https://github.com/aeldrion/iris/blob/stable/pack.mcmeta"
    click P "https://github.com/aeldrion/iris/tree/stable/data/iris/predicate"
    click T "https://github.com/aeldrion/iris/tree/stable/data/iris/tags"
    click U "https://github.com/aeldrion/iris/blob/stable/data/minecraft/tags/function/load.json"

    %% Styles
    classDef external fill:#F9E79F,stroke:#B7950B,stroke-width:2px;
    classDef build fill:#AED6F1,stroke:#3498DB,stroke-width:2px;
    classDef generated fill:#D5F5E3,stroke:#27AE60,stroke-width:2px;
    classDef metadata fill:#FADBD8,stroke:#E74C3C,stroke-width:2px;
    classDef setup fill:#FCF3CF,stroke:#F1C40F,stroke-width:2px;
    classDef core fill:#D2B4DE,stroke:#8E44AD,stroke-width:2px;
    classDef coord fill:#FAD7A0,stroke:#E67E22,stroke-width:2px;
    classDef hitbox fill:#F6DDCC,stroke:#CA6F1E,stroke-width:2px;
    classDef output fill:#D6EAF8,stroke:#2E86C1,stroke-width:2px;
    classDef config fill:#E8DAEF,stroke:#8E44AD,stroke-width:2px;
    classDef integration fill:#E8F8F5,stroke:#1ABC9C,stroke-width:2px;
```
