How aeldrion/iris works
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.