NWN Crunch Guide

Some notes and stuff on NWN Crunch Enhanced Edition.

Basics

The crunch program will generate good DDS files for your textures from source files such as PNG, TGA, BMP and JPG.

Recommended input file is PNG for obvious reasons - 32 bit with alpha is usual.

You can also convert any format to, say, PNG for use in other programs. This is the easiest way to get NWN DDS (a sorta weird NWN only DDS format no longer required in NWN:EE) back to a usable format, which many of the game files and much Custom Content uses.

Stuff to Note

Compressed PNG files should be 32bit with alpha. We've found having a simply blank; eg entirely transparent for some reason texture doesn't load properly.

There is an option to have the usual batch scripts check and truncate filenames; it is really however recommended to have all filenames 16 characters or less, or in the case of diffuse textures you want to have _d after, to have them 14 characters (or have the _d already apended).

Read the notes in the vault page for some tips on MTR creation as well: https://neverwintervault.org/project/nwnee/other/tool/nwn-crunch-enhanced-edition

You can create your own simplified batch or powershell scripts using the original ones as a basis, or check the options out further down.

Readme

This is essentially the readme in the program. Some pertinent options will be described below.

Crunch Readme

NWN Crunch: Texture Compression Tool
Based on crunch by Richard Geldreich, Jr. and Binomial LLC - https://github.com/BinomialLLC/crunch
libcrn version v1.04 x64 Built May 16 2021, 19:40:17

Error: No command line parameters specified!

Command line usage:
crunch [options] -file filename
-file filename - Required input filename, wildcards, multiple -file params OK.
-file @list.txt - List of files to convert.
Supported source file formats: dds,ktx,crn,tga,bmp,png,jpg/jpeg,psd
Note: Some file format variants are unsupported.
See the docs for stb_image.c: http://www.nothings.org/stb_image.c
Progressive JPEG files are supported, see: http://code.google.com/p/jpeg-compressor/

Path/file related parameters:
-out filename - Output filename
-outdir dir - Output directory
-outsamedir - Write output file to input directory
-deep - Recurse subdirectories, default=false
-nooverwrite - Don't overwrite existing files
-timestamp - Update only changed files
-forcewrite - Overwrite read-only files
-recreate - Recreate directory structure
-fileformat [dds,ktx,crn,tga,bmp,png,nwn] - Output file format, default=crn or dds

Modes:
-compare - Compare input and output files (no output files are written).
-info - Only display input file statistics (no output files are written).

Misc. options:
-helperThreads # - Set number of helper threads, 0-16, default=(# of CPU's)-1
-noprogress - Disable progress output
-quiet - Disable all console output
-ignoreerrors - Continue processing files after errors. Note: The default
                behavior is to immediately exit whenever an error occurs.
-logfile filename - Append output to log file
-pause - Wait for keypress on error
-window <left> <top> <right> <bottom> - Crop window before processing
-clamp <width> <height> - Crop image if larger than width/height
-clampscale <width> <height> - Scale image if larger than width/height
-nostats - Disable all output file statistics (faster)
-imagestats - Print various image qualilty statistics
-mipstats - Print statistics for each mipmap, not just the top mip
-lzmastats - Print size of output file compressed with LZMA codec
-split - Write faces/mip levels to multiple separate output PNG files
-yflip - Always flip texture on Y axis before processing
-unflip - Unflip texture if read from source file as flipped
-invertcolors - Invert image colors, default=disabled
-normalize - Normalize for normal maps, default=disabled
-minvalue <int> - Minimum value for all channels [0,255], default=0
-setRGBtoY - Set RGB channels to luminosity, default=disabled
-setAtoY - Set Alpha Channel to luminosity, default=disabled
-setRGBAtoR - Set RGBA channels to Red channel, default=disabled

Image rescaling (mutually exclusive options)
-rescale <int> <int> - Rescale image to specified resolution
-relscale <float> <float> - Rescale image to specified relative resolution
-rescalemode <nearest | hi | lo> - Auto-rescale non-power of two images
 nearest - Use nearest power of 2, hi - Use next, lo - Use previous

DDS/CRN compression quality control:
-quality # (or /q #) - Set Clustered DDS/CRN quality factor [0-255] 255=best
       DDS default quality is best possible.
       CRN default quality is 128.
