Documentation: lots

Some eclipse workspace settings that might help?

fml/common/cpw/mods/fml/common/FMLCommonHandler.java

@@ -13,6 +13,7 @@
  */
 package cpw.mods.fml.common;
 
+import java.io.File;
 import java.io.UnsupportedEncodingException;
 import java.util.HashMap;
 import java.util.HashSet;
@@ -20,24 +21,55 @@ import java.util.Map;
 import java.util.Set;
 import java.util.logging.Logger;
 
-import net.minecraft.src.EntityPlayer;
-
-
-
+/**
+ * The main class for non-obfuscated hook handling code
+ * 
+ * Anything that doesn't require obfuscated or client/server specific code should 
+ * go in this handler
+ * 
+ * It also contains a reference to the sided handler instance that is valid
+ * allowing for common code to access specific properties from the obfuscated world
+ * without a direct dependency
+ * 
+ * @author cpw
+ *
+ */
 public class FMLCommonHandler
 {
+    /**
+     * The singleton
+     */
     private static final FMLCommonHandler INSTANCE = new FMLCommonHandler();
+    /**
+     * A map of mods to their network channels
+     */
     private Map<ModContainer, Set<String>> channelList = new HashMap<ModContainer, Set<String>>();
+    /**
+     * A map of channels to mods
+     */
     private Map<String, ModContainer> modChannels = new HashMap<String, ModContainer>();
+    /**
+     * A map of active channels per player
+     */
     private Map<Object, Set<String>> activeChannels = new HashMap<Object, Set<String>>();
+    /**
+     * The delegate for side specific data and functions 
+     */
     private IFMLSidedHandler sidedDelegate;
 
 
+    /**
+     * We register our delegate here
+     * @param handler
+     */
     public void registerSidedDelegate(IFMLSidedHandler handler)
     {
         sidedDelegate = handler;
     }
 
+    /**
+     * Pre-tick the mods 
+     */
     public void gameTickStart()
     {
         for (ModContainer mod : Loader.getModList())
@@ -46,6 +78,9 @@ public class FMLCommonHandler
         }
     }
 
+    /**
+     * Post-tick the mods
+     */
     public void gameTickEnd()
     {
         for (ModContainer mod : Loader.getModList())
@@ -62,11 +97,17 @@ public class FMLCommonHandler
         return INSTANCE;
     }
 
+    /**
+     * Lookup the mod for a channel
+     * @param channel
+     * @return
+     */
     public ModContainer getModForChannel(String channel)
     {
         return modChannels.get(channel);
     }
     /**
+     * Get the channel list for a mod
      * @param modLoaderModContainer
      * @return
      */
@@ -75,6 +116,11 @@ public class FMLCommonHandler
         return channelList.get(container);
     }
 
+    /**
+     * register a channel to a mod
+     * @param container
+     * @param channelName
+     */
     public void registerChannel(ModContainer container, String channelName)
     {
         if (modChannels.containsKey(channelName))
@@ -94,6 +140,7 @@ public class FMLCommonHandler
     }
 
     /**
+     * Activate the channel for the player
      * @param player
      */
     public void activateChannel(Object player, String channel)
@@ -110,10 +157,11 @@ public class FMLCommonHandler
     }
 
     /**
+     * Deactivate the channel for the player
      * @param player
      * @param channel
      */
-    public void deactivateChannel(EntityPlayer player, String channel)
+    public void deactivateChannel(Object player, String channel)
     {
         Set<String> active = activeChannels.get(player);
 
@@ -127,6 +175,7 @@ public class FMLCommonHandler
     }
 
     /**
+     * Get the packet 250 channel registration string
      * @return
      */
     public byte[] getPacketRegistry()
@@ -151,6 +200,7 @@ public class FMLCommonHandler
     }
 
     /**
+     * Is the specified channel active for the player?
      * @param channel
      * @param player
      * @return
@@ -160,23 +210,46 @@ public class FMLCommonHandler
         return activeChannels.get(player).contains(channel);
     }
 
+    /**
+     * Get the forge mod loader logging instance (goes to the forgemodloader log file)
+     * @return
+     */
     public Logger getFMLLogger()
     {
         return Loader.log;
     }
 
+    /**
+     * Get the minecraft logger (goes to the server log file)
+     * @return
+     */
     public Logger getMinecraftLogger()
     {
         return sidedDelegate.getMinecraftLogger();
     }
 
+    /**
+     * Is this a modloader mod?
+     * @param clazz
+     * @return
+     */
     public boolean isModLoaderMod(Class<?> clazz)
     {
         return sidedDelegate.isModLoaderMod(clazz);
     }
 
+    /**
+     * Load the modloader mod
+     * @param clazz
+     * @param canonicalPath
+     * @return
+     */
     public ModContainer loadBaseModMod(Class<?> clazz, String canonicalPath)
     {
         return sidedDelegate.loadBaseModMod(clazz, canonicalPath);
     }
