1.2.x Documentation

Table of Contents:


Minecrafter is a easy to use mod manager for Minecraft.

Instead of providing a basic mod manager which only merges texture packs into the minecraft.jar, Minecrafter allows you easily install mods non-destructively and Mix’n’Match different mods to suit your style. You can mix different images files, and even different tiles in files like terrain.png and get the right mix of style you crave, without needing to deal with JAR repackaging and other boring stuff. Or, if you just want a basic mod launcher that doesn’t replace your minecraft.jar, then Minecrafter can do that too!

This document describes the features of Minecrafter in detail. For a tutorial on how to use Minecrafter, click here

System Requirements

  • Should work on any platform that Minecraft can run on, bar having JRE 1.5 or higher (Tested on Windows 7 64-bit, Mac OS X 10.6.2 64-bit and Ubuntu 10.10)
  • JRE 1.5 or higher (grab the latest version from here)
  • Minecraft Alpha (tested on v1.2.3_04)
  • Some mods – currently v1.2.0 supports only mods that replace files in minecraft.jar
  • Main Form

    Start Up

    Start up Minecrafter by running Minecrafter.exe. The main screen should look like below when you start it for the first time:

    The large combo box contains the mod packages you have in the data folder. Obviously from your first start up, you’ll need to create your own mod packages or download some. A Mod Package is a collection of mods that have been merged together based on a set of instructions. Think of it as a recipe to a dish. A mod package contains all the separate ingredients plus a recipe that will make the final dish – in our case, thats the final mod that will be placed into Minecraft.jar. Mods, on the other hand, are archive files containing the mod data that you would normally replace in minecraft.jar.


    Remember Minecraft Launcher path

    Minecrater has a built in launcher to launch Minecraft, but you’ll need to specify where you placed your Minecraft program. Once you’ve specified it’s location, whether the check box is checked, it will save the last location in it’s configuration file.

    Place your Minecraft.exe, Minecraft.app in the same folder as Minecrafter and Minecrafter will use this to launch Minecraft.

    Always Delete META-INF

    With this option checked, when building the final JAR, Minecrafter will always delete META-INF files. Not too useful in mod packages where you can explicitly delete META-INF files, but extremely useful when quick launching mods. For example: having this option checked when you quick launch Autocart will not black screen/freeze your game.

    Enable Crash Detection

    Crash detection will attempt to fix any problems that occur during lauching Minecraft. If Minecrafter ever crashes during launching, just run Minecrafter again and it will attempt to fix itself. In some circumstances it can’t, but if it ever does – then there is something seriously wrong 😮

    If the crash detector keeps bugging you everytime to launch Minecrafter saying it detected a crash (when it hasn’t), uncheck this option to turn it off.

    Use pre-compiled Mod Package

    Minecrafter manually builds the final minecraft.jar every time you launch Minecraft from inside the program. If you don’t want Minecrafter to rebuild the mod everytime you launch Minecraft, check this box, and the next time you launch Minecraft, it will save the compiled minecraft.jar in a temp folder and use that the next time you launch Minecraft with the mod package selected. This should improve load times by a few seconds, depending how fast your computer is.

    Remember Last Launch Type **new in 1.2.0!

    One of the new features of 1.2.0 is the new launch types. If you use a certain launch type frequently, check this option and Minecrafter will remember the last launch type you’ve used, and will automatically use that type the next type you launch a mod package.

    Enable HD Fix

    Thanks to Xau open sourcing his HD Texture Fix, I’ve now integrated it into my program. This is especially useful if you are switching between different sized textures, previously you’d need to repatch depending on texture size. If for any reason Minecraft does not load, try unchecking this option to see if it will load, but be warned, any texture size larger than 32×32 will black screen Minecraft without this fix. Unchecking this will disable all additional patcher options.

    Launch External Program

    This field allows you to launch an external program when Minecraft launches. You specify a file location, and it will run like any command entered in command prompt/terminal.

    Additional Launch Flags

    This field allows you to specify additional flags which will be added into the command which is used to launch Minecraft. Useful for tweaking JVM options. e.g. -Xmx1024m

    Clear Temp Button

    Clear the temp folder if you have a few crashes during Minecraft launching or made changes you your mod packages.

    Open Minecrafter Folder

    A shortcut for opening the Minecrafter folder. Great for easily grabbing packages or checking error.log

    Launch Minecraft

    When you select a mod package, you will have the option to launch Minecraft. This is the button to launch Minecraft with your mod package built in. New in 1.2.0, you have the option of new launch types!

    Temporary Launch Type

    This was the default launch type in 1.1.x and older. This will backup the current minecraft.jar and replace it with a new JAR with our mod package applied to it. Once you’ve finished playing, Minecrafter will automatically restore the JAR back to its previous state. This is the recommended launch type as it allows you to use any number of mods without the worry of needing to backup and maintain copies of minecraft.jar

    Permanent Launch Type **New in 1.2.0!

    This launch type will basically do what temporary does, except that it will not restore minecraft.jar to its previous state. That means you can apply a mod package and not require Minecrafter to play. Warning: No backups are made, so it’s up to you to restore minecraft.jar to its original state if you want to use another mod package.

    Semi-Permanent Launch Type **New in 1.2.0!

    A mix between temporary and permanent. What this allows is a permanent-like install (i.e. launch from Minecrafter, and launch from the Minecraft launcher and the mod installation is still there), but launching new packages will be based on the previous state of minecraft.jar.

    This might be a bit confusing for some, so I’ll explain exactly what happens. On a semi-permanent launch, Minecrafter will compile the JAR as usual, but but once that’s done, it will add the source minecraft.jar into minecraft.jar. Everything still works out as expected, but now you have  a copy of minecraft.jar inside minecraft.jar which holds the older version of minecraft.jar without the mods applied. When you select a new mod package to launch, Minecrafter will look for a nested minecraft.jar file in minecraft.jar, and if exists, it will apply the mod package to the nested minecraft.jar.

    So, in the end you don’t need to launch Minecrafter everytime you want to play with a particular mod package, but you have the power to revert the changes and re-install a different mod package on top of the original minecraft.jar.

    Note: You can restore minecraft.jar to its original state by performing a temporary launch using any package.

    Mod Quick Launch

    Quick mod launching allows you to easily and quickly launch one mod from file or a folder without the need of creating a mod package. This feature gives you the power to easily test out mods you’ve downloaded without the commitment.

    Note that with the introduction of new launch types, quick launching always uses temporary launching.

    Quick Launching is a 2 step process:

    Open Mod

    When you click the Quick Mod Launch button, you are offered an option of opening a mod from file or from folder. From File means opening an archive (zip, rar) containing the mod. From Folder means opening a mod that contains the files of a mod. The latter option is useful for modders in particular who want to quickly test changes in Minecraft without needing to zip up their files.

    Selecting either option will open a dialog requesting you to select the mod you want to load.

    Select a Base Folder

    Selecting a base folder means at what point do the contents start. Sometimes, mods are packed in a non-traditional way, and you must tell Minecrafter how the files are structured so Minecrafter can properly replace the correct files. Take for example the Quandry texture pack. It has a folder called Quandry_August which contains the files we need.

    Most mods however don’t have these folders to worry about, so it’s fine to select “No Base Folder” and press OK.

    Export **New in 1.2.0!

    NOTE: This feature is not available by default. You’ll need to download the export packages (check the download side bar) and extract them into the Minecrafter data folder.

    Export gives you the ability to export mod packages into “Executable Mod Packages”. These are basically packages which are wrapped into a JAR, and perform the Minecrafter launch mechanism when executed. This is a great tool for modders who want to distribute their mod without their users running into problems installing mods.

    By default, running the executable mod package will perform the temporary launch mechanism. To customize the launch type, enable CAPS LOCK, and run the mod package. Instead of the automatic launching, the launch options menu will show up. This will allow you to choose a different launch type.

    Note: In Linux, the CAPS LOCK detection does not work, so you must launch the JAR via command line with “-0” as an additional command line argument.

    Mod Package Editor

    You can create a new mod package by clicking on the “New Mod Package…” button. This will load the Mod Package Editor:

    On the top left corner of the form we see a textbox to specify the mod package name. This is the name that will be shown on the start up form when selecting a mod package.

    Mods List Box

    Right below the textbox is the mods list. The mods list will always have minecraft.jar preloaded for you as a base mod. This means as well as having mods that replace the default files, you can also keep specific files from minecraft.jar if you ever want to

    To the right of the mods list box is 4 buttons, each will be described separately:

    Add Mod

    Adding mods into the mod package. As of v1.1.1, you now have the option of adding RAR archives as well as ZIP files. Also, you can add folders, which work the same as archives.

    A new experimental option is to add files which are not archives. You can add any image file (like terrain.png) or class files into the mod package and they will be treated like archives with one file. Currently, there is no support for defining folders (e.g. cannot place items.png into the GUI folder), but this feature should be added into 1.1.2.

    Remove Mod

    This button removes the current mod selected. All selections made for the selected mod will be deleted as well. You cannot remove minecraft.jar.

    Increase Mod Priority (Move up)

    Mod Priority is importance of a mod when merging files. A mod with highest priority will have it’s files kept during compilation (What we call “active”), while lower priority mods will have it’s files replaced only if a higher priority mod has a file of the same name.

    for example:

    • Mod #1
      • terrain.png
      • gui/items.png
    • Mod #2
      • terrain.png
      • snow.png
    • Mod #3
      • terrain.png
      • snow.png

    Assuming highest priority to the first on the list, Mod #1 will not have it’s files replaced by Mod #2 or Mod #3 (unless you explicity do so). But Mod #2’s snow.png will not be replaced by Mod #3 because it has a higher priority.

    Decrease Mod Priority (Move down)

    The opposite of Increasing Mod Priority. But, you cannot move a mod to have a priority lower than minecraft.jar. minecraft.jar cannot be deleted or moved for that matter.

    Mod Files Grid

    When you select a mod, a grid will be populated with all the files contained in the archive. From there, each file is color coded based on how the mods are arranged and explicity set file states. File states give you an indication whether a file will be present when the mod package is compiled to play. The legend on the bottom left shows which color relates to each file state.

    To explicity change a file state, you can double click on the file and a confirmation box will be shown confirming the change to a different state. Each state only has one other state it can change to.


    This means the file will be present in the compiled JAR, and it is the default state for all files in the highest priority mod. You can change an “active” file state to a “delete” file state. Another way which yields the same result (which is recommended) is to set the same file lower priority mod to “priority” state.


    This file has been replaced by a file of the same name in a different mod that has a higher priority. If you want this file to be active, you can double click the file and change it to “priority” state.


    Files that are priority means that they will never be replaced by a mod of a higher priority. This state is useful for picking out one or two files in a lower priority mod. You can double click the file to remove the priority state.


    You can mark files to be deleted. This is useful for mods which modify the functionality of Minecraft, and need to delete files in META-INF.

    **Careful! Don’t get this confused with “priority”. If you don’t want a mod to be using a particular file, go to the mod that you want to be used and mark the files as “priority”. Deleting files should only be used for removing unnecessary files in the final JAR. Deleting a main file (e.g terrain.png), will delete all copies, so there won’t be a trace of that file in the final JAR (a leading cause of black screens / freezes during Minecraft startup)

    Filter Box

    A handy filter text box is provided right above the file grid. It will filter based on the name of the file, regardless of position of the occurrence. You can use the asterisk prefix (*) to filter by file state. So type in “*i” to filter inactive state files. The text state is as shown on the legend.

    Filtering file states have been simplified to two characters, *a for active filtering, *i for inactive, *d for delete and *p for priority.

    File Alias Area **new in v.1.1.3

    A file alias is just a fancy name for a renamed file. You can rename files by just entering a new name in the textbox. You can even add folders into the file name, and Minecrafter will create the folders for you when compiling the final JAR. Below the textbox is a label which shows the original file name. This only appears when you’ve renamed a file.

    Image preview

    If a file you’ve selected in the file grid is an image, you can see a preview of that image in the Image Preview Box. TODO: Click on the image preview area to view full size

    Open Button **New in 1.2.0

    The open button allows you to view the file from outside the program – i.e. the file is extracted and can be viewed using your default file viewer. There are two types: You can view the file, where the file is extracted to a temp folder and opened using the default file viewer (e.g. view image files in a larger size). The next is Save As…, where you can save the file to a specified location.

    Blocks Button

    The blocks button is only active for 2 files – terrain.png and gui/items.png. This button will load up the Block Selector form, which allows you to pick individual blocks from each mod, which will then be compiled into a final image which will be used when playing Minecraft. See the “Block Selector Form” section for more details.

    Base Folder Button

    Sometimes mods are packaged in a way that does not directly map to the file structure of minecraft.jar. Most of the time, it may just be one folder, but why re-zip the mod yourself? By clicking on this button, a dialog will popup with all the folders in the mod archive.

    By selecting the correct base folder, you can get the Package Editor to correctly detect the files.

    Save / Save As…

    These buttons save the Mod Package. The Mod Package will bundle all mods you’ve included plus metadata containing the specific selections made. You must specify a Mod Package Name before you can save.

    Block Selector

    The Block Selector Form allows you to easily select individual blocks from an image without requiring any graphics tools. Each block can be selected and marked as “active” in a similar fashion to that of mod files. The base image is the mod with the highest priority, and also having that file. So any selections made, should be made on lower priority mods.

    Image Area

    The image area allows you to select individual blocks and view the selected and currently allocated blocks. Double clicking a block will explicitly set that mod’s block as priority, and will appear in the final image. Double click the block again to remove the selection. Reserved blocks are blocks that have been selected from another mod and appear in red (by default). You can override this by double clicking the reserved block. Blocks without any block overlay are currently unallocated. Note that the unallocated blocks visible on the form are not necessarily the blocks in the final image.

    Selected / Allocated Block Preview

    When you select a block, the Minecrafter will automatically determine what will be the final image block for that selection. Depending on how you’ve arranged your mods, the selected mod block could be the same as the allocated block, or different.

    View Final Image Button

    Clicking this button will show you the final image where all the selected blocks are merged with the base image. This will be exactly what you will be playing in Minecraft.

    Background Color Button

    If the image uses transparency, then you can select a background color to make the image easier to see.

    Copy Block Selections **new in v1.1.3

    This will copy the active block selections from the mod’s image. It will not copy inactive selections from other mods.

    Paste Block Selections **new in v1.1.3

    This will paste block selections stored in memory to the active mod. If there are conflicting block selections, Minecrafter will ask you to confirm your actions.

    Command Line Arguments

    New in v1.1.1, you can now launch mod packages and mods from command line, allowing you to create shortcuts. The general format is like so:

    java -jar Minecrafter[version].jar [options] [package/mod] [index/file path]

    Launch Mod Package

    java -jar Minecrafter[version].jar -package 0

    the number after -package is the index of the mod package, as defined in the mod package combo box in the main form. So an index of 0 will launch the first mod package

    Launch Mod

    java -jar Minecrafter[version].jar -mod /path/to/mod/package

    You must define the absolute path to the mod archive or folder.

    Command Line Options

    The options that are available are described below:


    Disables the HD fix patching


    Disables crash detection


    Uses precompiled mod package from temp


    Minecrafter will not delete the META-INF folder

    Minecrafter Uses:

    Leave a Reply

    Fill in your details below or click an icon to log in:

    WordPress.com Logo

    You are commenting using your WordPress.com account. Log Out /  Change )

    Google photo

    You are commenting using your Google account. Log Out /  Change )

    Twitter picture

    You are commenting using your Twitter account. Log Out /  Change )

    Facebook photo

    You are commenting using your Facebook account. Log Out /  Change )

    Connecting to %s

    %d bloggers like this: