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
129 Posts
 x 6

Post 17 Feb 2016, 16:46


What is this?

A command-line tool that automates the boring resizing/zipping part of creating a Minecraft resource pack that no-one likes.

It takes a folder of source textures, then resizes, optimises, and removes transparent pixels from them. It then copies them into separate 512x, 256x, 128x... etc. folders, and optionally zips each folder up into a shareable texture pack zip.

The tool is highly configurable via a basic config file, patch.config.toml.


Automatically resizes all images to standard resource pack sizes.
512x source images are copied, resized to 256x, 128x, 64x, and 32x, then saved into their own size pack directory.

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 takes up as little memory as possible when used in-game, for better FPS. πŸ‘

Removes translucent pixels from item texture edges.
Ensures no texture flickering with Minecraft's graphics engine. This is configurable should certain textures need opting-in or -out, and is only applied to item textures by default.

Zips up each generated pack with clear, descriptive filenames.
E.g. SphaxPatch_MyTexturePack_MC1.16.4_64x.zip

Comes with a 'watch' mode, allowing you to design and create packs on the fly.
Any changes to .png, .txt or .mcmeta files will trigger a fresh generation of size packs

How to use

  1. Install Node JS v14+. It may work with earlier versions, but hasn't been tested on them.
  2. Download and unzip a Sphaxify release. Alternatively, clone the repo locally.
  3. Place your source images inside source-designs/{MC_VERSION}/, e.g. source-designs/1.16.4/. Mimic how the textures would be laid out when used as a texture pack. A typical working layout would be:
    - /source-designs/1.16.4/assets/some-incredible-mod/...
    - /source-designs/1.16.4/pack.mcmeta
    - /source-designs/1.16.4/pack.png

    An example 1.16.4/ folder has been provided, along with a barebones pack.mcmeta and pack icon design that you're encouraged to customise.
  4. . Customise the build options by editing patch.config.toml. Worry not, each option has detailed instructions, and has been set up with the defaults expected of a 512x source patch.
    - If your source designs are a different size (e.g. 128x), then make sure you customise initialSize and resizeLevels!
You now have 2 options for running the patch builder...

Option 1: For less tech-savvy users

Simply double-click either _MakePacks.command (macOS), or _MakePacks.bat (Windows). This will install everything Sphaxify needs to run, and then create the zipped-up texture packs for you. Generated texture packs will be inside the size-packs directory, ready to be shared. πŸš€

Option 2: For those comfortable with the command line

1. Install Sphaxify's dependencies. Open a terminal, browse to the _sphaxify directory, and run npm install.
2. The following npm scripts are now available:
  • npm run build - generates size packs
  • npm run zip - same as build, but also zips them up
  • npm run watch - will begin watching your source-designs/ directory for any changes to texture files, generating size packs every time a change is made.
  • npm run clean - nukes the size-packs/ directory. Handle with care! 🧨
Note - build and zip will likely to take a while when first run, especially for larger resource packs. Go and grab a coffee. β˜•οΈ

The console will show the progress of all processed images, and a system notification will appear when complete.


Please report any issues encountered either here or via GitHub.

Cheers to

Sphax, and the BDCraft community as a whole for being a big source of inspiration, creativity and motivation.



[01-01-2021] - v3.0.0
  • Graphicsmagick/Imagemagick no longer needed, now uses sharp (and should be much faster as a result)
  • Patch config now written in TOML
  • Now works with Node 14+
[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 01 Jan 2021, 05:13, edited 12 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
6408 Posts
 x 394

Post 17 Feb 2016, 17:38

Welcome back! Interesting project you have there :D Hopefully it'll help people out. ;)
Profile pic by TsaoShin: https://www.deviantart.com/tsaoshin
User avatar
Patch Creator
129 Posts
 x 6

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
Lifetime Supporter
246 Posts
 x 15

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
342 Posts
 x 33

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
6408 Posts
 x 394

Post 04 Jul 2017, 16:01

You can get GraphicsMagick as an installable exe here: https://sourceforge.net/projects/graphi ... es/1.3.25/
Profile pic by TsaoShin: https://www.deviantart.com/tsaoshin
User avatar
Patch Creator
342 Posts
 x 33

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
Lifetime Supporter
246 Posts
 x 15

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.
User avatar
Patch Creator
129 Posts
 x 6

Post 31 Dec 2020, 23:03

Hello guys, apologies for the radio silence over the last few years. Sphax (and Minecraft, for that matter) is something that I dip in and out of over time!

I'm happy to see that this tool has been useful for a few people, despite being very far from perfect. I've been in the process of updating it a bit for 2020, to hopefully make it a little less awkward to install, and speed it up a bit.

In the future I'd like to add a proper UI for it, aiming to avoid requiring users to install Node and having to work with the command line.
MauveCloud wrote: ↑
29 Nov 2020, 17:46
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.
I've noticed this as well, and I'm looking into it. The notifications are just a bonus though (they fire after the pack generation completes), so I wouldn't worry about them not showing up.

EDIT: also, Merry Christmas and a Happy New Year!
MC U/N: Grumpy_Pirate
Post Reply