Architecture, Bytecode Mixins & Performance — MC 26.3

This page details the internal software architecture, bytecode mixin injection targets, performance guardrails, and automated testing suites for Max Elytra Fly Speed (MC 26.3).

---

📋 Architecture Infobox

Parameter	Technical Details
Namespace Package	net.instantgratification.maxelytraflyspeed
Mod Initializer	net.instantgratification.maxelytraflyspeed.MaxElytraFlySpeedFabric
Client Initializer	net.instantgratification.maxelytraflyspeed.MaxElytraFlySpeedFabricClient
Mixin Configuration	src/main/resources/max-elytra-fly-speed.mixins.json
Active Mixins	LivingEntityMixin, FireworkRocketEntityMixin
Hot Path Memory Profile	Zero heap allocations ($\mathcal{O}(1)$ time complexity)
Classloader Guard	ModVersionGuard.checkClass in onInitialize

---

🏛️ Package Architecture & Responsibilities

The codebase follows the The Clean "1 File, 1 Purpose" Architecture Law, separating mathematical algorithms, bytecode manipulation, configuration, and client interfaces into dedicated classes:

net.instantgratification.maxelytraflyspeed/
├── MaxElytraFlySpeedFabric.java         # Main ModInitializer & GameRule registrations
├── MaxElytraFlySpeedFabricClient.java   # ClientModInitializer
├── config/
│   ├── ClothConfigScreenHelper.java    # Optional Cloth Config GUI factory
│   └── ModMenuIntegration.java         # ModMenuApi implementation
├── mixin/
│   ├── FireworkRocketEntityMixin.java  # Bytecode redirection for rocket boost calculations
│   └── LivingEntityMixin.java          # Fall-flying drag redirection & velocity clamping
└── util/
    ├── ElytraDragHelper.java           # Pure mathematical drag floor scaling algorithms
    ├── ModVersionGuard.java            # Knot/Fabric ClassLoader validation utility
    └── RocketBoostHelper.java          # Two-tier rocket propulsion vector math

---

🧩 Bytecode Mixin Breakdown

1. LivingEntityMixin.java

• Target Class: net.minecraft.world.entity.LivingEntity
• Injection Points:
  1. @Redirect in updateFallFlyingMovement:

     @Redirect(
         method = "updateFallFlyingMovement",
         at = @At(
             value = "INVOKE",
             target = "Lnet/minecraft/world/phys/Vec3;multiply(DDD)Lnet/minecraft/world/phys/Vec3;"
         )
     )
     private Vec3 maxelytraflyspeed$adjustDrag(Vec3 movement, double x, double y, double z) {
         LivingEntity entity = (LivingEntity) (Object) this;
         int maxSpeedBps = DynamicGameRuleManager.getInt(entity.level(), MaxElytraFlySpeedFabric.MAX_ELYTRA_FLY_SPEED);
         return ElytraDragHelper.calculateFallFlyingDrag(movement, maxSpeedBps);
     }

  2. @Inject in travelFallFlying:

     @Inject(
         method = "travelFallFlying",
         at = @At(
             value = "INVOKE",
             target = "Lnet/minecraft/world/entity/LivingEntity;move(Lnet/minecraft/world/entity/MoverType;Lnet/minecraft/world/phys/Vec3;)V"
         )
     )
     private void maxelytraflyspeed$clampMaxSpeed(Vec3 input, CallbackInfo ci) {
         LivingEntity entity = (LivingEntity) (Object) this;
         int maxSpeedBps = DynamicGameRuleManager.getInt(entity.level(), MaxElytraFlySpeedFabric.MAX_ELYTRA_FLY_SPEED);
         double maxSpeedTicks = maxSpeedBps / 20.0;
         Vec3 velocity = entity.getDeltaMovement();
         double currentSpeed = velocity.length();
         if (currentSpeed > maxSpeedTicks && currentSpeed > 0.0) {
             entity.setDeltaMovement(velocity.scale(maxSpeedTicks / currentSpeed));
         }
     }