-bitrate # - Set the desired output bitrate of DDS or CRN output files.
             This option causes crunch to find the quality factor
             closest to the desired bitrate using a binary search.

Low-level CRN specific options:
-c # - Color endpoint palette size, 32-8192, default=3072
-s # - Color selector palette size, 32-8192, default=3072
-ca # - Alpha endpoint palette size, 32-8192, default=3072
-sa # - Alpha selector palette size, 32-8192, default=3072

Mipmap filtering options:
-mipMode [UseSourceOrGenerate,UseSource,Generate,None]
         Default mipMode is UseSourceOrGenerate
 UseSourceOrGenerate: Use source mipmaps if possible, or create new mipmaps.
 UseSource: Always use source mipmaps, if any (never generate new mipmaps)
 Generate: Always generate a new mipmap chain (ignore source mipmaps)
 None: Do not output any mipmaps
-mipFilter [box,tent,lanczos4,mitchell,kaiser], default=kaiser
-gamma # - Mipmap gamma correction value, default=2.2, use 1.0 for linear
-blurriness # - Scale filter kernel, >1=blur, <1=sharpen, .01-8, default=.9
-wrap - Assume texture is tiled when filtering, default=clamping
-renormalize - Renormalize filtered normal map texels, default=disabled
-maxmips # - Limit number of generated texture mipmap levels, 1-16, default=16
-minmipsize # - Smallest allowable mipmap resolution, default=1

Compression options:
-alphaThreshold # - Set DXT1A alpha threshold, 0-255, default=128
 Note: -alphaThreshold also changes the compressor's behavior to
 prefer DXT1A over DXT5 for images with alpha channels (.DDS only).
-uniformMetrics - Use uniform color metrics, default=use perceptual metrics
-noAdaptiveBlocks - Disable adaptive block sizes (i.e. disable macroblocks).
-compressor [CRN,CRNF,RYG,ATI] - Set DXTn compressor, default=CRN
-dxtQuality [superfast,fast,normal,better,uber] - Endpoint optimizer speed.
            Sets endpoint optimizer's max iteration depth. Default=uber.
-noendpointcaching - Don't try reusing previous DXT endpoint solutions.
-grayscalsampling - Assume shader will convert fetched results to luma (Y).
-forceprimaryencoding - Only use DXT1 color4 and DXT5 alpha8 block encodings.
-usetransparentindicesforblack - Try DXT1 transparent indices for dark pixels.

Ouptut pixel format options:
-usesourceformat - Use input file's format for output format (when possible).

All supported texture formats:
-DXT1
-DXT2
-DXT3
-DXT4
-DXT5
-3DC
-DXN
-DXT5A
-DXT5_CCxY
-DXT5_xGxR
-DXT5_xGBR
-DXT5_AGBR
-DXT1A
-ETC1
-ETC2
-ETC2A
-ETC1S
-ETC2AS
-R8G8B8
-L8
-A8
-A8L8
-A8R8G8B8

Note: .CRN only supports DXTn pixel formats, NWN only support DXT1 and DXT5 formats.

Exit status: 1
PS E:\SVN\Tools and Utilities\Crunch\nwn_crunch_windows64_EE> .\nwn_crunch.exe
NWN Crunch: Texture Compression Tool
Based on crunch by Richard Geldreich, Jr. and Binomial LLC - https://github.com/BinomialLLC/crunch
libcrn version v1.04 x64 Built May 16 2021, 19:40:17

Error: No command line parameters specified!

Command line usage:
crunch [options] -file filename
-file filename - Required input filename, wildcards, multiple -file params OK.
-file @list.txt - List of files to convert.
Supported source file formats: dds,ktx,crn,tga,bmp,png,jpg/jpeg,psd
Note: Some file format variants are unsupported.
See the docs for stb_image.c: http://www.nothings.org/stb_image.c
Progressive JPEG files are supported, see: http://code.google.com/p/jpeg-compressor/

Path/file related parameters:
-out filename - Output filename
-outdir dir - Output directory
-outsamedir - Write output file to input directory
-deep - Recurse subdirectories, default=false
-nooverwrite - Don't overwrite existing files
-timestamp - Update only changed files
-forcewrite - Overwrite read-only files
-recreate - Recreate directory structure
-fileformat [dds,ktx,crn,tga,bmp,png,nwn] - Output file format, default=crn or dds

