QLumpy2 - Command Line Interface

QLumpy2 accepts one or more script files to process sequentially.

Usage:

qlumpy2 [-archive directory] [-newwad] scriptfile [scriptfile ...]

• -archive <directory>: Backs up or archives the source image files to the specified directory during processing.

• -newwad: Enables modern Quake 1 WAD2 mode. When active, it changes the internal lump type IDs to match newer engine expectations; sets miptex lumps to 0x44 and raw lumps to 0x43.

Script File Syntax

Script files parse commands line by line.

• Comments: Any text following a semicolon (;) or a hash (#) is treated as a comment and ignored.

• Paths: Relative paths are anchored to your Current Working Directory.

Global Directives

Global directives control file I/O, output modes, and script flow. They must be declared before grabbing any image data.

• $LOAD <filename>: Loads a Targa (.tga) image file to serve as the source graphic for subsequent grab commands. QLumpy2 supports Type 1 (8-bit indexed) and Type 2 (24/32-bit RGB) TGA formats.

• $DEST <filepath>: Sets the output path for the compiled .wad file. If omitted, QLumpy2 defaults to creating a .wad in the current directory with the same base name as the script.

• $SINGLEDEST <directory>: Overrides standard WAD creation and forces QLumpy2 to export every grabbed lump as an individual .lmp file into the specified directory.

• $MIPDEST <directory>: Operates identically to $SINGLEDEST, but exports the individual textures with the .mip extension.

• $INCL <filename>: Includes an external script file and parses it inline. The inclusion stack allows for nesting up to 8 levels deep and features built-in protection against circular or self-referential inclusions.

Lump Extraction Commands

To extract data from the image loaded via $LOAD, define the lump name followed by the desired grab command.

• Format: <lumpname> <command> [parameters]

• Naming Restrictions: Lump names are automatically converted to uppercase and cannot exceed 15 characters in length.

Image Grabbing

• qpic <x> <y> <width> <height>: Grabs a standard Quake UI or HUD picture. The resulting lump includes a header specifying the width and height.

• miptex <x> <y> <width> <height>: Grabs a texture and generates four downsampled mipmap levels. The width and height must be exact multiples of 16.

• raw <x> <y> <width> <height>: Grabs raw pixel bytes directly from the active image area without appending any dimensional headers.

Color & Palette Commands

• palette [start] [end]: Grabs a chunk of the active palette data. If the start and end parameters are omitted, it defaults to capturing the entire 0–255 color range.

• colormap <levels> <fullbrights>: Generates a standard Quake colormap. It creates an identity map, followed by shaded levels that smoothly step toward black, keeping the designated number of fullbright colors (at the end of the palette) unaffected.

• colormap2 <range> <levels> <fullbrights>: Generates an experimental overbright color table, allowing the color range to exceed 1.0.

Miscellaneous

• pop: Injects a static, 128-byte Quake Proof-of-Purchase data block into the destination path/file (best to use with $SINGLEDEST only).

QLumpEd - LumpyScript Editor

QLumpEd is a work-in-progress GUI editor dedicated to LumpyScript file handling. It features, among other things, valid syntax highlighting (basic but working), GUI viewer with grab markers & lump names, working Zoom In/Out, and a few other small helpful features!

Also, assets/aex_tech.ls is a LumpyScript file from a test project during development, you may use it freely to understand LumpyScript syntax, and as a base to develop your own texture sets!

Technical Note: Automatic Palette Quantization

When you load an 8-bit Indexed TGA file, QLumpy2 can extract the palette data directly from the image. When you load a 24-bit or 32-bit RGB TGA file, QLumpy2 automatically maps the true-color pixels to an 8-bit palette.

1. It scans for a palette.lmp in the current directory to use as the color reference.

2. If palette.lmp is missing, it silently defaults to a built-in Quake fallback palette.

After the RGB-to-8-bit mapping, QLumpy2 calculates and reports a Palette Quality root-mean-square error (RMSE) score. If the score exceeds 15.0, the terminal will warn you that high color loss/distortion has occurred.

---

Development Questions/Support: aeroxsoftware@null.net