Sphaxify - Automated BDCraft Patch Builder Tool

Want hints or tips about creating textures or other resources? This is the place for you.
Post Reply 
User avatar
Patch Creator
127 Posts
 x 3

Post 17 Feb 2016, 16:46


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 - SomeIncredibleMod.zip
  • 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 _Install.sh (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 _MakePacks.sh (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/_Install.sh 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
Last edited by GrumpyPirate on 02 Mar 2016, 17:58, edited 10 times in total.
MC U/N: Grumpy_Pirate
If you like our work please consider becoming a Supporter and get an ad-free experience.
User avatar
BDcraft Web Admin
6290 Posts
 x 301

Post 17 Feb 2016, 17:38

Welcome back! Interesting project you have there :D Hopefully it'll help people out. ;)
If you like a post give it a diamond! :arrow_heading_up:
:speech_balloon: Join the BDcraft Discord server to keep updated with news and chat with other fans!
User avatar
Patch Creator
127 Posts
 x 3

Post 17 Feb 2016, 17:50

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.
MC U/N: Grumpy_Pirate
User avatar
251 Posts
 x 14

Post 01 Mar 2017, 00:33

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 https://git-scm.com/downloads

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.
User avatar
Patch Creator
271 Posts
 x 1

Post 04 Jul 2017, 15:27

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
User avatar
BDcraft Web Admin
6290 Posts
 x 301

Post 04 Jul 2017, 16:01

You can get GraphicsMagick as an installable exe here: https://sourceforge.net/projects/graphi ... es/1.3.25/
If you like a post give it a diamond! :arrow_heading_up:
:speech_balloon: Join the BDcraft Discord server to keep updated with news and chat with other fans!
User avatar
Patch Creator
271 Posts
 x 1

Post 05 Jul 2017, 00:16

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.
User avatar
5 Posts
 x 0

Post 13 Apr 2020, 16:01

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
User avatar
251 Posts
 x 14

Post 29 Nov 2020, 17:46

I've found this tool very helpful for the GregTech texture patch (especially considering how many textures that involves), though I added an extra category "grayscaleables" since a lot of the textures work better when forced to "grayscale" color space (because the mod adds colors based on material).

However, I've run into a weird issue with the part about "a system notification will appear when complete." Several months or more ago (I've lost track of exactly when, sorry), it stopped popping up "when complete", and I only see them in my Windows 10 notification area after I start up my computer the following morning. IDK whether that's due to a setting I changed or a Windows Update, but I'm curious if anyone else has the same problem or any idea how I can fix it.
Post Reply