Modes:
-compare - Compare input and output files (no output files are written).
-info - Only display input file statistics (no output files are written).

Misc. options:
-helperThreads # - Set number of helper threads, 0-16, default=(# of CPU's)-1
-noprogress - Disable progress output
-quiet - Disable all console output
-ignoreerrors - Continue processing files after errors. Note: The default
                behavior is to immediately exit whenever an error occurs.
-logfile filename - Append output to log file
-pause - Wait for keypress on error
-window <left> <top> <right> <bottom> - Crop window before processing
-clamp <width> <height> - Crop image if larger than width/height
-clampscale <width> <height> - Scale image if larger than width/height
-nostats - Disable all output file statistics (faster)
-imagestats - Print various image qualilty statistics
-mipstats - Print statistics for each mipmap, not just the top mip
-lzmastats - Print size of output file compressed with LZMA codec
-split - Write faces/mip levels to multiple separate output PNG files
-yflip - Always flip texture on Y axis before processing
-unflip - Unflip texture if read from source file as flipped
-invertcolors - Invert image colors, default=disabled
-normalize - Normalize for normal maps, default=disabled
-minvalue <int> - Minimum value for all channels [0,255], default=0
-setRGBtoY - Set RGB channels to luminosity, default=disabled
-setAtoY - Set Alpha Channel to luminosity, default=disabled
-setRGBAtoR - Set RGBA channels to Red channel, default=disabled

Image rescaling (mutually exclusive options)
-rescale <int> <int> - Rescale image to specified resolution
-relscale <float> <float> - Rescale image to specified relative resolution
-rescalemode <nearest | hi | lo> - Auto-rescale non-power of two images
 nearest - Use nearest power of 2, hi - Use next, lo - Use previous

DDS/CRN compression quality control:
-quality # (or /q #) - Set Clustered DDS/CRN quality factor [0-255] 255=best
       DDS default quality is best possible.
       CRN default quality is 128.
-bitrate # - Set the desired output bitrate of DDS or CRN output files.
             This option causes crunch to find the quality factor
             closest to the desired bitrate using a binary search.

Low-level CRN specific options:
-c # - Color endpoint palette size, 32-8192, default=3072
-s # - Color selector palette size, 32-8192, default=3072
-ca # - Alpha endpoint palette size, 32-8192, default=3072
-sa # - Alpha selector palette size, 32-8192, default=3072

Mipmap filtering options:
-mipMode [UseSourceOrGenerate,UseSource,Generate,None]
         Default mipMode is UseSourceOrGenerate
 UseSourceOrGenerate: Use source mipmaps if possible, or create new mipmaps.
 UseSource: Always use source mipmaps, if any (never generate new mipmaps)
 Generate: Always generate a new mipmap chain (ignore source mipmaps)
 None: Do not output any mipmaps
-mipFilter [box,tent,lanczos4,mitchell,kaiser], default=kaiser
-gamma # - Mipmap gamma correction value, default=2.2, use 1.0 for linear
-blurriness # - Scale filter kernel, >1=blur, <1=sharpen, .01-8, default=.9
-wrap - Assume texture is tiled when filtering, default=clamping
-renormalize - Renormalize filtered normal map texels, default=disabled
-maxmips # - Limit number of generated texture mipmap levels, 1-16, default=16
-minmipsize # - Smallest allowable mipmap resolution, default=1

Compression options:
-alphaThreshold # - Set DXT1A alpha threshold, 0-255, default=128
 Note: -alphaThreshold also changes the compressor's behavior to
 prefer DXT1A over DXT5 for images with alpha channels (.DDS only).
-uniformMetrics - Use uniform color metrics, default=use perceptual metrics
-noAdaptiveBlocks - Disable adaptive block sizes (i.e. disable macroblocks).
-compressor [CRN,CRNF,RYG,ATI] - Set DXTn compressor, default=CRN
-dxtQuality [superfast,fast,normal,better,uber] - Endpoint optimizer speed.
            Sets endpoint optimizer's max iteration depth. Default=uber.
-noendpointcaching - Don't try reusing previous DXT endpoint solutions.
-grayscalsampling - Assume shader will convert fetched results to luma (Y).
-forceprimaryencoding - Only use DXT1 color4 and DXT5 alpha8 block encodings.
-usetransparentindicesforblack - Try DXT1 transparent indices for dark pixels.