+    
+    public File getMinecraftRootDirectory() {
+        return sidedDelegate.getMinecraftRootDirectory();
+    }
 }

fml/common/cpw/mods/fml/common/ICraftingHandler.java

@@ -14,6 +14,8 @@
 package cpw.mods.fml.common;
 
 /**
+ * Return a crafting handler for the mod container to call
+ * 
  * @author cpw
  *
  */
@@ -21,6 +23,8 @@ public interface ICraftingHandler
 {
 
     /**
+     * The object array contains these three arguments
+     * 
      * @param player
      * @param craftedItem
      * @param craftingGrid
@@ -28,6 +32,7 @@ public interface ICraftingHandler
     void onCrafting(Object... craftingParameters);
 
     /**
+     * The object array contains these two arguments
      * @param player
      * @param smeltedItem
      */

fml/common/cpw/mods/fml/common/IFMLSidedHandler.java

@@ -1,10 +1,12 @@
 package cpw.mods.fml.common;
 
+import java.io.File;
 import java.util.logging.Logger;
 
 public interface IFMLSidedHandler
 {
     Logger getMinecraftLogger();
+    File getMinecraftRootDirectory();
     boolean isModLoaderMod(Class<?> clazz);
     ModContainer loadBaseModMod(Class<?> clazz, String canonicalPath);
     boolean isServer();

fml/common/cpw/mods/fml/common/IWorldGenerator.java

@@ -15,7 +15,27 @@ package cpw.mods.fml.common;
 
 import java.util.Random;
 
+import cpw.mods.fml.server.FMLServerHandler;
+
+/**
+ * This is called back during world generation. The {@link #generate(Random, int, int, Object...)} method passes in some additional data that 
+ * can be cast into minecraft objects.
+ * 
+ * @author cpw
+ *
+ */
 public interface IWorldGenerator
 {
+    /**
+     * Generate some world
+     * 
+     * @param random the chunk specific {@link Random} as built in {@link FMLServerHandler#onChunkPopulate(net.minecraft.src.IChunkProvider, int, int, net.minecraft.src.World, net.minecraft.src.IChunkProvider)}.
+     * @param chunkX the block X coordinate of this chunk.
+     * @param chunkZ the block Z coordinate of this chunk.
+     * @param world : additionalData[0] The minecraft {@link net.minecraft.src.World} we're generating for.
+     * @param generator : additionalData[1] The {@link net.minecraft.src.IChunkProvider} that is generating.
+     * @param chunkProvider : additionalData[2] {@link net.minecraft.src.IChunkProvider} that is requesting the world generation.
+     * 
+     */
     public void generate(Random random, int chunkX, int chunkZ, Object...additionalData);
 }

fml/common/cpw/mods/fml/common/Loader.java

@@ -32,33 +32,90 @@ import java.util.zip.ZipEntry;
 import java.util.zip.ZipFile;
 
 import cpw.mods.fml.common.toposort.ModSorter;
+import cpw.mods.fml.common.toposort.TopologicalSort;
 
+/**
+ * The loader class performs the actual loading of the mod code from disk.
+ * 
+ * <p>There are several {@link State}s to mod loading, triggered in two different stages from the FML handler code's hooks into the
+ * minecraft code.</p>
+ * 
+ * <ol>
+ * <li>LOADING. Scanning the filesystem for mod containers to load (zips, jars, directories), adding them to the {@link #modClassLoader}
+ * Scanning, the loaded containers for mod classes to load and registering them appropriately.</li>
+ * <li>PREINIT. The mod classes are configured, they are sorted into a load order, and instances of the mods are constructed.</li>
+ * <li>INIT. The mod instances are initialized. For BaseMod mods, this involves calling the load method.</li>
+ * <li>POSTINIT. The mod instances are post initialized. For BaseMod mods this involves calling the modsLoaded method.</li>
+ * <li>UP. The Loader is complete</li>
+ * <li>ERRORED. The loader encountered an error during the LOADING phase and dropped to this state instead. It will not complete
+ * loading from this state, but it attempts to continue loading before abandoning and giving a fatal error.</li>
+ * </ol>
+ * 
+ * Phase 1 code triggers the LOADING and PREINIT states. Phase 2 code triggers the INIT and POSTINIT states.
+ * 
+ * @author cpw
+ * 
+ */
 public class Loader
 {
+    private static Pattern zipJar = Pattern.compile("([^\\s]+).(zip|jar)$");
+    private static Pattern modClass = Pattern.compile("(.*/?)(mod\\_[^\\s]+).class$");
+
+    /**
+     * The state enum used to help track state progression for the loader
+     * @author cpw
+     *
+     */
     private enum State
     {
         NOINIT, LOADING, PREINIT, INIT, POSTINIT, UP, ERRORED
     };
 
+    /**
+     * The singleton instance
+     */
     private static Loader instance;
+    /**
+     * Our special logger for logging issues to. We copy various assets from the Minecraft logger to acheive a similar appearance.
+     */
     public static Logger log = Logger.getLogger("ForgeModLoader");
 
-    private static Pattern zipJar = Pattern.compile("([^\\s]+).(zip|jar)$");
-    private static Pattern modClass = Pattern.compile("(.*/?)(mod\\_[^\\s]+).class$");
 
+    /**
+     * Build information for tracking purposes.
+     */
     private static String major = "@MAJOR@";
     private static String minor = "@MINOR@";
-    private static String rev  = "@REV@";
+    private static String rev = "@REV@";
     private static String build = "@BUILD@";
     private static String mcversion = "@MCVERSION@";
 
+    /**
+     * The {@link State} of the loader
+     */
     private State state;
+    /**
+     * The class loader we load the mods into.
+     */
     private ModClassLoader modClassLoader;
+    /**
+     * The sorted list of mods.
+     */
     private List<ModContainer> mods;
+    /**
+     * A named list of mods
+     */
     private Map<String, ModContainer> namedMods;
+    /**
+     * The canonical configuration directory
+     */
     private File canonicalConfigDir;
+    /**
+     * The canonical minecraft directory
+     */
     private File canonicalMinecraftDir;
 
+    
     public static Loader instance()
     {
         if (instance == null)
@@ -68,6 +125,7 @@ public class Loader
 
         return instance;
     }
+
     private Loader()
     {
         Loader.log.setParent(FMLCommonHandler.instance().getMinecraftLogger());
@@ -90,6 +148,10 @@ public class Loader
         log.info(String.format("Forge Mod Loader version %s.%s.%s.%s for Minecraft %s loading", major, minor, rev, build, mcversion));
     }
 
+    /**
+     * Sort the mods into a sorted list, using dependency information from the containers. The sorting is performed
+     * using a {@link TopologicalSort} based on the pre- and post- dependency information provided by the mods.
+     */
     private void sortModList()
     {
         log.fine("Verifying mod dependencies are satisfied");
@@ -112,16 +174,20 @@ public class Loader
         {
             log.fine("Sorting mods into an ordered list");
             mods = sorter.sort();
-            log.fine(String.format("Mod list sorted %s", mods));
+            log.fine(String.format("Sorted mod list %s", mods));
         }
         catch (IllegalArgumentException iae)
         {
-            log.severe("A dependency cycle was detected in the input mod set so they cannot load them in order");
+            log.severe("A dependency cycle was detected in the input mod set so they cannot be loaded in order");
             log.throwing("Loader", "sortModList", iae);
             throw new LoaderException(iae);
         }
     }
 
+    /**
+     * The first mod initialization stage, performed immediately after the jar files and mod classes are loaded,
+     * {@link State#PREINIT}. The mods are configured from their configuration data and instantiated (for BaseMod mods).
+     */
     private void preModInit()
     {
         state = State.PREINIT;
@@ -140,6 +206,9 @@ public class Loader
         log.fine("Mod pre-initialization complete");
     }
 
+    /**
+     * The main mod initialization stage, performed on the sorted mod list.
+     */
     private void modInit()
     {
         state = State.INIT;
@@ -171,9 +240,25 @@ public class Loader
         log.fine("Mod post-initialization complete");
     }
 
+    /**
+     * The primary loading code
+     * 
+     * This is visited during first initialization by Minecraft to scan and load the mods 
+     * from all sources
+     * 1. The minecraft jar itself (for loading of in jar mods- I would like to remove this if possible but forge depends on it at present)
+     * 2. The mods directory with expanded subdirs, searching for mods named mod_*.class
+     * 3. The mods directory for zip and jar files, searching for mod classes named mod_*.class again
+     * 
+     * The found resources are first loaded into the {@link #modClassLoader} (always) then scanned for class resources matching the specification above.
+     * 
+     * If they provide the {@link Mod} annotation, they will be loaded as "FML mods", which currently is effectively a NO-OP.
+     * If they are determined to be {@link net.minecraft.src.BaseMod} subclasses they are loaded as such.
+     * 
+     * Finally, if they are successfully loaded as classes, they are then added to the available mod list.
+     */
     private void load()
     {
-        File minecraftDir = new File(".");
+        File minecraftDir = FMLCommonHandler.instance().getMinecraftRootDirectory();
         File modsDir = new File(minecraftDir, "mods");
         File configDir = new File(minecraftDir, "config");
         String canonicalModsPath;
@@ -406,6 +491,10 @@ public class Loader
         return instance().mods;
     }
 
+    /**
+     * Called from the hook to start mod loading. We trigger the {@link #load()} and {@link #preModInit()} phases here.
+     * Finally, the mod list is frozen completely and is consider immutable from then on.
+     */
     public void loadMods()
     {
         state = State.NOINIT;
@@ -418,6 +507,9 @@ public class Loader
         mods = Collections.unmodifiableList(mods);
     }
 
+    /**
+     * Complete the initialization of the mods {@link #initializeMods()} and {@link #postModInit()} and mark ourselves up and ready to run.
+     */
     public void initializeMods()
     {
         modInit();
@@ -426,10 +518,17 @@ public class Loader
         log.info(String.format("Forge Mod Loader load complete, %d mods loaded", mods.size()));
     }
 
+    /**
+     * Query if we know of a mod named modname
+     * 
+     * @param modname
+     * @return
+     */
     public static boolean isModLoaded(String modname)
     {
         return instance().namedMods.containsKey(modname);
     }
+
     /**
      * @return
      */

fml/common/cpw/mods/fml/common/Mod.java

@@ -16,6 +16,12 @@ package cpw.mods.fml.common;
 import java.lang.annotation.Retention;
 import java.lang.annotation.RetentionPolicy;
 
+/**
+ * A possible future way to indicate mods to the system is to use an annotation style
+ * 
+ * @author cpw
+ *
+ */
 @Retention(RetentionPolicy.RUNTIME)
 public @interface Mod
 {

fml/common/cpw/mods/fml/common/ModClassLoader.java

@@ -18,6 +18,13 @@ import java.net.MalformedURLException;
 import java.net.URL;
 import java.net.URLClassLoader;
 
+/**
+ * A simple delegating class loader used to load mods into the system
+ * 
+ * 
+ * @author cpw
+ *
+ */
 public class ModClassLoader extends URLClassLoader
 {
 

fml/common/cpw/mods/fml/common/ModContainer.java

@@ -15,34 +15,145 @@ package cpw.mods.fml.common;
 
 import java.util.List;
 
-
+/**
+ * The container that wraps around mods in the system.
+ * <p>The philosophy is that individual mod implementation technologies should not impact the actual loading and management
+ * of mod code. This interface provides a mechanism by which we can wrap actual mod code so that the loader and other
+ * facilities can treat mods at arms length.</p> 
+ *
+ * @author cpw
+ *
+ */
 
 public interface ModContainer
 {
+    /**
+     * The enclosed mod wants to be called during pre-initialization.
+     * @return
+     */
     boolean wantsPreInit();
+    /**
+     * The enclosed mod wants to be called during post-initialization.
+     * @return
+     */
     boolean wantsPostInit();
+    /**
+     * Called when pre-initialization occurs.
+     */
     void preInit();
+    /**
+     * Called when main initialization occurs.
+     */
     void init();
+    /**
+     * Called when post-initialization occurs.
+     */
     void postInit();
+    /**
+     * The name of the mod
+     * @return
+     */
     String getName();
+    /**
+     * A tick has started
+     */
     void tickStart();
+    /**
+     * A tick has ended
+     */
     void tickEnd();
+    /**
+     * Does this mod match the supplied mod?
+     * @param mod
+     * @return
+     */
     boolean matches(Object mod);
+    /**
+     * The source of this mod: usually the file name on the file system
+     * @return
+     */
     String getSource();
+    /**
+     * The actual mod object itself
+     * @return
+     */
     Object getMod();
+    /**
+     * Does this mod want to generate world data.
+     * @return
+     */
     boolean generatesWorld();
+    /**
+     * The world generator for this mod.
+     * @return
+     */
     IWorldGenerator getWorldGenerator();
+    /**
+     * Lookup the fuel value for the supplied item/damage with this mod.
+     * @param itemId
+     * @param itemDamage
+     * @return
+     */
     int lookupFuelValue(int itemId, int itemDamage);
+    /**
+     * This mod wants to be notified when an object is picked up.
+     * @return
+     */
     boolean wantsPickupNotification();
+    /**
+     * The pickup notifier for this mod.
+     * @return
+     */
     IPickupNotifier getPickupNotifier();
+    /**
+     * This mod wants to have special dispenser handling.
+     * @return
+     */
     boolean wantsToDispense();
+    /**
+     * The dispensing handler.
+     * @return
+     */
     IDispenseHandler getDispenseHandler();
+    /**
+     * This mod wants notification of crafting and/or smelting events.
+     * @return
+     */
     boolean wantsCraftingNotification();
+    /**
+     * The crafting and smelting handler for this mod.
+     * @return
+     */
     ICraftingHandler getCraftingHandler();
+    /**
+     * The strong dependencies of this mod. If the named mods in this list are not present, the game will abort.
+     * @return
+     */
     List<String> getDependencies();
+    /**
+     * Get a list of mods to load before this one. The special value "*" indicates to load <i>after</i> all other mods (except other "*" mods).
+     * @return
+     */
     List<String> getPreDepends();
+    /**
+     * Get a list of mods to load after this one. The special value "*" indicates to load <i>before</i> all other mods (except other "*" mods).
+     * @return
+     */
     List<String> getPostDepends();
+    /**
+     * This mod wants packets from the client, and wants them handled by FML.
+     * @return
+     */
     boolean wantsNetworkPackets();
+    /**
+     * The network handler for this mod.
+     * @return
+     */
     INetworkHandler getNetworkHandler();
+    /**
+     * Does this mod own this channel?
+     * @param channel
+     * @return
+     */
     boolean ownsNetworkChannel(String channel);
 }

fml/common/cpw/mods/fml/common/ReflectionHelper.java

@@ -13,7 +13,12 @@
 package cpw.mods.fml.common;
 
 import java.lang.reflect.Field;
-
+/**
+ * Some reflection helper code.
+ * 
+ * @author cpw
+ *
+ */
 public class ReflectionHelper
 {
     @SuppressWarnings("unchecked")

fml/eclipse/.gitignore

@@ -1,2 +1,6 @@
 /*/bin
 /*/.settings/org.eclipse.ltk.core.refactoring.prefs
+*.cdt.*
+*.ajdt.*
+/.log
+*.m2e.*

fml/eclipse/.metadata/.plugins/org.eclipse.core.runtime/.settings/org.eclipse.jdt.core.prefs

@@ -1,33 +1,43 @@
-#Wed Apr 04 21:53:27 PDT 2012
-org.eclipse.jdt.core.formatter.brace_position_for_method_declaration=next_line
-org.eclipse.jdt.core.formatter.insert_new_line_before_catch_in_try_statement=insert
-org.eclipse.jdt.core.compiler.compliance=1.6
-org.eclipse.jdt.core.compiler.problem.staticAccessReceiver=ignore
-org.eclipse.jdt.core.formatter.insert_new_line_before_else_in_if_statement=insert
+eclipse.preferences.version=1
+org.eclipse.jdt.core.builder.resourceCopyExclusionFilter=
+org.eclipse.jdt.core.codeComplete.argumentPrefixes=
+org.eclipse.jdt.core.codeComplete.argumentSuffixes=
+org.eclipse.jdt.core.codeComplete.fieldPrefixes=
+org.eclipse.jdt.core.codeComplete.fieldSuffixes=
+org.eclipse.jdt.core.codeComplete.localPrefixes=
+org.eclipse.jdt.core.codeComplete.localSuffixes=
+org.eclipse.jdt.core.codeComplete.staticFieldPrefixes=
+org.eclipse.jdt.core.codeComplete.staticFieldSuffixes=
+org.eclipse.jdt.core.codeComplete.staticFinalFieldPrefixes=
+org.eclipse.jdt.core.codeComplete.staticFinalFieldSuffixes=
+org.eclipse.jdt.core.codeComplete.visibilityCheck=enabled
 org.eclipse.jdt.core.compiler.codegen.inlineJsrBytecode=enabled
+org.eclipse.jdt.core.compiler.codegen.targetPlatform=1.6
+org.eclipse.jdt.core.compiler.compliance=1.6
+org.eclipse.jdt.core.compiler.problem.missingSerialVersion=ignore
+org.eclipse.jdt.core.compiler.problem.rawTypeReference=ignore
+org.eclipse.jdt.core.compiler.problem.staticAccessReceiver=ignore
+org.eclipse.jdt.core.compiler.problem.uncheckedTypeOperation=ignore
 org.eclipse.jdt.core.compiler.problem.unusedImport=ignore
 org.eclipse.jdt.core.compiler.problem.unusedLocal=ignore
-org.eclipse.jdt.core.formatter.brace_position_for_anonymous_type_declaration=next_line
-org.eclipse.jdt.core.formatter.keep_imple_if_on_one_line=true
-org.eclipse.jdt.core.formatter.brace_position_for_block_in_case=next_line
-org.eclipse.jdt.core.formatter.tabulation.char=space
-eclipse.preferences.version=1
-org.eclipse.jdt.core.compiler.problem.uncheckedTypeOperation=ignore
-org.eclipse.jdt.core.formatter.brace_position_for_switch=next_line
-org.eclipse.jdt.core.formatter.brace_position_for_annotation_type_declaration=next_line
-org.eclipse.jdt.core.formatter.lineSplit=160
-org.eclipse.jdt.core.builder.resourceCopyExclusionFilter=
-org.eclipse.jdt.core.formatter.insert_new_line_before_finally_in_try_statement=insert
-org.eclipse.jdt.core.compiler.problem.rawTypeReference=ignore
-org.eclipse.jdt.core.formatter.brace_position_for_block=next_line
-org.eclipse.jdt.core.codeComplete.visibilityCheck=enabled
-org.eclipse.jdt.core.formatter.use_tabs_only_for_leading_indentations=true
 org.eclipse.jdt.core.compiler.problem.unusedPrivateMember=ignore
-org.eclipse.jdt.core.formatter.indent_switchstatements_compare_to_switch=true
-org.eclipse.jdt.core.formatter.brace_position_for_type_declaration=next_line
-org.eclipse.jdt.core.formatter.brace_position_for_constructor_declaration=next_line
-org.eclipse.jdt.core.compiler.problem.missingSerialVersion=ignore
-org.eclipse.jdt.core.formatter.brace_position_for_enum_declaration=next_line
-org.eclipse.jdt.core.compiler.codegen.targetPlatform=1.6
-org.eclipse.jdt.core.formatter.brace_position_for_enum_constant=next_line
 org.eclipse.jdt.core.compiler.source=1.6
+org.eclipse.jdt.core.formatter.brace_position_for_annotation_type_declaration=next_line
+org.eclipse.jdt.core.formatter.brace_position_for_anonymous_type_declaration=next_line
+org.eclipse.jdt.core.formatter.brace_position_for_block=next_line
+org.eclipse.jdt.core.formatter.brace_position_for_block_in_case=next_line
+org.eclipse.jdt.core.formatter.brace_position_for_constructor_declaration=next_line
+org.eclipse.jdt.core.formatter.brace_position_for_enum_constant=next_line
+org.eclipse.jdt.core.formatter.brace_position_for_enum_declaration=next_line
+org.eclipse.jdt.core.formatter.brace_position_for_method_declaration=next_line
+org.eclipse.jdt.core.formatter.brace_position_for_switch=next_line
+org.eclipse.jdt.core.formatter.brace_position_for_type_declaration=next_line
+org.eclipse.jdt.core.formatter.indent_switchstatements_compare_to_switch=true
+org.eclipse.jdt.core.formatter.insert_new_line_before_catch_in_try_statement=insert
+org.eclipse.jdt.core.formatter.insert_new_line_before_else_in_if_statement=insert
+org.eclipse.jdt.core.formatter.insert_new_line_before_finally_in_try_statement=insert
+org.eclipse.jdt.core.formatter.keep_imple_if_on_one_line=true
+org.eclipse.jdt.core.formatter.lineSplit=160
+org.eclipse.jdt.core.formatter.tabulation.char=space
+org.eclipse.jdt.core.formatter.use_tabs_only_for_leading_indentations=true
+org.eclipse.jdt.core.timeoutForParameterNameFromAttachedJavadoc=50

fml/eclipse/.metadata/.plugins/org.eclipse.core.runtime/.settings/org.eclipse.ui.ide.prefs

@@ -1,9 +1,9 @@
-#Wed Apr 04 21:31:17 PDT 2012
 IMPORT_FILES_AND_FOLDERS_MODE=prompt
 IMPORT_FILES_AND_FOLDERS_VIRTUAL_FOLDER_MODE=prompt
-SAVE_ALL_BEFORE_BUILD=true
-eclipse.preferences.version=1
-tipsAndTricks=true
-platformState=1322720251962
-quickStart=false
 PROBLEMS_FILTERS_MIGRATE=true
+SAVE_ALL_BEFORE_BUILD=true
+TASKS_FILTERS_MIGRATE=true
+eclipse.preferences.version=1
+platformState=1333336227259
+quickStart=true
+tipsAndTricks=true

fml/server/cpw/mods/fml/server/FMLServerHandler.java

@@ -12,6 +12,8 @@
  */
 package cpw.mods.fml.server;
 
+import java.io.File;
+import java.io.IOException;
 import java.io.UnsupportedEncodingException;
 import java.util.ArrayList;
 import java.util.Random;
@@ -37,14 +39,43 @@ import cpw.mods.fml.common.IFMLSidedHandler;
 import cpw.mods.fml.common.Loader;
 import cpw.mods.fml.common.ModContainer;
 
+/**
+ * Handles primary communication from hooked code into the system
+ * 
+ * The FML entry point is {@link #onPreLoad(MinecraftServer)} called from {@link MinecraftServer}
+ * 
+ * Obfuscated code should focus on this class and other members of the "server" (or "client") code
+ * 
+ * The actual mod loading is handled at arms length by {@link Loader}
+ * 
+ * It is expected that a similar class will exist for each target environment: Bukkit and Client side.
+ * 
+ * It should not be directly modified.
+ * 
+ * @author cpw
+ *
+ */
 public class FMLServerHandler implements IFMLSidedHandler
 {
+    /**
+     * The singleton
+     */
     private static final FMLServerHandler INSTANCE = new FMLServerHandler();
 
+    /**
+     * A reference to the server itself
+     */
     private MinecraftServer server;
 
+    /**
+     * A handy list of the default overworld biomes
+     */
     private BiomeGenBase[] defaultOverworldBiomes;
 
+    /**
+     * Called to start the whole game off from {@link MinecraftServer#startServer}
+     * @param minecraftServer
+     */
     public void onPreLoad(MinecraftServer minecraftServer)
     {
         server = minecraftServer;
@@ -53,31 +84,59 @@ public class FMLServerHandler implements IFMLSidedHandler
         Loader.instance().loadMods();
     }
 
+    /**
+     * Called a bit later on during server initialization to finish loading mods
+     */
     public void onLoadComplete()
     {
         Loader.instance().initializeMods();
     }
 
+    /**
+     * Every tick just before world and other ticks occur
+     */
     public void onPreTick()
     {
         FMLCommonHandler.instance().gameTickStart();
     }
 
+    /**
+     * Every tick just after world and other ticks occur
+     */
     public void onPostTick()
     {
         FMLCommonHandler.instance().gameTickEnd();
     }
 
+    /**
+     * Get the server instance
+     * @return
+     */
     public MinecraftServer getServer()
     {
         return server;
     }
 
+    /**
+     * Get a handle to the server's logger instance
+     */
     public Logger getMinecraftLogger()
     {
         return MinecraftServer.field_6038_a;
     }
 
+    /**
+     * Called from ChunkProviderServer when a chunk needs to be populated
+     * 
+     * To avoid polluting the worldgen seed, we generate a new random from the world seed and
+     * generate a seed from that
+     * 
+     * @param chunkProvider
+     * @param chunkX
+     * @param chunkZ
+     * @param world
+     * @param generator
+     */
     public void onChunkPopulate(IChunkProvider chunkProvider, int chunkX, int chunkZ, World world, IChunkProvider generator)
     {
         Random fmlRandom = new Random(world.func_22079_j());
@@ -94,6 +153,13 @@ public class FMLServerHandler implements IFMLSidedHandler
         }
     }
 
+    /**
+     * Called from the furnace to lookup fuel values
+     * 
+     * @param itemId
+     * @param itemDamage
+     * @return
+     */
     public int fuelLookup(int itemId, int itemDamage)
     {
         int fv = 0;
@@ -106,11 +172,17 @@ public class FMLServerHandler implements IFMLSidedHandler
         return fv;
     }
 
+    /**
+     * Is the offered class and instance of BaseMod and therefore a ModLoader mod?
+     */
     public boolean isModLoaderMod(Class<?> clazz)
     {
         return BaseMod.class.isAssignableFrom(clazz);
     }
 
+    /**
+     * Load the supplied mod class into a mod container
+     */
     public ModContainer loadBaseModMod(Class<?> clazz, String canonicalPath)
     {
         @SuppressWarnings("unchecked")
@@ -118,6 +190,11 @@ public class FMLServerHandler implements IFMLSidedHandler
         return new ModLoaderModContainer(bmClazz, canonicalPath);
     }
 
+    /**
+     * Called to notify that an item was picked up from the world
+     * @param entityItem
+     * @param entityPlayer
+     */
     public void notifyItemPickup(EntityItem entityItem, EntityPlayer entityPlayer)
     {
         for (ModContainer mod : Loader.getModList())
@@ -129,6 +206,12 @@ public class FMLServerHandler implements IFMLSidedHandler
         }
     }
 
+    /**
+     * Raise an exception
+     * @param exception
+     * @param message
+     * @param stopGame
+     */
     public void raiseException(Throwable exception, String message, boolean stopGame)
     {
         FMLCommonHandler.instance().getFMLLogger().throwing("FMLHandler", "raiseException", exception);
@@ -136,13 +219,15 @@ public class FMLServerHandler implements IFMLSidedHandler
     }
 
     /**
-     * @param p_21036_1_
-     * @param var13
-     * @param var15
-     * @param var17
-     * @param var9
-     * @param var10
-     * @param var12
+     * Attempt to dispense the item as an entity other than just as a the item itself
+     * 
+     * @param world
+     * @param x
+     * @param y
+     * @param z
+     * @param xVelocity
+     * @param zVelocity
+     * @param item
      * @return
      */
     public boolean tryDispensingEntity(World world, double x, double y, double z, byte xVelocity, byte zVelocity, ItemStack item)
@@ -167,6 +252,7 @@ public class FMLServerHandler implements IFMLSidedHandler
     }
 
     /**
+     * Build a list of default overworld biomes
      * @return
      */
     public BiomeGenBase[] getDefaultOverworldBiomes()
@@ -192,6 +278,12 @@ public class FMLServerHandler implements IFMLSidedHandler
         return defaultOverworldBiomes;
     }
 
+    /**
+     * Called when an item is crafted
+     * @param player
+     * @param craftedItem
+     * @param craftingGrid
+     */
     public void onItemCrafted(EntityPlayer player, ItemStack craftedItem, IInventory craftingGrid)
     {
         for (ModContainer mod : Loader.getModList())
@@ -203,6 +295,12 @@ public class FMLServerHandler implements IFMLSidedHandler
         }
     }
 
+    /**
+     * Called when an item is smelted
+     * 
+     * @param player
+     * @param smeltedItem
+     */
     public void onItemSmelted(EntityPlayer player, ItemStack smeltedItem)
     {
         for (ModContainer mod : Loader.getModList())
@@ -214,6 +312,13 @@ public class FMLServerHandler implements IFMLSidedHandler
         }
     }
 
+    /**
+     * Called when a chat packet is received
+     * 
+     * @param chat
+     * @param player
+     * @return true if you want the packet to stop processing and not echo to the rest of the world
+     */
     public boolean handleChatPacket(Packet3Chat chat, EntityPlayer player)
     {
         for (ModContainer mod : Loader.getModList())
@@ -227,6 +332,11 @@ public class FMLServerHandler implements IFMLSidedHandler
         return false;
     }
 
+    /**
+     * Called when a packet 250 packet is received from the player
+     * @param packet
+     * @param player
+     */
     public void handlePacket250(Packet250CustomPayload packet, EntityPlayer player)
     {
         if ("REGISTER".equals(packet.field_44005_a) || "UNREGISTER".equals(packet.field_44005_a))
@@ -244,6 +354,7 @@ public class FMLServerHandler implements IFMLSidedHandler
     }
 
     /**
+     * Handle register requests for packet 250 channels
      * @param packet
      */
     private void handleClientRegistration(Packet250CustomPayload packet, EntityPlayer player)
@@ -274,6 +385,11 @@ public class FMLServerHandler implements IFMLSidedHandler
         }
     }
 
