WadMerge Help

A utility for making simple build scripts for compiling together projects made of several files into a single WADs, or merging WADs of different kinds together. Very flexible.

wadmerge build.txt

You can make snazzy build scripts that look like this!

create outwad

datemarker outwad __VER__

# Merge in maps.
mergewad outwad maps/map01.wad
mergewad outwad maps/map02.wad
mergewad outwad maps/map03.wad

# Merge in textures.
marker outwad pp_start
mergedir outwad textures/patches
marker outwad pp_end
marker outwad ff_start
mergedir outwad textures/flats
marker outwad ff_end

mergedeutexfile outwad textures/texture1.txt

# Export to file.
finish outwad build/mymod.wad
end
			

Go crazy!

Full Command Help

WadMerge v1.11.0 by Matt Tropiano (using DoomStruct v2.15.8)
Usage: wadmerge [--help | -h | --version]
                [switches] [scriptfile] [arguments]

    --help        Prints help and exits.
    -h

    --version     Prints version, and exits.

    --changelog   Prints the changelog, and exits.

    --gui         Starts the GUI version of this program.

[switches]:
    --verbose     Prints verbose output.
    -v

[scriptfile]:
    <filename>    The input script file.

    --            Script input is from Standard In, not a file.

    If a file is not specified, ./wadmerge.txt is the default file.
    The parent directory of the provided script becomes the working directory.

[arguments]:
    The arguments to pass to the script. Script arguments are injected into
    commands by just adding "$" plus the argument index. (e.g. $0) A
    doubled-up $ ($$) is interpreted as one "$".

    The argument index references can be in any part of the parsed tokens, not
    just by themselves as a singular token. They are parsed at the token level,
    not the line level.

    Arguments: ["apple", "banana", "doom stuff"]
    mergedir $1 ./$0/$1phone $2
    Expands to:
    mergedir "banana" "./apple/bananaphone" "doom stuff"

Script Commands
...............

END
    Ends script read.

ECHO [...]
    Prints tokens to output.
    [...]: The tokens to print.

CREATE [symbol] [opt:iwad]
    Creates a new in-memory buffer, errors out if the symbol exists.
    Buffers are best used for speed, but large merges will consume
    lots of memory during merge.
    [symbol]: The symbol for the new buffer.
    [iwad]:   (Optional) If "iwad", the created WAD buffer is an IWAD.
    ................................
    Returns: OK if a symbol was created.
             BAD_SYMBOL if the destination symbol already exists.

CREATEBUFFER [symbol] [capacity] [opt:increment] [opt:iwad]
    Creates a new in-memory buffer, errors out if the symbol exists.
    Buffers are best used for speed, but large merges will consume
    lots of memory during merge. This differs from CREATE such that
    you can control the initial capacity or incremental capacity of
    the new buffer.
    [symbol]:    The symbol for the new buffer.
    [capacity]:  The buffer capacity in bytes.
    [increment]: (Optional) The buffer increment (if more bytes are needed)
                 in bytes. 0 or less doubles the buffer size.
    [iwad]:      (Optional) If "iwad", the created WAD buffer is an IWAD.
    ................................
    Returns: OK if a symbol was created.
             BAD_SYMBOL if the destination symbol already exists.
             BAD_SIZE if the capacity or increment is an illegal value.

CREATEFILE [symbol] [path] [opt:iwad]
    Creates a new WAD file (on disk - not in memory), errors out if 
    the symbol exists or the new file could not be created.
    WARNING: If the file already exists, it is OVERWRITTEN!
    Files are best used for memory efficiency, but large merges will
    incur lots of overhead as the output file grows.
    See: CREATE for the in-memory version.
    [symbol]: The symbol for the new buffer.
    [path]:   The file to create.
    [iwad]:   (Optional) If "iwad", the created WAD file is an IWAD.
    ................................
    Returns: OK if creation successful and a symbol was created.
             BAD_SYMBOL if the destination symbol is invalid.