Ouptut pixel format options:
-usesourceformat - Use input file's format for output format (when possible).

All supported texture formats:
-DXT1
-DXT2
-DXT3
-DXT4
-DXT5
-3DC
-DXN
-DXT5A
-DXT5_CCxY
-DXT5_xGxR
-DXT5_xGBR
-DXT5_AGBR
-DXT1A
-ETC1
-ETC2
-ETC2A
-ETC1S
-ETC2AS
-R8G8B8
-L8
-A8
-A8L8
-A8R8G8B8

Note: .CRN only supports DXTn pixel formats, NWN only support DXT1 and DXT5 formats.

Basic Usage

The basic usage would be, eg in powershell to convert all PNGs in the "in" folder, to a DDS DTX1 (no alpha) image, with a yflip, quietly:

.\nwn_crunch.exe -file -i "in\*.png" -outdir "out" -fileformat dds -DXT1 -yflip -quiet

DDS Options

The main thing might be what DDS options you want to use, primarily you want to use these as per the convert_dds_mtr batch and convert_dds_portrait files:

File Type	DTX type	Other options	Notes
Diffuse	-DXT5A		Not all diffuse textures require the alpha channel (ie if no transparency) so can use DTX1 for those
Normal	-DXN	-normalize -uniformMetrics	DXN appears to be "3DC" compression
Specular	-DXT5A
Metallicness	-DXT5A	-minvalue 5
Roughness	-DXT5A	-invertcolors
Glossiness	-DXT5A
Height	-DXT5A
Illumination	-DXT1		No transparency allowed on illumination
Portrait
Portrait	-DXT1	-deep -recreate -mipmode none	See notes on mipmaps below - by default portraits won't load mipmaps meaning this isn't an issue, but if you ever do enable them and a DDS hasn't got them it will crash the game so be careful - you can always use just the -DXT1 setting and ignore the mipmode one

Some Options Breakdown

Some of these are not in the readme or not clear from the readme how they work. I've found these to be the most relevant for most texture work on diffuse textures (the other MTR ones it is recommended to use the settings above).

Option Name	Values (if any)	Example	Description and Notes
i	folder name	-i "in\."	The input - in the example all files in the "in" folder in the same location as the exe, of any file extension
outdir	folder name	-outdir "out"	The output directory, in the example it is the "out" on in the same location as the exe
nostats		-nostats	Removes stats from the output to the console
noprogress		-noprogress	Removes progress on converting things from the output to the console
quiet		-quiet	Removes all console information (use this wisely - it really doesn't tell you what it's doing at all!)
logfile	file name	-logfile log.txt	Log file, which contains all the progress and any issues
fileformat	dds / png / nwn then the type if DDS	-fileformat dds -DXT1	Output file format. Don't use "nwn" anymore, that's for 1.69 only, use DDS instead. Use PNG usually when converting from DDS or similar.
DXT1		-fileformat dds -DXT1	Standard DDS file with no alpha transparency. Saves a significant magnitude of space compared to DXT5A if you don't need alpha.
DXT5A		-fileformat dds -DXT5A	Standard DDS file with alpha transparency
quality	0 - 255	-quality 10	The DDS quality factor to use; it defaults to 255 so no need to include usually.
rescale	X Y	-rescale 512 512	This is useful for doing all the rescaling of a large image into a smaller one (eg; for a portrait H, L, M, S, T variants all at once). Can produce the best results compared to doing the resizing out of crunch from my experiments - if you use powers of two! If you don't use powers of two look at the rescalemode option.
yflip		-yflip	Will flip on the Y axis, which can be required for converting to DDS files if your original image is "the right way up".
deep		-deep	Recurse subdirectories
recreate		-recreate	Recreate the subdirectories if "-deep" is used
mipmode	UseSourceOrGenerate, UseSource, Generate, None	-mipmode none	The default is UseSourceOrGenerate, which is fine for 99% of NWN content, but for portraits you might want to use "-mipmode none" since it saves a lot of disk space and portraits don't use mipmaps by default. CAVEAT HOWEVER: Portraits can use mipmaps if the TXI file that changes this setting is overriden, meaning mipmaps plus the UI scaling of the game can correctly use them at different mipmap sizes as needed. The space saving isn't huge anyway, even at high resolutions, so probably not worth disabling since it can crash the game if a DDS file doesn't have a mipmap when it should.

Page tree