---

2. FireworkRocketEntityMixin.java

• Target Class: net.minecraft.world.entity.projectile.FireworkRocketEntity
• Injection Point:
  • @Redirect in tick():

    @Redirect(
        method = "tick",
        at = @At(
            value = "INVOKE",
            target = "Lnet/minecraft/world/entity/LivingEntity;setDeltaMovement(Lnet/minecraft/world/phys/Vec3;)V"
        )
    )
    private void maxelytraflyspeed$scaleRocketBoost(LivingEntity entity, Vec3 newMovement) {
        Vec3 oldMovement = entity.getDeltaMovement();
        int maxSpeedBps = DynamicGameRuleManager.getInt(entity.level(), MaxElytraFlySpeedFabric.MAX_ELYTRA_FLY_SPEED);
        double maxSpeedTicks = maxSpeedBps / 20.0;
    
        int initialBoostSpeedBps = DynamicGameRuleManager.getInt(entity.level(), MaxElytraFlySpeedFabric.ELYTRA_INITIAL_BOOST_SPEED);
        double initialBoostSpeedTicks = initialBoostSpeedBps / 20.0;
    
        int highAccPermille = DynamicGameRuleManager.getInt(entity.level(), MaxElytraFlySpeedFabric.ELYTRA_HIGH_SPEED_ACCELERATION);
        double highAccFactor = Math.max(0.05, highAccPermille / 100.0);
    
        Vec3 lookAngle = entity.getLookAngle();
        Vec3 targetMovement = RocketBoostHelper.calculateBoostMovement(
            oldMovement, lookAngle, initialBoostSpeedTicks, maxSpeedTicks, highAccFactor
        );
        entity.setDeltaMovement(targetMovement);
    }

---

⚡ Performance & Zero-Allocation Guardrails

Flight physics executes 20 times per second for every flying entity in the world:

1. Zero Heap Allocation in Hot Paths:
   • All vector calculations in ElytraDragHelper and RocketBoostHelper reuse native immutable Vec3 methods (multiply, scale, add, subtract) without instantiating custom tracking wrapper objects.
2. Deterministic $\mathcal{O}(1)$ Execution:
   • Drag calculations and rocket convergence require strictly constant-time floating-point operations ($\approx 0.0001\mu\text{s}$ per check).
3. Strict Null Safety:
   • Both helpers validate incoming vectors and safely return Vec3.ZERO if an unexpected null movement or look angle is encountered.

---

🧪 Automated Reality Testing Suite

The mod includes headless JUnit 5 unit tests in src/test/java/ verifying all math, edge cases, and boundary conditions prior to release:

Test Class	Test Case	Assertion Objective
ElytraDragHelperTest	testVanillaParityDragAtOrBelow50Bps	Asserts exact $0.99H / 0.98V$ multipliers at $\le 50\text{ BPS}$.
ElytraDragHelperTest	testDynamicDragReductionAbove50Bps	Asserts relaxed drag at $100\text{ BPS}$ ($0.9950H/0.9900V$) and $200\text{ BPS}$ ($0.9975H/0.9950V$).
ElytraDragHelperTest	testNullVectorSafety	Asserts strict null safety returning zero vector without throwing NPE.
RocketBoostHelperTest	testInitialBoostSnappyAcceleration	Asserts snappy $0.5$ convergence below $30\text{ BPS}$ threshold.
RocketBoostHelperTest	testHighSpeedProportionalAcceleration	Asserts proportional vector difference convergence above $30\text{ BPS}$.
RocketBoostHelperTest	testMaxSpeedClamping	Asserts vector clamping when rocket boost exceeds maximum flight ceiling.
RocketBoostHelperTest	testNullVectorSafety	Asserts strict null safety on movement and look angle parameters.

---

🧭 Navigation

• 📖 MC 26.3 Overview
• 🌀 Kinetic Physics & Drag
• 🚀 Rocket Propulsion & Acceleration
• ⚙️ GameRules & Configuration
• 🏠 Wiki Home