Page 1 of 1

Sphaxify - Automated BDCraft Patch Builder Tool

Posted: 17 Feb 2016, 16:46
by GrumpyPirate

What is this?

This is a simple script for patch artists to use when creating BDCraft texture packs, automating the boring resizing/zipping part that no-one likes.

It takes a folder of source images, then resizes/optimises/removes transparent pixels from everything into separate 512x, 256x, 128x... etc. folders, then zips each one up into neatly-named files.

Everything is configurable.


  • Automatically resizes all images as needed
    • Source 512x images are resized to 256x, 128x, 64x, and 32x into their own directories
    • This is fully configurable - is your source only 128x? Want to only generate packs down to 64x? No problem.
  • Optimises generated PNGs losslessly to ensure small filesizes
    • Ensures the patch uses as little VRAM as possible, for better system performance on users' machines
  • Removes any semi-transparent pixels from texture edges
    • Ensures no texture flickering with Minecraft's graphics engine
    • Uses an 'either-or' method of setting pixel colour intensity - pixels below 50% get removed, above 50% get converted to 100% intensity
  • Saves processed images to separate, neatly-named directories
    • The build system will generate separate directories for each set of processed files, leaving the source images untouched
    • This allows generated packs to be chucked away and simply regenerated whenever needed without worry
  • Zips up each generated pack with nice, standardised filenames
    • E.g. [128x] [1.7.10] Sphax Patch -
  • Allows certain images to be excluded from resizing/transparent pixel removal
    • Useful for troublesome images that need to be kept the same size (hello, GUIs) or need transparency (some fluid textures)
    • GUIs are excluded by default
  • Can watch your source-designs/ directory for any changes while you work, to auto-regenerate packs on-the-fly
    • Any changes to .png, .txt or .mcmeta files will trigger a fresh generation of size packs

How to Install

  1. Install Node.js
  2. Install ImageMagick
  3. Install GraphicsMagick
  4. Download and unzip Sphaxify
  5. Double-click _Install.bat (Windows) or (Mac OSX/Linux)
  6. Edit the options at the top of gulpfile.js
  7. Ready!
For an exhaustive, newbie-friendly, step-by-step guide on how to set the project up, please see the README on GitHub.

How to use

  1. Place your source images inside source-designs/{MC_VERSION}/, e.g. source-designs/1.7.10/
    • Mimic how the textures would be laid out when used as a texture pack. A typical working layout would be
      • My Sphax Texture Project/
        • source-designs/
          • 1.7.10/
            • pack.png
            • pack.mcmeta
            • assets/
              • someincrediblemod/
                • textures/
                  • etc...
    • An example 1.7.10/ folder has been provided, along with a barebones pack.mcmeta and pack.png/psd for customisation.
  2. Customise the build options by opening `Gulpfile.js` in your favourite text editor. You'll see some variables at the top of the file - customise these to how you want your patch to be built and named:
    • Set patchName to whatever you'd like your generated .zip files to be named
    • Set initialSize to the resolution of your source images (default is 512)
    • Set resizeLevels to however many times you want the patch to be downsized
    • Add to resizeables any images you don't want resized
    • Add to thresholdables any images you want to keep their transparency
    • Optional: If you'd like to specify the location of your source images (and where they'll be generated), edit paths.src/dest - otherwise, leave as default.
  3. Ready! You can now run any of the following from a terminal/command prompt within the folder:
    • npm run optimise - generates size packs into size-packs/
    • npm run makezips - runs optimise, then zips up each size pack in size-packs/
    • npm run watch - will begin watching your source-designs/ directory for any changes to .png, .txt or .mcmeta files, and will run the optimise only on images newer than the equivalents currently in size-packs/. Stop watching at any time by hitting CTRL+C
  4. Or, if you don't want to use the command line
    • simply double-click either _MakePacks.bat (Windows) or (Mac OSX/Linux) to make everything.
Note - optimise and makezips are likely to take a while when first run, depending on the size of your texture pack - go and grab a coffee. The console will show the progress of all processed images, and a system notification will appear when complete.


This is a young project, please report any issues encountered either here or via GitHub and they'll be fixed as soon as possible.

Cheers to

Sphax and the BDCraft community as a whole for being a big source of inspiration over the last couple of years.


[29-02-2016] - v1.2.1 released
  • Large QoL upgrade, setup has been made much easier
  • Issues with colour type getting reduced by imagemin have been fixed, eliminating the need for the compressables list
[19-02-2016] - v1.1.0 released
  • Default directories have been renamed to something more meaningful
    • src/ -> source-designs/
    • dist/ -> size-packs/
[19-02-2016] - v1.0.4 released
  • Can now simply double-click _Install.bat/ to install Sphaxify locally
  • Fixes/improves _MakePacks scripts
[19-02-2016] - v1.0.3 released + massively simplify OP
  • Much easier to set up + configure
  • Remove need to install global Gulp
  • Options for specifying which images are excluded when resizing/optimising/thresholding are now at the top of Gulpfile.js, along with all the other options

Re: Sphaxify - an Automated BDCraft Patch Builder

Posted: 17 Feb 2016, 17:38
by HanFox
Welcome back! Interesting project you have there :D Hopefully it'll help people out. ;)

Re: Sphaxify - an Automated BDCraft Patch Builder

Posted: 17 Feb 2016, 17:50
by GrumpyPirate
Cheers Han :)

I hope so, I'm aware that it's a little unwieldy to set up if you're not very tech-oriented. I'm hoping to streamline it a little more in the future, but once set up it does handle automating a job I always hated doing.