CLEAR [symbol]
    Clears an existing buffer, errors out if the symbol does not exist.
    If the symbol is a file, it is deleted and rebuilt.
    [symbol]: The symbol for the existing buffer to clear.
    ................................
    Returns: OK if successful.
             BAD_SYMBOL if the symbol is invalid.

DISCARD [symbol]
    Discards an existing buffer, errors out if the symbol does not exist.
    If the symbol is a file, it is closed.
    [symbol]: The symbol for the existing buffer to discard.
    ................................
    Returns: OK if successful.
             BAD_SYMBOL if the symbol is invalid.

SAVE [symbol] [file]
    Exports the content of a symbol to a WAD file. Directories are created for
    the file, if they don't exist. If the symbol is a WAD file (not buffer)
    and the destination is the same file, nothing happens.
    WARNING: If the target file already exists, it is OVERWRITTEN!
    [symbol]: The symbol to export.
    [file]:   The file to create and export to.
    ................................
    Returns: OK if export successful.
             BAD_SYMBOL if the symbol is invalid.

LOAD [symbol] [file]
    Creates a new in-memory buffer by loading an existing WAD file
    into memory. The symbol must not already exist.
    [symbol]: The buffer to create.
    [file]:   The WAD file to read.
    ................................
    Returns: OK if successful.
             BAD_FILE if the file does not exist or is a directory.
             BAD_WAD if the file is not a WAD.
             BAD_SYMBOL if the destination symbol is invalid.

FINISH [symbol] [file]
    Exports the content of a symbol to a WAD file. Directories are created for
    the file, if they don't exist. If the symbol is a WAD file (not buffer) and
    the destination is the same file, nothing happens. The symbol is discarded.
    WARNING: If the target file already exists, it is OVERWRITTEN!
    [symbol]: The symbol to export.
    [file]:   The file to create and export to.
    ................................
    Returns: OK if export successful.
             BAD_SYMBOL if the symbol is invalid.

VALID [symbol]
    Asserts that a symbol is a valid buffer.
    [symbol]: The symbol to test.
    ................................
    Returns: OK if valid.
             BAD_SYMBOL if the symbol is invalid.

MARKER [symbol] [name]
    Adds an empty entry to [symbol] called [name].
    [symbol]: The symbol to add to.
    [name]:   The name of the marker.
    ................................
    Returns: OK if add successful.
             BAD_SYMBOL if the destination symbol is invalid.

DATEMARKER [symbol] [name]
    Adds an entry to [symbol] called [name] with the current date.
    [symbol]: The symbol to add to.
    [name]:   The name of the marker.
    ................................
    Returns: OK if add successful.
             BAD_SYMBOL if the destination symbol is invalid.

MERGE [dest-symbol] [src-symbol]
    Adds all entries from [src-symbol] into [dest-symbol].
    [dest-symbol]: Destination symbol.
    [src-symbol]:  Source symbol.
    ................................
    Returns: OK if merge successful,
             BAD_SYMBOL if the destination symbol is invalid,
             BAD_SOURCE_SYMBOL if the source symbol is invalid.

MERGEWAD [symbol] [path]
    Reads WAD entries from [path] into buffer [symbol].
    [symbol]: The symbol to add to.
    [path]:   The WAD contents to add.
    ................................
    Returns: OK if merge successful,
             BAD_FILE if the file does not exist or is a directory,
             BAD_WAD if the file is not a WAD,
             BAD_SYMBOL if the destination symbol is invalid.

