†New in 2.3.0! Custom Colors mod! Texture pack authors can now customize many colors in the game including swamps, lighting, and more.†Many thanks to†Misa†for her valuable testing and feedback. A guide for texture pack authors will be forthcoming, but until then see Misa's updated texture pack for examples.
†HD texture pack and font support.
†Custom terrain and item animations for any tile, including water, lava, and portals.
†MrMessiah's BetterGrass mod.
†Balthichou's RandomMobs mod.
†Ability to load other mods like ModLoader. See "Installing other Mods" for details.
†Ability to save and load mod profiles and switch between them easily. Also organize your mods by the Minecraft version they go with.
Notes and Recent Changes:
†Texture pack author rejoice! In the Options tab there is now an option to automatically reload the textures whenever you make any changes to the texture pack. Test your changes without exiting to the main menu. Note: Enabling this feature may affect performance slightly.
†All existing backup jars and profiles from beta versions of Minecraft are automatically renamed. For example, minecraft-1.8.1.jar becomes minecraft-beta-1.8.1.jar. This will prevent problems when a future non-beta release uses the same version number as an earlier beta. The conversion will happen transparently when starting MCPatcher 2.2.3 for the first time.
†2.2.3 also contains a compatibility fix for the 11w49a snapshot (Unicode font support).
- Download the correct version of the patcher for your OS.
- Double-click the patcher. You should see this:
- If you would like Better Grass (full grass texture on the sides of grass blocks next to other grass blocks), check the box next to Better Grass.
- Click Patch. You do not need to select a texture pack at this point.
- Start the game.
- Click Mods and Texture Packs.
- Click Open Texture Packs folder. If nothing happens, just go to the texturepacks folder in .minecraft instead.
- Copy all your texture packs into that folder.
- Enjoy switching between texture packs without repatching the game!
Credit goes to JKurtz87 for making this video.
I have created adf.ly links for those who wish to support this project. Or you may donate via paypal:†
All other platforms:
java.io.IOException: could not open com/pclewis/mcpatcher/Config.classfor __Base
I do not know what causes this bug. It affects some people but not others. As a workaround, try this
- Download the jar version (not the exe)
- Use WinZip, 7-zip, etc., to unpack the jar into its own folder, say mcpatcher-2.2.0.
- In the folder, right-click and create new text file called mcpatcher.bat. Make sure you have file extensions turned on so you are creating mcpatcher.bat and not mcpatcher.bat.txt.
- Edit the file in notepad and copy the following into it:
- Save the file and exit.
- The mcpatcher-2.2.0 folder should look like this:
- Double-click mcpatcher.bat. The patcher window should appear.
Installing other Mods:
- In the main patcher window, click the Add (+) button.
- Select the zip file containing the mod you wish to apply. In this example, we'll use ModLoader.
- Click Ok.
- Next a window showing the list of files that will be added will appear. This is mainly informational. Confirm that the right files are listed and click Ok.
- The main patcher window should look like this now:
- Now we're going to add a second mod, zombe's mod pack.†This will illustrate two important things: How to add just a subfolder from a mod and how to resolve mod conflicts.
- Click the Add (+) button again.
- Choose the zombe mod pack zip.
- The subfolder window appears again. This time there are multiple subfolders to choose from. If you blindly add everything from the zip, it will not work. Instead, select the classes folder and click Ok.
- Next the list of files to be added is shown. Notice this time how files are being copied from the classes folder into the root of minecraft.jar.
- Now we have a slight problem. Both ModLoader and zombe's contain aaa.class. If you try to patch at this point, you will get a warning about the conflict.
- You can ignore this warning and patch anyway. Or you can fix it by removing aaa.class from ModLoader. Double-click ModLoader and the list of files will appear again. Select aaa.class and click the Remove (-) button.†Note: Doing this does not change the original ModLoader.zip file, only the list of files that will be copied from it.
- The file list should now look like this. Click Ok.
- The main patcher window should look like this:
- Click Patch and run the game!
FAQ / Troubleshooting
Some scanners detect WS.Reputation.1. It is a false positive that can be ignored. WS.Reputation.1 isn't so much a virus as it is the scanner saying "This file is new, so I don't trust it." See†this post by shinji257†for more information.
HD Textures or one of the other mods is greyed out.
If you install mods by hand before running the patcher, you may run into this problem. Start from a clean minecraft.jar instead and this should never happen. Delete the bin folder in .minecraft and redownload it. Try patching again first without any mods. If that works, then add mods one at a time using the patcher as described above.
The grass blocks are grey when I enable Better Grass.
This happens when you install ModLoader after patching. Use the patcher instead, and it will install ModLoader properly. See above section "Installing other Mods" for details.
I installed *** Mod using the patcher and now the game crashes.
Try using the Up/Down arrows in the patcher to apply mods in a different order. In my experience, putting other mods†before†HD Textures, etc., (which is the default behavior) works better, but you can also try moving them after.
I tried installing *** Mod both above and below HD Textures, etc., and it didn't work.
If you tried installing both ways and it didn't work, then you're out of luck. You'll have to choose between HD textures and the other mod. Unless the source code for the mod is available, I probably won't be able to fix the incompatibility.
All this patching, repatching, installing, and uninstalling mods has made a mess of things. Now I just want to start fresh.
Delete the bin folder in your .minecraft directory and run the game's launcher again to redownload everything. If the game still crashes, delete options.txt as well to force the game to use the default textures again. You will have to redo your settings and key mappings if you do this.
The "Open Texture Packs Folder" button in the game doesn't work. / Where do I put my texture packs?
Navigate to the appropriate folder for your OS. The texturepacks folder will be in there.
- Windows XP - C:\Documents and Settings\\Application Data\.minecraft
- Windows Vista/7 - C:\Users\\AppData\Roaming\.minecraft
- MacOS - From your home directory, go to Library -> Application Support -> minecraft
- Linux - ~/.minecraft
As a shortcut, in Windows, you can also press Windows key+R, then type%APPDATA%\.minecraft\texturepacks†and hit Enter.
When I select a particular texture pack, nothing changes.
Open the texture pack's .zip file and check that the files are in the right place. terrain.png should be in the root of the zip. If the zip contains a single folder with everything under it, it will not work. Take everything out of the folder and zip it back up. Other than that, do not unzip texture packs. Simply download them and place the .zip file as-is into the texturepacks folder.
Correctly zipped pack:
Incorrectly zipped pack:
(thanks to Gestankfaust for the screenshots)
The game crashes with an out of memory error or I get white boxes in place of some of the textures.
This mainly happens with 32-bit OSes and 256x texture packs, but there are things you can try:
- If you are running a 64-bit OS, download the 64-bit version of Java. For Windows it is available†here.. The first few lines of the patcher log tell you what version of Java you are running.
- In the patcher options panel, there is an option to set the Java heap size. If you are running 32-bit, decrease the value to 768. If you are running 64-bit, try increasing it to 2048 or 3072.†Note: This setting only affects the Test Minecraft button.
- Uncheck "Use texture cache" on the MCPatcher Options tab. This will make switching packs slower, but it uses less memory.
Multiplayer does not work / Achievements are not saved / I get the "Unlicensed copy or logged in from another location" message when using the Test Minecraft button.
That's because the Test Minecraft button does not log in. It is useful for testing that the patcher worked, but if you want multiplayer or achievements, use the normal game launcher.
Does this work with version x.y.z of Minecraft?
Unlike most mods, MCPatcher is designed to be version-independent. It should work across multiple versions of the game, theoretically as far back as the 2010 Halloween update. When a new version of the game comes out, before breathlessly posting to ask when MCPatcher will be updated, just try running the version you have. Most of the time it will work as-is and you'll save yourself some unnecessary waiting.
I have a different problem not mentioned here.
Before posting, please Google for "mcpatcher†other keywords†site:minecraftforum.net" to see if your question has already been answered. If you do post, please include the log in your post as well. The Copy To Clipboard button puts code tags around it so all you have to do is paste it into your post.
Information for Texture Pack Authors
For the most part, you create an HD texture pack the same way you create a non-HD one.†This thread†has a list of the files in a typical texture pack.
Texture files within a pack can be different sizes. MCPatcher uses the largest and scales everything up to that size. This means that a 32x terrain.png and 32x items.png will be scaled to 128x if used in a pack with a 128x custom water texture.
These are the files that are considering when calculating the tile size:
- width(terrain.png) / 16
- width(gui/items.png) / 16
Custom animations are read from these files, all in the root of the texture pack .zip:
- custom_water_still.png, custom_water_flowing.png - still and flowing water
- custom_lava_still.png, custom_lava_flowing.png - still and flowing lava
- custom_portal.png - portal animation
- custom_fire_n_s.png, custom_fire_e_w.png - the north-south and east-west sides of fire blocks, respectively
- custom_terrain_###.png - animation for any tile in terrain.png. ### is the tile index (0-255), not a block or item ID
- custom_item_###.png - animation for any tile in items.png. ### is the tile index (0-255), not a block or item ID
Each image should be a vertical strip of separate frames. The width should match the tile size of the texture pack, but if it doesn't it will be resized to match. See†this thread†for a more detailed explanation.
Balthichou's RandomMobs†mod is now included by default. You may include multiple skins for the same mob and the game will automatically pick one at random. Add a number to the end of the filename before the .png, e.g., /mob/creeper2.png. Start at number 2 and do not skip any numbers. For the wolf textures, make sure you include the same number of wolf, wolf_tame, and wolf_angry textures or it will look strange when a wolf changes moods.
In 2.2.0, I changed how the font widths are calculated. This causes existing custom fonts to be more spaced out. If you've added invisible "spacer pixels" to the edges of characters to get the spacing you want in the past, you'll probably want to take them out. To allow for more control over the widths of individual characters, I have included a way to specify them manually. Create a text file called /font/default.properties or /font/alternate.properties. Each line in this file specifies the width of a character:
width.<ASCII value 0-255>=<Width0-8>
For example, to specify the widths of capital A, B, and C, you might use
Values can be floating point numbers (Notch's original code only supported integer widths) and range from 0-8 regardless of the resolution of the font. You do not need to specify widths for all characters, only ones where you want to override the default width.
The space character is special. Its default width is 1/2 of the average of the widths of A-Z, a-z, and 0-9. This makes the spacing between words match the overall width of the font. However you can override this the same way, by setting width.32 to a custom value.
Update:†Nuin has created an†Excel spreadsheet†to make the font calculations easier. Also see his†Berylium font.
After hearing many complaints about the swamp colors introduced in 1.9 I developed the Custom Colors mod to allow texture pack authors to customize, not just swamps, but many of the games hardcoded colors. Here are the files you will need to include in the texture pack:
This text file allows you to specify colors for potions, spawner eggs, lilypads, and a base color for water particle effects (drops, splashes, and bubbles). A template file with the game's default values is included below. See the # comments above each value for a description of how it is used in game.
This is a 16x1 bitmap used for redstone wiring and particle effects. Other redstone colors (torches, repeaters, etc.) are still in terrain.png / items.png as usual. The x-axis of the redstonecolor.png bitmap represents the current strength. 0 is fully off, 15 is fully on.
This is an 8x1 bitmap used for pumpkin and melon stems at each growth stage. 0 is a sprout, 7 is fully grown.
This is a bitmap used for the lava drop particle effect as it cools during its fall. The height should be 1 pixel but the width can be anything. The x-axis represents the particle's age in game ticks (about 1/20th of a second). Lava drop particles are generally not visible for the first 40 ticks or so because they start out embedded in the block above. 90 pixels is a good width. If the particle lives longer than the width of the image, the last pixel is used for the remaining time.
/misc/swampgrasscolor and /misc/swampfoliagecolor:
256x256 biome palettes used in swampy areas. They work just like their non-swamp counterparts.
/misc/pinecolor and /misc/birchcolor:
Biome color palettes for pine and birch leaves. The pixel at (127, 127) is used for the default color when the block is held or in inventory.
Biome color palette for water. Note the capital X in the filename to prevent the default watercolor.png from being used accidentally.
Other biome palettes:
You can also assign a custom biome palette to any standard block. Here "standard" means any block that does not already have its own special coloring. In MCP terms, this is any Block subclass that does not override the colorMultiplier method. Create a 256x256 bitmap, then in color.properties add a line
palette.block.<path>=<list of block IDs>
For example, to use /misc/stonecolor.png with all stone and ore blocks, use
/environment/lightmap1.png: (The End)
These are custom lighting palettes for each world. The height must be exactly 32 pixels but they can be any width. Each bitmap actually consists of two palettes, but we'll get into that later.
First an explanation of how lighting normally works in Minecraft. Every block has two light values from 0 to 15 assigned to it, one for sky brightness and one for torch brightness. A block in direct sunlight has a sky value of 15. A block in the shade directly adjacent to it has a value of 14 and so on. Blocks deep underground far from any block that can see the sky have sky brightness 0. Similarly for torches. A torch block has light value 14 and the light value drops by 1 each block away from it.
To generate the lighting you actually see in game, Minecraft uses a 16x16 lightmap. Its axes correspond to the 16 light levels of each type. If a block has torch brightness x and sky brightness y, it uses (x,y) for its lightmap coordinates. The lightmap is not in any of the game's files but is generated each frame. You may have found that light_normal.png file in minecraft.jar, but it is not used at all. Two variables affect the lightmap, the time of day and the torch flicker. Minecraft implements night and day and torch flicker by making the entire lightmap darker or lighter rather than by adjusting the sky/torch brightness values.
So how does MCPatcher convert lightmap0.png into a 16x16 lightmap? Remember your palette must be exactly 32 pixels high, but can be any width. The top 16 rows represent sunlight and the bottom 16 represent torchlight. Two columns, 16 pixels from the top half and 16 pixels from the bottom half, are chosen to form the axes of the final 16x16 lightmap used for rendering.
In the top half, the left-hand side represents night and the right-hand side represents day, with the dusk/dawn transitions in between. The very far right of the palette represents lightning flashes. Again, there is no specified width for the palette, but more width means more room for detail in the dusk/dawn transitions.
Blue=night, orange=dusk/dawn, cyan=day, yellow=lightning. (Template by Misa.)
Torches work similarly, but in this case x is a random value based on the torch flicker.
The method described above is used for all three worlds (Overworld, Nether, The End), but since there is no night or day in Nether and The End, the "time of day" value is constant. For these worlds you can simply give each row 0-15 the same color all the way across.
xau's thread is available†here, but the old patcher (1.1.12_02) no longer works as of 1.5_01.
Settings, including the list of enabled mods and files to include, are saved to mcpatcher.xml in the .minecraft folder. The format should be self-explanatory.
From the main patcher window, you can also
- enable or disable individual mods by checking/unchecking them,
- edit a mod by double-clicking it,
- remove altogether a mod you previously added by selecting it and clicking the Remove (-) button, and
- change the order in which mods will be applied using the up and down arrows.
If you are curious about the actual changes MCPatcher makes to minecraft.jar, use MCP to decompile a patched minecraft.jar.
- Colorize cauldron water.
- Colorize water block when held / in inventory.
- Colorize falling sand and gravel.
- Colorize rain splashes.
12/15 2.3.0 release:
- Compatibility fixes for older versions of Minecraft. HD Textures and HD Font should work as far back as Beta 1.0 again.
- New Custom Colors mod. Customize swamps, potions, pine/birch leaves, and much more.
- Possible fix for null pointer exception on some MacOS systems.
- Fix reading from closed zip file when editing a mod's file list.
- Hack to deal with the misnamed 11w50a version.
12/8 2.2.3 release:
- Handle unicode changes to FontRenderer class in snapshot 11w49a.
- Rename backups/profiles (e.g., 1.8.1 -> Beta 1.8.1) to prevent future version conflicts.
- Option to auto-detect when texture pack zip changes.
- Autocompute max locals when adding a method.
11/13 2.2.2 release:
- Compatible with Minecraft RC versions.
- Restored workaround for white spider/endermen.
- Improved Better Grass compatibility with ModLoader.
- More compact UI.
- Fixes for loading custom patches from jar files.
10/30 2.2.1 release:
- Random Mobs is no longer dependent on HD Textures. This allows Optifine users to have Random Mobs.
- Random Mobs skins are now persistent in single-player. Mobs will not change appearances when saving and reloading the world.
- Fix incompatibility with†Tale of Kingdoms†mod. (Workaround for javassist classFile.compact bug)
- Use numbered spider/enderman_eyes##.png texture if present.
10/16 2.2.0 release:
- Balthichou's RandomMobs mod
- Fixed enchantment table font
- Fixed font width calculations and allowed texture packs to override widths if desired.
- Properly refresh enchantment table font when switching packs.
- Animate any tile in terrain.png or items.png by creating custom_terrain_###.png / custom_item_###.png.
10/3 2.1.2 release:
- New feature: mod profiles.
- Properly recognize pre-release versions with their own version number. Minecraft 1.9 Prerelease 2 will be separate from Minecraft 1.9 final. The first time you run this version, the existing backups will be renamed to the new numbering scheme if possible.
- Shift-click up/down moves selected mod to top/bottom of the list.
- BetterGrass also affect mycelium blocks.
- Close file handles to prevent files from being needlessly locked by Windows.
- Remember last mod folder.
- Better, resizable mod conflicts window.
9/18 2.1.1_01 release:
- Fix Better Grass with mod loader (qo.class conflict).
- Fix non-AO Better Grass with 1.8
9/12 2.1.1 release:
- Workaround for ! in pathname.
- Fix bug when reading orig md5sum from md5s file.
- Extra null checks in RenderEngine.class for BukkitContrib compatibility.
- Improved handling of zips with missing directory entries (e.g., Better Than Wolves).
- Improved exception handling during patching.
- Fix inconsistent priority when mods add vs. replace files. In case of conflicts, mods later in the list override ones earlier in the list.
- Ensure that Minecraft 1.0 final will be considered newer than 1.6 beta.
- Add scrollbar to conflicts window.
- Make patched code decompile cleanly with MCP again. Tested with MC 1.7.3 + MCP 4.3.
- Close ZipFile when cancelling add mod operation or removing mod.
- Fix white spider/enderman bug that affected some texture packs.
- Reduce font size to make mod list more compact.
6/11 2.1.0_02 release:
- Skip __MACOSX directory when patching
- Skip subfolder dialog if mod contains no subfolders
- Allow editing of previously added mods by double-clicking
- Fix "double item" bug in 3rd person view
- Allow selecting and removing multiple files from a mod
- Fix Add mod button for Java 5 users
- Set default Java heap size to 768 on 32-bit
- Redirect stdout/stderr to log window
- Put spoiler tags around log window text when copying to clipboard
5/29 2.1.0_01 release:
- Fix "whiskers" on held items
- Fix invisible ModLoader items
- Make compatible with older versions of the game again
5/26 2.1.0 release:
- 1.6 compatibility
- Custom mod support
- Better Grass disabled initially
- Configuration saved to mcpatcher.xml instead of mcpatcher.properties
5/1 2.0.1 release:
- BetterGrass is back! Based on MrMessiah's mod.
- Um, that's pretty much it.
4/26 2.0.0 release:
- Fixed bug where custom animation settings were not always read. If the game appeared to ignore your settings when launched normally (vs. the Test Minecraft button), this should fix it.
- Reorganized the Options panel.
- Fixed a class conflict with zombe's mod pack. HD Textures should no longer be greyed out if you have this mod installed before patching.
- Base the tile size of the max of several common textures, not just terrain.png. This allows you to have a 32x32 items.png and no terrain.png, for example.
- Custom fire animations. Filenames are custom_fire_n_s.png and custom_fire_e_w.png.
- Texture cache optional, disabled by default on 32-bit OSes.
- Removed beta popup warning on first startup.