+    /**
+     * Handle a login
+     * @param loginPacket
+     * @param networkManager
+     */
     public void handleLogin(Packet1Login loginPacket, NetworkManager networkManager)
     {
         for (ModContainer mod : Loader.getModList())
@@ -291,15 +407,31 @@ public class FMLServerHandler implements IFMLSidedHandler
         networkManager.func_745_a(packet);
     }
 
+    /**
+     * Are we a server?
+     */
     @Override
     public boolean isServer()
     {
         return true;
     }
 
+    /**
+     * Are we a client?
+     */
     @Override
     public boolean isClient()
     {
         return false;
     }
+
+    @Override
+    public File getMinecraftRootDirectory()
+    {
+        try {
+            return server.func_6009_a(".").getCanonicalFile();
+        } catch (IOException ioe) {
+            return new File(".");
+        }
+    }
 }

fml/server/cpw/mods/fml/server/ModLoaderModContainer.java

@@ -51,11 +51,13 @@ public class ModLoaderModContainer implements ModContainer
         this.modSource = modSource;
     }
 
+    @Override
     public boolean wantsPreInit()
     {
         return true;
     }
 
+    @Override
     public boolean wantsPostInit()
     {
         return true;
@@ -310,6 +312,10 @@ public class ModLoaderModContainer implements ModContainer
         isTicking = enable;
     }
 
+    /**
+     * Find all the BaseMods in the system 
+     * @return
+     */
     public static List<BaseMod> findAll()
     {
         ArrayList<BaseMod> modList = new ArrayList<BaseMod>();
@@ -367,36 +373,24 @@ public class ModLoaderModContainer implements ModContainer
         return mod;
     }
 
-    /* (non-Javadoc)
-     * @see cpw.mods.fml.common.ModContainer#wantsToDispense()
-     */
     @Override
     public boolean wantsToDispense()
     {
         return true;
     }
 
-    /* (non-Javadoc)
-     * @see cpw.mods.fml.common.ModContainer#getDispenseHandler()
-     */
     @Override
     public IDispenseHandler getDispenseHandler()
     {
         return mod;
     }
 
-    /* (non-Javadoc)
-     * @see cpw.mods.fml.common.ModContainer#wantsCraftingNotification()
-     */
     @Override
     public boolean wantsCraftingNotification()
     {
         return true;
     }
 
-    /* (non-Javadoc)
-     * @see cpw.mods.fml.common.ModContainer#getCraftingHandler()
-     */
     @Override
     public ICraftingHandler getCraftingHandler()
     {
@@ -442,9 +436,7 @@ public class ModLoaderModContainer implements ModContainer
             }
         }
     }
-    /* (non-Javadoc)
-     * @see cpw.mods.fml.common.ModContainer#getDependencies()
-     */
+
     @Override
     public List<String> getDependencies()
     {