MERGENAMESPACE [dest-symbol] [src-symbol] [namespace] [opt:amend]
    Adds all entries from [src-symbol] into [dest-symbol] that
    lie between [namespace]_START and  [namespace]_END, excluding
    the START/END namespace markers.
    [dest-symbol]: Destination symbol.
    [src-symbol]:  Source symbol.
    [namespace]:   Namespace name (e.g. FF, PP, TX).
    [amend]:       (Optional) If "amend", find the namespace in the
                   destination and append to its end. If the namespace does not
                   exist in the destination, it is created.
    ................................
    Returns: OK if merge successful,
             BAD_SYMBOL if the destination symbol is invalid,
             BAD_SOURCE_SYMBOL if the source symbol is invalid,
             BAD_NAMESPACE if the namespace could not be found or is incomplete.
             BAD_NAMESPACE_RANGE if the namespace entries are not in sequence.

MERGENAMESPACEFILE [symbol] [path] [namespace] [opt:amend]
    Reads WAD entries from [path] into buffer [symbol] that
    lie between [namespace]_START and  [namespace]_END, excluding
    the START/END namespace markers.
    [symbol]:    The symbol to add to.
    [path]:      The WAD contents to add.
    [namespace]: Namespace name (e.g. FF, PP, TX).
    [amend]:     (Optional) If "amend", find the namespace in the
                 destination and append to its end. If the namespace does not
                 exist in the destination, it is created.
    ................................
    Returns: OK if merge successful,
             BAD_FILE if the file does not exist or is a directory,
             BAD_WAD if the file is not a WAD,
             BAD_SYMBOL if the destination symbol is invalid,
             BAD_SOURCE_SYMBOL if the source symbol is invalid,
             BAD_NAMESPACE if the namespace could not be found or is incomplete.
             BAD_NAMESPACE_RANGE if the namespace entries are not in sequence.

MERGEFILE [symbol] [path] [opt:entryname]
    Reads file from [path] into [symbol].
    NOTE: Specifying a target entry name will override any replacement
    behavior set by FILECHARSUB.
    [symbol]:    The symbol to add to.
    [path]:      The file to add.
    [entryname]: (Optional) If specified, this is the name to use as
                 the imported entry.
    ................................
    Returns: OK if merge successful,
             BAD_SYMBOL if the destination symbol is invalid,
             BAD_FILE if the provided file does not exist or is a directory.

MERGEMAP [dest-symbol] [targetmap] [src-symbol] [opt:sourcemap]
    Reads a single map from the source, appending it to the destination.
    [dest-symbol]: The symbol to add to.
    [targetmap]:   The map to add (map header).
    [src-symbol]:  The buffer to read from.
    [sourcemap]:   (Optional) If specified, this is map to read
                   from the source symbol, and the target is the
                   new header name. If not, [targetmap] is read.
    ................................
    Returns: OK if merge successful,
             BAD_SYMBOL if the destination symbol is invalid,
             BAD_SOURCE_SYMBOL if the source symbol is invalid,
             BAD_MAP if the map entries are malformed.

MERGEMAPFILE [symbol] [targetmap] [path] [opt:sourcemap]
    Reads a single map from the source WAD, appending it to the destination.
    [symbol]:    The symbol to add to.
    [targetmap]: The map to add (target header).
    [path]:      The source WAD file to read from.
    [sourcemap]: (Optional) If specified, this is map to read
                 from the source WAD, and the target is the
                 new header name. If not, [targetmap] is read.
    ................................
    Returns: OK if merge successful,
             BAD_SYMBOL if the destination symbol is invalid,
             BAD_FILE if the file does not exist or is a directory,
             BAD_WAD if the file is not a WAD,
             BAD_MAP if the map entries are malformed.

MERGEDIR [symbol] [path] [opt:nomarkers]
    Adds a directory and its subdirectories recursively (files first, then
    directory contents, per directory).
    For each FILE in [path],
        If FILE is a directory,
            MARKER [symbol] \[FILE]
            MERGEDIR [symbol] [FILE]
        Else if file is a WAD,
            MERGEWAD [symbol] [FILE]
        Else,
            MERGEFILE [symbol] [FILE]
    [symbol]:    The buffer to add to.
    [path]:      The source directory to scan.
    [nomarkers]: (Optional) If "nomarkers", omit the directory markers.
    ................................
    Returns: OK if merge successful,
             BAD_SYMBOL if the destination symbol is invalid,
             BAD_DIRECTORY if the provided file is not a directory.

