DDS CLI
DDS commands inspect textures, crop regions, convert image formats, and generate X-Ray bump maps. Use sprite commands when a config or XML description defines a whole sheet, and THM commands to change a texture’s bump declaration.
Examples use paths relative to a gamedata or texture-working directory. Output commands write the named files; choose separate output paths when keeping the originals.
DDS inspection
xrf-cli dds info --path ./textures/ui/ui_icon_equipment.dds
Example output — inspect a DDS sheet:
Read dds file ./gamedata/textures/ui/ui_test_sheet.dds
File size: 16512 (16.1 KB)
Metadata size: 128
Data size: 16384 (16 KB)
Size: 256 x 64
Mipmap: 1 - 16
Linear size: 16384
Block size: 16
D3D format: DXT5
Exit code: 0.
The report includes dimensions, mipmaps, file and pixel-data sizes, compression, block size, bits per pixel, and known FourCC or D3D/DXGI formats. Pitch or linear size is included when present. Inspect these fields before selecting an output format or diagnosing a texture that the renderer cannot load.
Region cropping
Crop a single icon when its source sheet has no compatible inventory config:
xrf-cli dds crop --source ./textures/ui/ui_icon_equipment.dds --output ./wpn_ak74.png `
--x 1000 --y 0 --width 250 --height 100
Example output — crop a region:
Wrote 16x16 region from 0:0 of ./gamedata/textures/ui/ui_test_sheet.dds to ./height.png
Exit code: 0.
Coordinates and dimensions are pixels, measured from the top left. The source must contain the entire rectangle; out-of-bounds regions are rejected.
A .png output preserves the decoded pixels without another lossy encode. Any other output extension selects BC3 DDS.
Prefer PNG for subsequent packing; sprite pack-equipment selects <section>.png before <section>.dds.
Fitting into different bounds
Supply both fit dimensions to resize the crop into a fixed output rectangle:
xrf-cli dds crop --source ./ui_actor_weapons.dds --output ./upgrade_ak74.png --x 0 --y 400 `
--width 300 --height 100 --fit-width 295 --fit-height 110
Fitting preserves aspect ratio and centers the image on a transparent canvas. A crop already matching the requested bounds is unchanged. Equipment packing uses the same fitting behavior; description packing instead requires exact dimensions, so fit those icons before packing.
Convert a texture
Re-encode an existing DDS texture in an explicit format:
xrf-cli dds convert ./source.dds ./texture.dds --format bc3
xrf-cli dds info --path ./texture.dds
Example output — convert a DDS texture:
Converted ./gamedata/textures/ui/ui_test_sheet.dds to ./converted.dds as BC3 (DXT5), 9 levels, 22032 bytes
Exit code: 0.
Accepted formats are bc1, bc2, bc3, bc7, and rgba8. Choose a format supported by the target renderer and
appropriate for the texture’s alpha and quality requirements.
Conversion decodes the base image and rebuilds its mip chain. Use --no-mipmaps to write only the base level.
--mip-filter selects the reduction filter, defaulting to kaiser; --quality trades encoding time for fidelity,
defaulting to slow.
Add --compare to encode the other formats in memory and report their size and distortion alongside the selected
format. Only the selected format is written. Review the resulting texture visually as well as inspecting its metadata;
numerical error alone does not establish acceptable appearance.
Generate a bump pair
From a working directory containing a height image, generate the two DDS files used by an X-Ray bumped surface:
xrf-cli dds make-bump ./height.png ./textures/tile/wall --gloss-constant 0.5
Example output — generate a bump pair:
Generated .\wall_bump.dds and .\wall_bump#.dds from ./height.png
Exit code: 0.
The destination is a base path without an extension or _bump suffix. This example writes textures/tile/wall_bump.dds
and textures/tile/wall_bump#.dds.
Height is averaged across the input’s color channels. Supply --gloss for a gloss-mask image instead of a constant
between 0 and 1. An optional --normal-map supplies normals instead of deriving them from height; its dimensions must
match the height image. --virtual-height controls relief depth, defaulting to 0.05.
Bump generation uses the box mip filter by default. A warning about very dark gloss indicates little specular
response; the files are still written because a matte surface may be intentional.
Bump declarations
Generating or moving a bump texture does not update its descriptor. Follow the THM bump-declaration workflow to connect an existing descriptor to the new path, then verify the assembled texture set.
Command reference
xrf-cli dds convert
Command to re-encode a dds file into another format, with its mip chain rebuilt
xrf-cli dds convert [OPTIONS] --format <format> <SOURCE> <DESTINATION>
| Option | Required | Default | Description |
|---|---|---|---|
<SOURCE> | yes | Path of the dds file to read | |
<DESTINATION> | yes | Path of the dds file to write | |
--format <format> | yes | Format to write, of the five worth offering for an X-Ray texture. Possible values: bc1, bc2, bc3, bc7, rgba8. | |
--mip-filter <mip-filter> | kaiser | Kernel the mip chain is reduced with, from the X-Ray converter’s own family. Possible values: point, box, triangle, quadratic, cubic, catrom, mitchell, gaussian, sinc, bessel, hanning, hamming, blackman, kaiser. | |
--quality <quality> | slow | How hard the encoder works; slow costs seconds on BC7 and pennies on the rest. Possible values: fast, normal, slow. | |
--no-mipmaps | Write only the base level, for a texture the engine never minifies | ||
--compare | Also report what every other candidate format would have cost, which is four more encodes | ||
-s, --silent | Turn off logging | ||
-v, --verbose | Turn on verbose logging | ||
--json | Write the run’s JSON report to stdout, moving human output to stderr | ||
--report <PATH> | Write the run’s JSON report to a file |
xrf-cli dds crop
Command to crop a rectangular region out of a dds file into a new dds file
xrf-cli dds crop [OPTIONS] --source <source> --output <output> --x <x> --y <y> --width <width> --height <height>
| Option | Required | Default | Description |
|---|---|---|---|
--source <source> | yes | Path to the dds file to read the region from | |
--output <output> | yes | Path of the dds file to write | |
--x <x> | yes | Left edge of the region, in pixels | |
--y <y> | yes | Top edge of the region, in pixels | |
--width <width> | yes | Width of the region, in pixels | |
--height <height> | yes | Height of the region, in pixels | |
--fit-width <fit-width> | Scale the cropped region to this width, preserving aspect and letterboxing | ||
--fit-height <fit-height> | Scale the cropped region to this height, preserving aspect and letterboxing | ||
-s, --silent | Turn off logging | ||
-v, --verbose | Turn on verbose logging | ||
--json | Write the run’s JSON report to stdout, moving human output to stderr | ||
--report <PATH> | Write the run’s JSON report to a file |
xrf-cli dds info
Command to print information about provided dds file
xrf-cli dds info [OPTIONS] --path <path>
| Option | Required | Default | Description |
|---|---|---|---|
-p, --path <path> | yes | Path to dds file | |
-s, --silent | Turn off logging | ||
-v, --verbose | Turn on verbose logging | ||
--json | Write the run’s JSON report to stdout, moving human output to stderr | ||
--report <PATH> | Write the run’s JSON report to a file |
xrf-cli dds make-bump
Command to generate the _bump and _bump# pair a bumped surface binds, from a height map
xrf-cli dds make-bump [OPTIONS] <HEIGHT> <DESTINATION>
| Option | Required | Default | Description |
|---|---|---|---|
<HEIGHT> | yes | Path of the image the relief is read from, averaged across its colour channels | |
<DESTINATION> | yes | Path of the texture the pair belongs to, without the _bump suffix or an extension | |
--gloss <gloss> | Path of a gloss mask, averaged across its colour channels | ||
--gloss-constant <gloss-constant> | One gloss level for the whole surface, from 0 to 1, for a texture with no mask | ||
--normal-map <normal-map> | Path of a normal map to use instead of deriving one from the height, of the same size | ||
--mip-filter <mip-filter> | box | Kernel the mip chain is reduced with, from the X-Ray converter’s own family. Possible values: point, box, triangle, quadratic, cubic, catrom, mitchell, gaussian, sinc, bessel, hanning, hamming, blackman, kaiser. | |
--quality <quality> | slow | How hard the encoder works; slow costs seconds on BC7 and pennies on the rest. Possible values: fast, normal, slow. | |
--virtual-height <virtual-height> | 0.05 | Relief depth the normals are derived at, bump_virtual_height of the descriptor | |
-s, --silent | Turn off logging | ||
-v, --verbose | Turn on verbose logging | ||
--json | Write the run’s JSON report to stdout, moving human output to stderr | ||
--report <PATH> | Write the run’s JSON report to a file |