Better comments on hopper tick patch

CraftBukkit-Patches/0146-Alternative-Hopper-Ticking.patch

@@ -1,19 +1,22 @@
-From e8b30c53ce2cd6e2be450d6d03f8977c79bcc231 Mon Sep 17 00:00:00 2001
+From ee57713dd00e22d5629a29410922ed293163e3fe Mon Sep 17 00:00:00 2001
 From: "Evan A. Haskell" <eah2119@gmail.com>
 Date: Sat, 19 Apr 2014 16:58:26 -0400
 Subject: [PATCH] Alternative Hopper Ticking
 
 
 diff --git a/src/main/java/net/minecraft/server/BlockHopper.java b/src/main/java/net/minecraft/server/BlockHopper.java
-index 9e64702..36682df 100644
+index 9e64702..e1e626b 100644
 --- a/src/main/java/net/minecraft/server/BlockHopper.java
 +++ b/src/main/java/net/minecraft/server/BlockHopper.java
-@@ -87,6 +87,14 @@ public class BlockHopper extends BlockContainer {
+@@ -87,6 +87,17 @@ public class BlockHopper extends BlockContainer {
  
          if (flag != flag1) {
              world.setData(i, j, k, i1 | (flag ? 0 : 8), 4);
 +            // Spigot start - When this hopper becomes unpowered, make it active.
++            // Called when this block's power level changes. flag1 is the current
++            // isNotPowered from metadata. flag is the recalculated isNotPowered.
 +            if (world.spigotConfig.altHopperTicking) {
++            	// e returns the TileEntityHopper associated with this BlockHopper.
 +                TileEntityHopper hopper = e((IBlockAccess) world, i, j, k);
 +                if (flag && hopper != null) {
 +                    hopper.makeTick();
@@ -23,7 +26,7 @@ index 9e64702..36682df 100644
          }
      }
  
-@@ -163,4 +171,16 @@ public class BlockHopper extends BlockContainer {
+@@ -163,4 +174,17 @@ public class BlockHopper extends BlockContainer {
      public static TileEntityHopper e(IBlockAccess iblockaccess, int i, int j, int k) {
          return (TileEntityHopper) iblockaccess.getTileEntity(i, j, k);
      }
@@ -32,6 +35,7 @@ index 9e64702..36682df 100644
 +    @Override
 +    public void a(World world, int i, int j, int k, Random random) {
 +        if (world.spigotConfig.altHopperTicking) {
++        	// e returns the TileEntityHopper associated with this BlockHopper.
 +            TileEntityHopper hopper = e((IBlockAccess) world, i, j, k);
 +            if (hopper != null) {
 +                hopper.makeTick();
@@ -41,14 +45,14 @@ index 9e64702..36682df 100644
 +    // Spigot end
  }
 diff --git a/src/main/java/net/minecraft/server/Chunk.java b/src/main/java/net/minecraft/server/Chunk.java
-index 364df1d..5771fbd 100644
+index 2c95832..b5014b0 100644
 --- a/src/main/java/net/minecraft/server/Chunk.java
 +++ b/src/main/java/net/minecraft/server/Chunk.java
 @@ -722,6 +722,11 @@ public class Chunk {
  
              tileentity.t();
              this.tileEntities.put(chunkposition, tileentity);
-+            // Spigot start - We have a world, now we can be sure hoppers are born ticking.
++            // Spigot start - The tile entity has a world, now hoppers can be born ticking.
 +            if (this.world.spigotConfig.altHopperTicking) {
 +                this.world.triggerHoppersList.add(tileentity);
 +            }
@@ -57,14 +61,15 @@ index 364df1d..5771fbd 100644
          } else {
              System.out.println("Attempted to place a tile entity (" + tileentity + ") at " + tileentity.x + "," + tileentity.y + "," + tileentity.z
 diff --git a/src/main/java/net/minecraft/server/EntityItem.java b/src/main/java/net/minecraft/server/EntityItem.java
-index 5eb893f..f9e16ac 100644
+index 5eb893f..6dfedc0 100644
 --- a/src/main/java/net/minecraft/server/EntityItem.java
 +++ b/src/main/java/net/minecraft/server/EntityItem.java
-@@ -102,6 +102,26 @@ public class EntityItem extends Entity {
+@@ -102,6 +102,27 @@ public class EntityItem extends Entity {
              if (this.onGround) {
                  this.motY *= -0.5D;
              }
-+            // Spigot start - Make the hopper below this item active.
++            // Spigot start - Make the hopper(s) below this item active.
++            // Called each tick on each item entity.
 +            if (this.world.spigotConfig.altHopperTicking) {
 +                int xi = MathHelper.floor(this.boundingBox.a);
 +                int yi = MathHelper.floor(this.boundingBox.b) - 1;
@@ -88,14 +93,15 @@ index 5eb893f..f9e16ac 100644
              // ++this.age; // CraftBukkit - Moved up
              if (!this.world.isStatic && this.age >= world.spigotConfig.itemDespawnRate) { // Spigot
 diff --git a/src/main/java/net/minecraft/server/EntityMinecartAbstract.java b/src/main/java/net/minecraft/server/EntityMinecartAbstract.java
-index 166206c..1305526 100644
+index 166206c..de60840 100644
 --- a/src/main/java/net/minecraft/server/EntityMinecartAbstract.java
 +++ b/src/main/java/net/minecraft/server/EntityMinecartAbstract.java
-@@ -342,6 +342,26 @@ public abstract class EntityMinecartAbstract extends Entity {
+@@ -342,6 +342,27 @@ public abstract class EntityMinecartAbstract extends Entity {
  
                  this.passenger = null;
              }
-+            // Spigot start - Make hoppers adjacent to this container minecart active.
++            // Spigot start - Make hoppers around this container minecart active.
++            // Called each tick on each minecart.
 +            if (this.world.spigotConfig.altHopperTicking && this instanceof EntityMinecartContainer) {
 +                int xi = MathHelper.floor(this.boundingBox.a) - 1;
 +                int yi = MathHelper.floor(this.boundingBox.b) - 1;
@@ -119,15 +125,17 @@ index 166206c..1305526 100644
      }
  
 diff --git a/src/main/java/net/minecraft/server/EntityOcelot.java b/src/main/java/net/minecraft/server/EntityOcelot.java
-index 603e53d..b5fe441 100644
+index 1ce9fb8..b3e6ec8 100644
 --- a/src/main/java/net/minecraft/server/EntityOcelot.java
 +++ b/src/main/java/net/minecraft/server/EntityOcelot.java
-@@ -27,6 +27,29 @@ public class EntityOcelot extends EntityTameableAnimal {
+@@ -27,6 +27,31 @@ public class EntityOcelot extends EntityTameableAnimal {
          this.datawatcher.a(18, Byte.valueOf((byte) 0));
      }
  
-+    // Spigot start - When this ocelot begins standing, any chests below this ocelot must be
++    // Spigot start - When this ocelot begins standing, chests below this ocelot must be
-+    // updated as if its contents have changed.
++    // updated as if its contents have changed. We update chests if this ocelot is sitting
++    // knowing that it may be dead, gone, or standing after this method returns.
++    // Called each tick on each ocelot.
 +    @Override
 +    public void h() {
 +        if (this.world.spigotConfig.altHopperTicking && this.isSitting()) {
@@ -153,35 +161,39 @@ index 603e53d..b5fe441 100644
          if (this.getControllerMove().a()) {
              double d0 = this.getControllerMove().b();
 diff --git a/src/main/java/net/minecraft/server/TileEntity.java b/src/main/java/net/minecraft/server/TileEntity.java
-index 19d008c..4a0ca46 100644
+index 19d008c..c5859e5 100644
 --- a/src/main/java/net/minecraft/server/TileEntity.java
 +++ b/src/main/java/net/minecraft/server/TileEntity.java
-@@ -24,6 +24,36 @@ public class TileEntity {
+@@ -24,6 +24,40 @@ public class TileEntity {
      public int g = -1;
      public Block h;
  
 +    // Spigot start
-+    // Used for alternative ticking. If the hopper at x0, y0, z0 is pointed at this tile entity, make it active.
++    // Helper method for scheduleTicks. If the hopper at x0, y0, z0 is pointed
++    // at this tile entity, then make it active.
 +    private void scheduleTick(int x0, int y0, int z0) {
 +        TileEntity tileEntity = this.world.getTileEntity(x0, y0, z0);
 +        if (tileEntity instanceof TileEntityHopper && tileEntity.world != null) {
++            // i is the metadeta assoiated with the direction the hopper faces.
 +            int i = BlockHopper.b(tileEntity.p());
++            // Facing class provides arrays for direction offset.
 +            if (tileEntity.x + Facing.b[i] == this.x && tileEntity.y + Facing.c[i] == this.y && tileEntity.z + Facing.d[i] == this.z) {
 +                ((TileEntityHopper) tileEntity).makeTick();
 +            }
 +        }
 +    }
 +    
-+    // Contents have changed, so hoppers need ticking. Check all 6 faces.
++    // Called from update when the contents have changed, so hoppers need updates.
++    // Check all 6 faces.
 +    public void scheduleTicks() {
 +        if (this.world != null && this.world.spigotConfig.altHopperTicking) {
-+            // check the top
++            // Check the top
 +            this.scheduleTick(this.x, this.y + 1, this.z);
-+            // check the sides
++            // Check the sides
 +            for (int i = 2; i < 6; i++) {
 +                this.scheduleTick(this.x + Facing.b[i], this.y, this.z + Facing.d[i]);
 +            }
-+            // check the bottom
++            // Check the bottom.
 +            TileEntity tileEntity = this.world.getTileEntity(this.x, this.y - 1, this.z);
 +            if (tileEntity instanceof TileEntityHopper && tileEntity.world != null) {
 +                ((TileEntityHopper) tileEntity).makeTick();
@@ -193,29 +205,30 @@ index 19d008c..4a0ca46 100644
      public TileEntity() {}
  
      private static void a(Class oclass, String s) {
-@@ -105,6 +135,9 @@ public class TileEntity {
+@@ -105,6 +139,10 @@ public class TileEntity {
              if (this.q() != Blocks.AIR) {
                  this.world.f(this.x, this.y, this.z, this.q());
              }
-+            // Spigot start - The contents have changed, so make the hoppers pointed at this inventory active.
++            // Spigot start - Called when the contents have changed, so hoppers around this
++            // tile need updating.
 +            this.scheduleTicks();
 +            // Spigot end
          }
      }
  
 diff --git a/src/main/java/net/minecraft/server/TileEntityHopper.java b/src/main/java/net/minecraft/server/TileEntityHopper.java
-index b620394..02c07cd 100644
+index b620394..c7b3495 100644
 --- a/src/main/java/net/minecraft/server/TileEntityHopper.java
 +++ b/src/main/java/net/minecraft/server/TileEntityHopper.java
-@@ -17,6 +17,42 @@ public class TileEntityHopper extends TileEntity implements IHopper {
+@@ -17,6 +17,43 @@ public class TileEntityHopper extends TileEntity implements IHopper {
      private String i;
      private int j = -1;
  
 +    // Spigot start
-+    private long nextTick = -1; // Next tick this hopper will be ticked
++    private long nextTick = -1; // Next tick this hopper will be ticked.
-+    private long lastTick = -1; // Last tick this hopper was polled
++    private long lastTick = -1; // Last tick this hopper was polled.
 +    
-+    // To be used only with the alternative ticking. If this hopper is not cooling down, assaign a visible tick for next time.
++    // If this hopper is not cooling down, assaign a visible tick for next time.
 +    public void makeTick() {
 +        if (!this.j()) {
 +            this.c(0);
@@ -229,9 +242,10 @@ index b620394..02c07cd 100644
 +        }
 +    }
 +    
-+    // We can't use config or c() if we don't have a world, so this is called when this hopper is assaigned a world.
++	// Called after this hopper is assaigned a world or when altHopperTicking is turned
-+    // Is also called when alt hopper ticking is turned on from the reload command
++	// on from reload.
 +    public void convertToScheduling() {
++    	// j is the cooldown in ticks
 +        this.c(this.j);
 +    }
 +    
@@ -250,7 +264,7 @@ index b620394..02c07cd 100644
      // CraftBukkit start - add fields and methods
      public List<HumanEntity> transaction = new java.util.ArrayList<HumanEntity>();
      private int maxStack = MAX_STACK;
-@@ -80,7 +116,19 @@ public class TileEntityHopper extends TileEntity implements IHopper {
+@@ -80,7 +117,20 @@ public class TileEntityHopper extends TileEntity implements IHopper {
          }
  
          nbttagcompound.set("Items", nbttaglist);
@@ -265,13 +279,14 @@ index b620394..02c07cd 100644
 +            }
 +            nbttagcompound.setInt("TransferCooldown", (int) Math.max(0, Math.min(cooldownDiff, Integer.MAX_VALUE)));
 +        } else {
++        	// j is the cooldown in ticks.
 +            nbttagcompound.setInt("TransferCooldown", this.j);
 +        }
 +        // Spigot end
          if (this.k_()) {
              nbttagcompound.setString("CustomName", this.i);
          }
-@@ -88,6 +136,9 @@ public class TileEntityHopper extends TileEntity implements IHopper {
+@@ -88,6 +138,9 @@ public class TileEntityHopper extends TileEntity implements IHopper {
  
      public void update() {
          super.update();
@@ -281,7 +296,7 @@ index b620394..02c07cd 100644
      }
  
      public int getSize() {
-@@ -167,11 +218,20 @@ public class TileEntityHopper extends TileEntity implements IHopper {
+@@ -167,11 +220,21 @@ public class TileEntityHopper extends TileEntity implements IHopper {
  
      public void h() {
          if (this.world != null && !this.world.isStatic) {
@@ -293,6 +308,7 @@ index b620394..02c07cd 100644
 +            if (this.world.spigotConfig.altHopperTicking) {
 +                this.lastTick = this.world.getTime();
 +                if (this.nextTick == this.world.getTime()) {
++                	// Method that does the pushing and pulling.
 +                    this.i();
 +                }
 +            } else {
@@ -306,7 +322,7 @@ index b620394..02c07cd 100644
          }
      }
  
-@@ -196,7 +256,7 @@ public class TileEntityHopper extends TileEntity implements IHopper {
+@@ -196,7 +259,7 @@ public class TileEntityHopper extends TileEntity implements IHopper {
              }
  
              // Spigot start
@@ -315,7 +331,7 @@ index b620394..02c07cd 100644
              {
                  this.c( world.spigotConfig.hopperCheck );
              }
-@@ -584,10 +644,34 @@ public class TileEntityHopper extends TileEntity implements IHopper {
+@@ -584,10 +647,34 @@ public class TileEntityHopper extends TileEntity implements IHopper {
      }
  
      public void c(int i) {
@@ -353,23 +369,23 @@ index b620394..02c07cd 100644
      }
  }
 diff --git a/src/main/java/net/minecraft/server/World.java b/src/main/java/net/minecraft/server/World.java
-index a879ae3..3559bfc 100644
+index a879ae3..a2fa854 100644
 --- a/src/main/java/net/minecraft/server/World.java
 +++ b/src/main/java/net/minecraft/server/World.java
 @@ -113,6 +113,7 @@ public abstract class World implements IBlockAccess {
      private final byte chunkTickRadius;
      public static boolean haveWeSilencedAPhysicsCrash;
      public static String blockLocation;
-+    public List<TileEntity> triggerHoppersList = new ArrayList<TileEntity>(); // Spigot
++    public List<TileEntity> triggerHoppersList = new ArrayList<TileEntity>(); // Spigot, When altHopperTicking, tile entities being added go through here.
  
      public static long chunkToKey(int x, int z)
      {
-@@ -130,6 +131,40 @@ public abstract class World implements IBlockAccess {
+@@ -130,6 +131,42 @@ public abstract class World implements IBlockAccess {
      {
          return (int) ( ( ( k >> 32 ) & 0xFFFF0000L ) | ( ( k >> 16 ) & 0x0000FFFF ) );
      }
 +
-+    // Spigot Start
++    // Spigot Start - Hoppers need to be born ticking.
 +    private void initializeHoppers() {
 +        if (this.spigotConfig.altHopperTicking) {
 +            for (TileEntity o : this.triggerHoppersList) {
@@ -383,7 +399,8 @@ index a879ae3..3559bfc 100644
 +        triggerHoppersList.clear();
 +    }
 +    
-+    // To be used only with alt hopper ticking
++    // Helper method for altHopperTicking. Updates chests at the specified location,
++    // accounting for double chests. Updating the chest will update adjacent hoppers.
 +    public void updateChestAndHoppers(int a, int b, int c) {
 +        Block block = this.getType(a, b, c);
 +        if (block instanceof BlockChest) {
@@ -392,6 +409,7 @@ index a879ae3..3559bfc 100644
 +                tile.scheduleTicks();
 +            }
 +            for (int i = 2; i < 6; i++) {
++            	// Facing class provides arrays for direction offset.
 +                if (this.getType(a + Facing.b[i], b, c + Facing.d[i]) == block) {
 +                    tile = this.getTileEntity(a + Facing.b[i], b, c + Facing.d[i]);
 +                    if (tile instanceof TileEntityChest) {
@@ -405,12 +423,14 @@ index a879ae3..3559bfc 100644
      // Spigot end
  
      public BiomeBase getBiome(int i, int j) {
-@@ -404,6 +439,12 @@ public abstract class World implements IBlockAccess {
+@@ -404,6 +441,14 @@ public abstract class World implements IBlockAccess {
                      this.notifyAndUpdatePhysics(i, j, k, chunk, block1, block, i1);
                  // CraftBukkit end
                  }
 +                // Spigot start - If this block is changing to that which a chest beneath it
-+                // becomes able to be opened, then said chest must be updated
++                // becomes able to be opened, then the chest must be updated.
++                // block1 is the old block. block is the new block. r returns true if the block type
++                // prevents access to a chest.
 +                if (this.spigotConfig.altHopperTicking && block1 != null && block1.r() && !block.r()) {
 +                    this.updateChestAndHoppers(i, j - 1, k);
 +                }
@@ -418,11 +438,11 @@ index a879ae3..3559bfc 100644
  
                  return flag;
              }
-@@ -1455,6 +1496,7 @@ public abstract class World implements IBlockAccess {
+@@ -1455,6 +1500,7 @@ public abstract class World implements IBlockAccess {
          }
          // Spigot End
          this.M = true;
-+        this.initializeHoppers(); // Spigot - hopper ticking
++        this.initializeHoppers(); // Spigot - Initializes hoppers which have been added recently.
          Iterator iterator = this.tileEntityList.iterator();
  
          while (iterator.hasNext()) {