MERGEWADDIR [symbol] [path]
    Adds a directory and its subdirectories recursively (files first, then
    directory contents, per directory), but only the WAD files (by type and
    extension).
    For each FILE in [path],
        If FILE is a directory,
            MERGEDIR [symbol] [FILE]
        Else if file is a WAD,
            MERGEWAD [symbol] [FILE]
        Else,
            Skip file.
    [symbol]: The buffer to add to.
    [path]:   The source directory to scan.
    ................................
    Returns: OK if merge successful,
             BAD_SYMBOL if the destination symbol is invalid,
             BAD_DIRECTORY if the provided file is not a directory.

MERGEENTRY [dest-symbol] [entry] [src-symbol] [opt:src-entry]
    Adds an entry from [src-symbol] to [dest-symbol].
    The entry copied is first entry found by the provided name.
    [dest-symbol]: The destination buffer.
    [entry]:       The entry to add.
    [src-symbol]:  The source buffer.
    [src-entry]:   (Optional) If specified, [src-entry] is the entry to read
                   from [src-symbol], and [entry] is the new name for the
                   entry.
    ................................
    Returns: OK if merge successful,
             BAD_SYMBOL if the destination symbol is invalid,
             BAD_SOURCE_SYMBOL if the source symbol is invalid,
             BAD_ENTRY if the entry could not be found.

MERGEENTRYFILE [symbol] [entry] [path] [opt:src-entry]
    Adds an entry from a source WAD to [symbol].
    The entry copied is first entry found by the provided name.
    [symbol]:    The destination buffer.
    [entry]:     The entry to add.
    [path]:      The source buffer.
    [src-entry]: (Optional) If specified, [src-entry] is the entry to read
                 from [src-symbol], and [entry] is the new name for the
                 entry.
    ................................
    Returns: OK if merge successful,
             BAD_SYMBOL if the destination symbol is invalid,
             BAD_SOURCE_SYMBOL if the source symbol is invalid,
             BAD_ENTRY if the entry could not be found,
             BAD_FILE if the file does not exist or is a directory,
             BAD_WAD if the file is not a WAD.

MERGESWANTBLS [symbol] [path]
    Reads file from [path], interprets it as a SWANTBLS file, creates two
    entries in [symbol]: ANIMATED and SWITCHES.
    [symbol]: The symbol to add to.
    [path]:   The file to read.
    ................................
    Returns: OK if the file was found and contents were merged in,
             BAD_SYMBOL if the destination symbol is invalid,
             BAD_DIRECTORY if the provided file is not a directory,
             BAD_PARSE if the input file had a parse error.

MERGEDEUTEXFILE [symbol] [path] [opt:entry] [opt:strife]
    Reads file from [path], interprets it as a DEUTeX texture/patch assembly
    file, creates/amends TEXTUREx/PNAMES. The name of the file is the name of
    the texture lump.
    [symbol]: The symbol to add to.
    [path]:   The file to read.
    [entry]:  (Optional) If specified, the name of the entry to write.
    [strife]: (Optional) If "strife", the texture entry is read and/or
              written as a Strife-formatted texture set.
    ................................
    Returns: OK if the file was found and contents were merged in,
             BAD_SYMBOL if the destination symbol is invalid,
             BAD_PARSE if the input file had a parse error,
             BAD_FILE if the file does not exist or is a directory.