Re: Sphaxify - Automated BDCraft Patch Builder Tool

Posted: 01 Mar 2017, 00:33
by MauveCloud
The "How to Install" seems to be incomplete. I'm using Windows 10, and double-clicking _Install.bat gave me some errors about "git" being missing, so I tried running the file from a Git Shell, and that seems to have worked. GitHub Desktop doesn't seem to include a simple way to enable running git from the standard command line, though, so I installed one from

Edit: it also fails to mention needing to install Gulp, and when I tried to run it for a fork of the OpenComputers patch (I'm hoping to add a folder for 1.10.2 with the textures renamed and rearranged to work with the newer version of the mod, but I want to test them first before setting up the PR), I got the following output:

Code: Select all

C:\GitHub\sphax-patch-opencomputers>npm run optimise

> [email protected] optimise C:\GitHub\sphax-patch-opencomputers
> gulp optimise

    throw err;

Error: Cannot find module 'gulp-load-plugins'
    at Function.Module._resolveFilename (module.js:470:15)
    at Function.Module._load (module.js:418:25)
    at Module.require (module.js:498:17)
    at require (internal/module.js:20:19)
    at Object.<anonymous> (C:\GitHub\sphax-patch-opencomputers\gulpfile.js:108:9)
    at Module._compile (module.js:571:32)
    at Object.Module._extensions..js (module.js:580:10)
    at Module.load (module.js:488:32)
    at tryModuleLoad (module.js:447:12)
    at Function.Module._load (module.js:439:3)

npm ERR! Windows_NT 10.0.14393
npm ERR! argv "C:\\Program Files\\nodejs\\node.exe" "C:\\Program Files\\nodejs\\node_modules\\npm\\bin\\npm-cli.js" "run" "optimise"
npm ERR! node v7.6.0
npm ERR! npm  v4.1.2
npm ERR! [email protected] optimise: `gulp optimise`
npm ERR! Exit status 1
npm ERR!
npm ERR! Failed at the [email protected] optimise script 'gulp optimise'.
npm ERR! Make sure you have the latest version of node.js and npm installed.
npm ERR! If you do, this is most likely a problem with the sphax-patch-opencomputers package,
npm ERR! not with npm itself.
npm ERR! Tell the author that this fails on your system:
npm ERR!     gulp optimise
npm ERR! You can get information on how to open an issue for this project with:
npm ERR!     npm bugs sphax-patch-opencomputers
npm ERR! Or if that isn't available, you can get their info via:
npm ERR!     npm owner ls sphax-patch-opencomputers
npm ERR! There is likely additional logging output above.

npm ERR! Please include the following file with any support request:
npm ERR!     C:\GitHub\sphax-patch-opencomputers\npm-debug.log


Edit 2: Got past that by doing "npm install gulp-load-plugins", and similarly for each module that came up in error messages. However, I have a feeling there was something I could have done to pre-install the necessary modules, or maybe make it install them as needed.

Edit 3: I see what I did wrong. I could have just run the _Install.bat file inside the checked-out copy of the OpenComputers patch. I didn't need to download "Sphaxify" separately, as it doesn't exactly install it as a utility for my computer to use elsewhere. You might see if you can clarify that a bit in the documentation.

Re: Sphaxify - Automated BDCraft Patch Builder Tool

Posted: 04 Jul 2017, 15:27
by Llama Farmer
My lord... Haven't tested this yet, but if this is all I hope it to be, then I shall be one happy bean. Where was this in the old days... hahahahahahaha

-- edit --

Rip, nvm. No idea how to compile source code, so no GraphicsMagick for me :/ Ah well, let's see if I can rustle up those old PS scripts again :D

-- edit --

*when you're on a new computer, PS doesn't have the old complete set of actions for opacity-removing and batch-resizing (100% size, 50% size, 25% size, etc.), and after a good hour tracking down the link to the download for them, it's down...* rip. Anyone feel like teaching a nooblet like me what a 'unix' is? :-x :-x :-x

Re: Sphaxify - Automated BDCraft Patch Builder Tool

Posted: 04 Jul 2017, 16:01
by HanFox
You can get GraphicsMagick as an installable exe here: ... es/1.3.25/

Re: Sphaxify - Automated BDCraft Patch Builder Tool

Posted: 05 Jul 2017, 00:16
by Llama Farmer
Thanks Han! I was on Mac when I made those comments (last night over here) so no can do's .exes, but I definitely could use that on my PC :) Speaking of which, found those old PS batch-resizer actions on said PC, so problem solved anyway hahahaha. That being said, I'll definitely check out GP's new fandangle-sphaxamabob. :) so thanks heaps!

Btdubs, I could potentially re-link those batch-resizer actions, which could be helpful for anyone new here who's not so code-savvy (e.g. me), if that would help? Could maybe add 'em back to the "Useful Resources to Sphaxify" thread? Don't wanna step on anyone's (crumbl3d's...? if I remember correctly... I think it was him who made them in the first place, though I could absolutely be wrong there) toes though.

Re: Sphaxify - Automated BDCraft Patch Builder Tool

Posted: 13 Apr 2020, 16:01
by PCNAndor
This works quick and efficient, thanks for that. Funny to me, I learned something during the installation process. In Windows file explorer I used to CTRL+SHIFT and right click to bring option to open command prompt from current location. Forever ago that's been replaced with `Open Powershell window here` instead ... now I know I can enter cmd by typing `cmd` in file explorer address bar and hit `Enter`.... neat 8D