release 0.2.5, more fixes and docs

- Finished re-documenting the code, again.
- Refactored some variables to be more readable.
- Reworked the fluid management to support filtering fluid types, be
more efficient, and probably fix some bugs.
- Removed a useless check, and rotation modification in the Hitbox
Handler.
- Removed the LiquidManager, we don't need that now that transports and
tile entities do it themselves.
- Removed the well car, it was never actually intended for TiM.
- Optomized the imports.
- This update marks the release of Alpha 2.5.

src/main/java/ebf/tim/TrainsInMotion.java

@@ -25,8 +25,6 @@
 import net.minecraftforge.common.MinecraftForge;
 import net.minecraftforge.common.config.Configuration;
 
-import java.util.UUID;
-
 
 /**
  * <h1>Main class</h1>
@@ -42,13 +40,14 @@
 @Mod(modid = TrainsInMotion.MODID, version = TrainsInMotion.MOD_VERSION, name = "Trains in Motion")
 public class TrainsInMotion {
 
-    //the ID of the mod and the version displayed in game, as well as used for version check in the version.txt file
+    /**the ID of the mod and the version displayed in game, as well as used for version check in the version.txt file*/
     public static final String MODID = "tim";
-    public static final String MOD_VERSION="0.2.0.1 alpha";
-    //an instance of the mod TODO: i doubt this even needs to be public
+    /**the version identifier of the mod*/
+    public static final String MOD_VERSION="0.2.5.0 alpha";
+    /**an instance of the mod*/
     @Mod.Instance(MODID)
     public static TrainsInMotion instance;
-    //the creative tab for the mod
+    /**the creative tab for the mod*/
     public static CreativeTabs creativeTab = new TiMTab(CreativeTabs.getNextID(), "Trains in Motion");
     /**
      *Setup the proxy, this is used for managing some of the client and server specific features.
@@ -59,42 +58,48 @@ public class TrainsInMotion {
     public static CommonProxy proxy;
 
 
-    //instance the network wrapper for the channels. Every wrapper runs on it's own thread, so heavy traffic should go on it's own wrapper, using channels to separate packet types.
+    /**instance the network wrapper for the channels.
+     * Every wrapper runs on it's own thread, so heavy traffic should go on it's own wrapper, using channels to separate packet types.*/
     public static SimpleNetworkWrapper keyChannel;
 
 
-    //Instance the event handler, This is used for event based functionality, things like when you right-click an entity.
+    /**Instance the event handler, This is used for event based functionality, things like when you right-click an entity.*/
     public static EventManager eventManager = new EventManager();
 
     /**
      * <h3>enums</h3>
-     * we define enums for transport types, block types, and inventory sizes here.
-     * makes it easier to add more later on, also simplifies the code elsewhere
-     * Enums will take up perm space though, so we shouldn't put massive amounts of data here or we break java 7 compatibility.
      *
-     * Inventory size should be thought about like it's own mini class since it has multiple values and works like a class long run.
      */
+
+     /**define the transport types*/
     public enum transportTypes {
         STEAM,DIESEL,HYDROGEN_DIESEL,ELECTRIC,NUCLEAR_STEAM,NUCLEAR_ELECTRIC,MAGLEV, //trains
         PASSENGER, FREIGHT, HOPPER, TANKER, WORKCAR, //generic rollingstock
         LOGCAR, RAILCAR, FREEZERCAR, LAVATANKER, GRAINHOPPER, COALHOPPER, //specific cargo rollingstock
-        TENDER, JUKEBOX, TRACKBUILDER //specialized Rollingstock
+        TENDER, JUKEBOX, TRACKBUILDER; //specialized Rollingstock
+
+         public boolean isTrain(){
+             return this == STEAM || this == DIESEL || this == HYDROGEN_DIESEL || this == ELECTRIC ||
+                     this == NUCLEAR_STEAM || this == NUCLEAR_ELECTRIC || this == MAGLEV;
+         }
     }