MERGETEXTUREDIR [symbol] [path] [entry] [opt:strife]
    Imports a directory's files as Doom Patches (or PNGs) and adds them
    to either a new or already-existing P or PP namespace and texture set entry
    (plus PNAMES).
    [symbol]: The symbol to add to.
    [path]:   The directory to read.
    [entry]:  The name of the texture entry to write/append to.
    [strife]: (Optional) If "strife", the texture entry is read and/or
              written as a Strife-formatted texture set.
    ................................
    Returns: OK if the file was found and contents were merged in,
             BAD_FILE if a file could not be read,
             BAD_SYMBOL if the destination symbol is invalid,
             BAD_DIRECTORY if the provided file is not a directory.

FILECHARSUB [char] [replacement]
    Sets a character replacement mapping (from this command onward) for
    auto-merged lumps that come from file names. The intended use for this is
    for renaming files to lump names that may have characters that can't be
    used in file names in your filesystem.
    For example: "VILE^1.lmp" will import as "VILE\1" if the following
    was set:
        FILECHARSUB ^ \
    [char]:        The character to replace (first character is used).
    [replacement]: The replacement character (first character is used).
    ................................
    Returns: OK.

		

CHANGELOG

### Changed for 1.11.0

* `Changed` MERGETEXTUREDIR now works on a "P" namespace if it exists in the target buffer.


### Changed for 1.10.1

* `Fixed` [GUI] Editor would error out on workspace load with no files open.


### Changed for 1.10.0

* `Added` New command: CREATEBUFFER (Enhancement #93).


### Changed for 1.9.1

* `Fixed` [GUI-Editor] Opening a file filtered the wrong kind of files (WadScript, not WadMerge). (Issue #88)
* `Changed` [GUI-Executor] The working directory form field will not auto-fill unless it is blank.


### Changed for 1.9.0

* `Added` [GUI] Verbose output flag for running scripts.
* `Added` MERGEENTRY and MERGEENTRYFILE commands.


### Changed for 1.8.0

* `Added` A `--charset` switch for specifying the encoding of the script files (if not system default).
* `Added` The WadMerge GUI, plus a switch to start it (`--gui`).


### Changed for 1.7.0

* `Added` `FILECHARSUB` command for declaring filename character substitutions on import.
* `Changed` Some behavior to accommodate the character substitution logic.


### Changed for 1.6.0.1

* `Fixed` Some documentation inconsistencies.


### Changed for 1.6.0

* `Added` MERGEDEUTEXFILE can now write a Strife texture entry set.
* `Added` MERGETEXTUREDIR can now write a Strife texture entry set and replace/amend sets and namespaces.
* `Changed` MERGENAMESPACE/MERGENAMESPACEFILE can now optionally import into an existing matching namespace in the destination.


### Changed for 1.5.1

* `Fixed` Saving a WAD from a buffer didn't output a message (introduced in previous version).


### Changed for 1.5.0

* `Changed` Added ability to create IWAD buffers via CREATE and CREATEFILE.
* `Changed` Some non-verbose message output.


### Changed for 1.4.0

* `Added` An argument for MERGEDIR to omit the directory markers.
* `Added` Support for argument expansion in scripts.
* `Added` MERGEWADDIR for just merging in WADs found in a directory search.
* `Fixed` Handling of PNAMES in MERGEDEUTEXFILE for multiple TEXTURE entries 
  ([Issue 4](https://github.com/MTrop/DoomTools/issues/4)).


### Changed for 1.3.0

* `Fixed` Some performance improvements and verbose output performance.
* `Added` MERGENAMESPACE[FILE] command for merging/importing entry namespaces.
* `Changed` Strings can be bound in double quotes and escape sequences for single tokens.


### Changed for 1.2.0

* `Fixed` Made directory sorting consistent across all merge commands.


### Changed for 1.1.0

* `Added` The `CREATEFILE` command for creating a File instead of a Buffer.
* `Changed` If a problem occurs in any command execution, a better error message is output.
* `Changed` The `MERGEDIR` command sorts files alphabetically, files first, then directories.


### Changed for 1.0.0

* Initial Release.