+    /**define the inventory size values, this lets us get values to define rows and columns rather than just overall size.*/
     public enum inventorySizes{NULL(0,0),
         TWOxTWO(2,2), TWOxTHREE(3,2), THREExTHREE(3,3), THREExFOUR(4,3), FOURxFOUR(4,4), FOURxFIVE(5,4), FIVExFIVE(5,5), FIVExSIX(6,5), SIXxSIX(6,6), NINExTHREE(3,9), NINExFOUR(4,9);
         private int row;
-        private int collumn;
-        inventorySizes(int row, int collumn){
+        private int column;
+        inventorySizes(int row, int column){
             this.row = row;
-            this.collumn = collumn;
+            this.column = column;
         }
         public int getRow() {
             return row;
         }
         public int getColumn() {
-            return collumn;
+            return column;
         }
     }
+    /**defines the type of block, so that way our generic block classes can change the functionality without needing a bunch of different classes.*/
     public enum blockTypes {
         CRAFTING, CONTAINER, COSMETIC, SWITCH
     }
@@ -103,14 +108,15 @@ public enum blockTypes {
      * <h2>load config</h2>
      * we use the pre-init to load the config file.
      * Most of the configs are decided by the proxy, no need to setup controls on the server.
-     * any generic settings that effect both come after proxy.loadConfig.
      */
+    @SuppressWarnings("unused")
     @Mod.EventHandler
     public void preInit(FMLPreInitializationEvent event) {
         Configuration config = new Configuration(event.getSuggestedConfigurationFile());
 
         config.load();
         proxy.loadConfig(config);
+        //settings that effect client and server here.
         config.save();
     }
 
@@ -131,9 +137,7 @@ public void init(FMLInitializationEvent event) {
         cpw.mods.fml.common.registry.EntityRegistry.registerModEntity(EntityBogie.class, "Bogie", 15, TrainsInMotion.instance, 60, 1, true);
         cpw.mods.fml.common.registry.EntityRegistry.registerModEntity(EntitySeat.class, "Seat", 16, TrainsInMotion.instance, 60, 2, true);
         int index =0;
-        /**
-         * now we loop for every value in the train registry and registry it, when the index reaches a null value, then it will stop.
-         */
+        ///now we loop for every value in the train registry and registry it, when the index reaches a null value, then it will stop.
         while (TransportRegistry.listTrains(index)!=null) {
             TransportRegistry registry = TransportRegistry.listTrains(index);
             cpw.mods.fml.common.registry.EntityRegistry.registerModEntity(registry.trainClass, registry.item.getUnlocalizedName().replace("item","entity"), index+17, TrainsInMotion.instance, 60, 1, true);

src/main/java/ebf/tim/entities/EntityBogie.java

@@ -20,7 +20,6 @@
 import net.minecraft.util.AxisAlignedBB;
 import net.minecraft.util.MathHelper;
 import net.minecraft.world.World;
-import zoranodensha.api.structures.tracks.ITrackBase;
 
 /**
  * <h1>Bogie Core</h1>

src/main/java/ebf/tim/entities/GenericRailTransport.java

@@ -100,10 +100,10 @@ public class GenericRailTransport extends Entity implements IEntityAdditionalSpa
     private FluidStack fluidTank = null;
     /**the list of items used for the inventory and crafting slots.*/
     private List<ItemStack> items;
-    /**the lst of unlocalized names for the filter*/
-    private List<String> filter = new ArrayList<String>();
-    /**whether the filter should only take the items in the list (whitelist), or whether it should take anything but the items in the list (blacklist).*/
-    private boolean isWhitelist = false;
+    /**the lst of unlocalized names for the itemFilter*/
+    private List<String> itemFilter = new ArrayList<String>();
+    /**whether the itemFilter should only take the items in the list (whitelist), or whether it should take anything but the items in the list (blacklist).*/
+    private boolean itemIsWhitelist = false;
     /**whether or not this needs to update the datawatchers*/
     public boolean updateWatchers = false;
     /**the RF battery for rollingstock.*/
@@ -332,12 +332,12 @@ protected void readEntityFromNBT(NBTTagCompound tag) {
                     setInventorySlotContents(i, ItemStack.loadItemStackFromNBT(tagCompound));
                 }
             }
-            isWhitelist = tag.getBoolean(NBTKeys.whitelist);
+            itemIsWhitelist = tag.getBoolean(NBTKeys.whitelist);
 
             int length = tag.getInteger(NBTKeys.filterLength);
             if (length > 0) {
                 for (int i = 0; i < length; i++) {
-                    filter.add(tag.getString(NBTKeys.filterItem + i));
+                    itemFilter.add(tag.getString(NBTKeys.filterItem + i));
                 }
             }
         }
@@ -384,13 +384,13 @@ protected void writeEntityToNBT(NBTTagCompound tag) {
                     tag.setTag(NBTKeys.inventoryItem + i, items.get(i).writeToNBT(new NBTTagCompound()));
                 }
             }
-            tag.setBoolean(NBTKeys.whitelist, isWhitelist);
+            tag.setBoolean(NBTKeys.whitelist, itemIsWhitelist);
 
 
-            tag.setInteger(NBTKeys.filterLength, filter!=null?filter.size():0);
-            if (filter != null && filter.size() > 0) {
-                for (int i = 0; i < filter.size(); i++) {
-                    tag.setString(NBTKeys.filterItem + i, filter.get(i));
+            tag.setInteger(NBTKeys.filterLength, itemFilter !=null? itemFilter.size():0);
+            if (itemFilter != null && itemFilter.size() > 0) {
+                for (int i = 0; i < itemFilter.size(); i++) {
+                    tag.setString(NBTKeys.filterItem + i, itemFilter.get(i));
                 }
             }
         }
@@ -837,17 +837,17 @@ public GameProfile getOwner(){
 
     /**
      * <h2>define filters</h2>
-     * this is called on the creation of an entity that need it's inventory filtered, or on the event that the entity's filter is set, like from the GUI.
+     * this is called on the creation of an entity that need it's inventory filtered, or on the event that the entity's itemFilter is set, like from the GUI.
      * whitelist as true will allow only the defined types or items. while as false will allow anything except the defined types or items.
      * types in most cases will override items because items are always checked last, if at all.
-     * itemTypes.ALL is basically just ignored, this is only called when you are not going to filter by type.
+     * itemTypes.ALL is basically just ignored, this is only called when you are not going to itemFilter by type.
      */
     public void setFilter(boolean isWhitelist, Item[] items){
-        this.isWhitelist = isWhitelist;
+        this.itemIsWhitelist = isWhitelist;
         if (items != null) {
-            filter.clear();
+            itemFilter.clear();
             for (Item itm : items){
-                filter.add(itm.getUnlocalizedName());
+                itemFilter.add(itm.getUnlocalizedName());
             }
         }
     }
@@ -968,15 +968,15 @@ public boolean isItemValidForSlot(int slot, ItemStack itemStack) {
 
 
         //before we even bother to try and check everything else, check if it's filtered in the first place.
-        if (itemStack == null || filter.size() == 0) {
+        if (itemStack == null || itemFilter.size() == 0) {
             return true;
         }
         //if we use a whitelist, only return true if the item is in the list.
-        if (isWhitelist) {
-            return filter.size() != 0 && filter.contains(itemStack.getItem().getUnlocalizedName());
+        if (itemIsWhitelist) {
+            return itemFilter.size() != 0 && itemFilter.contains(itemStack.getItem().getUnlocalizedName());
         } else {
             //if it's a blacklist do exactly the same as above but return the opposite value.
-            return filter.size() == 0 || !filter.contains(itemStack.getItem().getUnlocalizedName());
+            return itemFilter.size() == 0 || !itemFilter.contains(itemStack.getItem().getUnlocalizedName());
         }
     }
 
@@ -1088,96 +1088,79 @@ public void closeInventory() {}
     public boolean canDrain(ForgeDirection from, Fluid resource){return fluidTank != null && fluidTank.amount>0 && (fluidTank.getFluid() == resource || resource == null);}
     /**Returns true if the given fluid can be inserted into the fluid tank.*/
     @Override
-    public boolean canFill(ForgeDirection from, Fluid resource){return getTankCapacity()>0 && (fluidTank == null || fluidTank.getFluid() == resource);}
-    //drain a set amount
+    public boolean canFill(ForgeDirection from, Fluid resource){return getTankCapacity()>0 && (fluidTank == null || fluidTank.getFluid() != resource);}
+    //attenpt to drain a set amount
     @Override
     public FluidStack drain(ForgeDirection from, int drain, boolean doDrain){
         if (getTankCapacity() <1 || fluidTank == null || fluidTank.amount <1){
             return null;
         } else {
-            if (fluidTank.amount <= drain){
-                FluidStack toReturn = fluidTank.copy();
-                if (doDrain){
+            int amountToDrain = getTankAmount() < drain?getTankAmount():drain;
+            if (doDrain){
+                if (amountToDrain == getTankAmount()) {
                     fluidTank = null;
-                    this.dataWatcher.updateObject(20,0);
-                }
-                return toReturn;
-            } else {
-                FluidStack toReturn = fluidTank.copy();
-                toReturn.amount -= drain;
-                if (doDrain){
-                    fluidTank.amount -= drain;
+                    this.dataWatcher.updateObject(20, 0);
+                } else {
+                    fluidTank.amount -= amountToDrain;
                     this.dataWatcher.updateObject(20, fluidTank.amount);
                 }
-                return toReturn;
             }
+            return new FluidStack(fluidTank.getFluid(), amountToDrain);
         }
     }
-    //drain only if its a specific fluidTank
+
+    /**drain with a fluidStack, this is mostly a redirect to
+     * @see #drain(ForgeDirection, int, boolean) but with added filtering for fluid type.
+     */
     @Override
     public FluidStack drain(ForgeDirection from, FluidStack resource, boolean doDrain){
         if (getTankCapacity() <1 || fluidTank == null || fluidTank.getFluid() != resource.getFluid() || fluidTank.amount<1){
             return null;
         } else {
-            if (fluidTank.amount <= resource.amount){
-                FluidStack toReturn = fluidTank.copy();
-                if (doDrain){
-                    fluidTank = null;
-                    this.dataWatcher.updateObject(20,0);
-                }
-                return toReturn;
-            } else {
-                FluidStack toReturn = fluidTank.copy();
-                toReturn.amount -= resource.amount;
-                if (doDrain){
-                    fluidTank.amount -= resource.amount;
-                    this.dataWatcher.updateObject(20, fluidTank.amount);
-                }
-                return toReturn;
-            }
+            return drain(from, resource.amount,doDrain);
         }
     }
     /**returns the amount of fluid in the tank. 0 if the tank is null*/
     public int getTankAmount(){
         return fluidTank !=null? fluidTank.amount:0;
     }
 
+    /**checks if the fluid can be put into the tank, and if doFill is true, will actually attempt to add the fluid to the tank.
+     * @return the amount of fluid that was or could be put into the tank.*/
     @Override
     public int fill(ForgeDirection from, FluidStack resource, boolean doFill){
-        if (getTankCapacity() <1 || !(fluidTank == null || fluidTank.getFluid() == resource.getFluid())){
+        //if the tank has no capacity, or the filter prevents this fluid, or the fluid in the tank already isn't the same.
+        if (getTankCapacity() <1 || filterFluids(resource.getFluid()) || (fluidTank != null && fluidTank.getFluid() != resource.getFluid())){
             return 0;
         }
+        int amountToFill;
+        //if the tank is null, figure out how much fluid to add based on tank capacity.
         if (fluidTank == null){
-            if (resource.amount > getTankCapacity()) {
-                resource.amount = getTankCapacity();
-            }
+            amountToFill = getTankCapacity() < resource.amount?getTankCapacity():resource.amount;
             if (doFill) {
-                fluidTank = resource;
-                this.dataWatcher.updateObject(20, fluidTank.amount);
-            }
-            return resource.amount;
-
-        } else if (getTankCapacity() + fluidTank.amount < resource.amount){
-            if (doFill){
-                fluidTank.amount += resource.amount;
+                fluidTank = new FluidStack(resource.getFluid(), amountToFill);
                 this.dataWatcher.updateObject(20, fluidTank.amount);
             }
-            return resource.amount;
+            //if the tank isn't null, we also have to check the amount already in the tank
         } else {
-            int volume = getTankCapacity() - fluidTank.amount;
+            amountToFill = getTankCapacity() -getTankAmount() < resource.amount?getTankCapacity()-getTankAmount():resource.amount;
             if (doFill){
-                fluidTank.amount += volume;
+                fluidTank.amount += amountToFill;
                 this.dataWatcher.updateObject(20, fluidTank.amount);
             }
-            return volume;
         }
+        return amountToFill;
     }
     /**returns the list of fluid tanks and their capacity.*/
     @Override
     public FluidTankInfo[] getTankInfo(ForgeDirection from){
         return getTankCapacity()<1?null:new FluidTankInfo[]{new FluidTankInfo(fluidTank, getTankCapacity())};
     }
 
+    /**filters the fluids use this to define what fluids to allow in the tank*/
+    public boolean filterFluids(Fluid fluid){
+        return true;
+    }
 
 
     /**