DoomMake Help

Alright, everybody. I've been hearing things.

I've been hearing that you are slapping together Doom projects all willy-nilly and kvetching about needing to pare back the textures used for the final product. I've been hearing that you've been wanting to get into MBF21 and/or DSDHACKED development, but the patch building is just one tiny piece of the puzzle. I've been hearing about some of you that manage your projects in single WADs and making one point of failure for your magnum opus, and perhaps need some kind of repository-driven solution.

I hear you need a better way. Well, guess what? That "better way" exists!


What if I told you that you could do all of those things in one command? You'd say I was crazy. But you can. Enter DoomMake.

DoomMake is a project builder for Doom mods. It's a program that builds a file system scaffolding where you throw everything in the correct directories and your wonderful WAD file pops out! Whether you are making something by yourself or with others, DoomMake does the heavy lifting when it comes time to package up your work before you send it out into the world!

"Heavy lifting," I might add, that includes exporting only the map textures necessary to play your mod, so that you don't have to do that manually!


The Most Common Project

Now, a lot of y'all are gonna be like, "Matt, you're a handsome, charismatic dreamboat, but what you are promising can't possibly be that easy." Well, aside from the parts where I'm a handsome, charismatic dreamboat, you're wrong. It IS that easy!

The most common kind of project is gonna be one with maps, loose assets, and textures from a texture WAD, right? DoomMake's got you covered. Type this at the command line to make that initial project structure:

doommake myproject --new-project assets texturewads maps

Then you'll have to answer some quick questions:

What is your project's WAD name (blank for "PROJECT")? SOMEJUNK
Path to project IWAD (blank to skip)? H:\Doom\IWADs\DOOM2.WAD

And then after some stuff gets generated, you'll see this in your project directory that was just created:

Those files and folders are the main scaffolding of your project. Those .script and .properties files are what drive the DoomMake build process. Everything is editable! If you update DoomMake itself (via DoomTools updates), your project's build will still work!

See that /src folder? Let's take a look inside!

Change that wadinfo.txt. That becomes your text file (and is imported as WADINFO in the final WAD file).

Record and maintain project credits in credits.txt. That gets imported as CREDITS in the final WAD, as well.

Put (or edit) all of your maps in /src/maps. Use your favorite map editor! Only the map WADs are read!

Throw your texture WADs in /src/wads/textures. You'll use those files for editing maps.

You've got a /src/assets folder for all of your loose assets:

A place for global-space stuff like DEMOs or GENMIDI or whatever, a place for graphics, music, sprites, or sounds, imported as-is.

The /src/convert directory will contain graphics, sounds, and sprites that get automatically converted on build and placed in asset directories.

But how are you going to edit all of those assets and whatnot? Easy! Using SLADE! It's got a directory mode! Just open that /src directory and you can move stuff in, alter, and save to the project structure!

And then when you're all done, just jump into your project directory at the command prompt, and type:



DoomMake will then chew through all of your project stuff, spit out some intermediate WAD files in the /build directory, and assemble your project as a texture-minified product in the /dist directory!

And there you have it. DoomMake is also smart enough to not rebuild stuff that didn't change, so you can keep rebuilding stuff as you edit other things.


What else can it do?

It also has templates for DECOHack (or other patch utilities), initializing a Git repository for your project (and Mercurial), and even running your project from DoomMake in your favorite source port! And if there's a tiny thing it doesn't support out of the box, you can edit all of the project scripts until it's how you like it.


What CAN'T it do?

Well... it doesn't put together GZDoom and Eternity PK3/PKEs out of the box, yet. But it's coming soon! Just need to figure out the best approach for that sort of thing. Nothing says you can't code that yourself in the DoomMake scripts! DoomTools (and DoomMake) should contain documentation about it.


Oh. Well, any help for other types of Doom projects?

Sure! Here's a webpage for giving you the correct command line for creating the project scaffolding of your dreams, plus a lot of extra information about all the different templates in your project:


There's even an example project that you can clone and build yourself using Git! BEHOLD IT'S POWER!


Who is using DoomMake?

All the cool kids are using DoomMake! Prominent authors! Me! Maybe YOU, one day!

Now, get out there and MAKE SOMETHING!

Full Command Help

DoomMake v0.26.0 by Matt Tropiano
(using DoomStruct v2.15.8 , WadScript v1.6.2, RookScript v1.15.0, RookScript-Desktop v1.10.2.1)
Usage: doommake [target] [args] [switches]
                [directory] --new-project [templates...]
                [--gui | --new-project-gui]
                [--list-templates | -t]
                [--help | -h | --version]
                [--function-help | --function-help-markdown]

    The target entry point to execute. Default is "make".

    The additional arguments to pass along to the script.

    The names of the template(s) to use or combine for the new project
    (applied altogether). Only one from each category is allowed.
    E.g.: --new-project maps git
        Combines the "maps", and "git" templates together.

    The directory/name for the new project.

    --help, -h                     Prints this help.
    --version                      Prints the version of this utility.
    --changelog                    Prints the changelog, and exits.
    --function-help                Prints all available function usages.
    --function-help-markdown       Prints all available function usages in
                                       Markdown format.
    --function-help-html           Prints all available function usages in
                                       HTML format.
    --function-help-html-div       Prints all available function usages in
                                       HTML format, but just the content.
    --disassemble                  Prints the disassembly for the make script
                                       in use and exits.


    --project-type [type]          Sets the project type. Possible values:
                                      WAD, TEXTURE
                                      Default: WAD

    --new-project, -n [templates]  Creates a new project made up of a set of
                                      templates (requires [directory]).

    --list-templates, -t           Lists all available project templates.


    --gui                          Opens this project in a graphical interface

    --studio                       Opens this project in DoomMake Studio.

    --new-project-gui              Opens the "New Project" GUI.


    --script, -s [filename]        Use [filename] for the root build script.
                                       Default is "doommake.script".
    --properties, -p [filename]    Use [filename] for the project properties.
                                       Default is "".

    --runaway-limit [num]          Sets the runaway limit (in operations)
                                       before the soft protection on infinite
                                       loops triggers. 0 is no limit.
                                       Default: 0
    --activation-depth [num]       Sets the activation depth to [num].
                                       Default: 256
    --stack-depth [num]            Sets the stack value depth to [num].
                                       Default: 2048


    --targets                      Displays all available targets for this


    --embed                        Embeds DoomTools/DoomMake into the current


    --auto-build                   Starts DoomMake as an agent for detecting
                                       changes in the current project and
                                       kicking off full builds when changes
                                       are detected.

    --auto-build-verbose           Same as above, except it produces more
                                       verbose output.

While the agent is listening on a project, any attempt to run any DoomMake
targets on that project will error out. In order to run targets, you can use:

    --agent-bypass                 Bypasses agent detection. USE WITH CAUTION.
                                       Used internally.


DoomMake has a variable scope called `global` that serves as a common variable
scope for sharing values outside of functions or for data that you would want
to initialize once.


### Changed for 0.26.0

* `Added` DoomMake will check to see if it is already embedded in a project if `--embed` is used.
* `Added` Code in base projects for specifying a "library" IWAD file for CI builds.
* `Changed` New projects that convert assets and textures will build them into the project build directory, and merged from there.
* `Changed` Fixed documentation/comments in the created build scripts.

### Changed for 0.25.1

* `Fixed` [GUI-Studio] Fixed a potential NPE on the file watch service.
* `Fixed` [GUI-Studio] Fix WAD detection on opened files.
* `Fixed` [GUI-Studio] Studio will no longer try to open binary files as text.

### Changed for 0.25.0

* `Changed` Added Doom Builder autosave ignores to Git and Mercurial ignore files.

### Changed for 0.24.0

* `Added` COPYWITHREPLACE function added to DoomMake.

### Changed for 0.23.1

* `Fixed` Corrected an IOError message for reopening a zip file.
* `Fixed` Potential NPE in ZIPDIR function if the source directory did not exist.
* `Fixed` Problems when appending to an existing Zip in ZIPFILES/ZIPDIR.

### Changed for 0.23.0

* `Changed` [GUI-Studio] Auto-build output now appears in the main log. (Enhancement #102)

### Changed for 0.22.0

* `Fixed` [GUI] DoomMake did not output `` in new projects.
* `Fixed` [GUI] "Do Nothing" option after project creation did not close the dialog (it *literally* did nothing).
* `Added` DoomMake now outputs property usage into the project with documentation. (Enhancement #94)

### Changed for 0.21.1

* `Changed` TOOL::DOOMFETCH documentation to reflect new parameters.

### Changed for 0.21.0

* `Added` TOOL::DOOMFETCH function.

### Changed for 0.20.1

* `Changed` [GUI-Studio] "Type unrecognized" on file open message: do not say "unrecognized" if we knew it was a WAD file.
* `Changed` [GUI-Studio] "Run DoomMake" menu entries to clarify function.

### Changed for 0.20.0

* `Fixed` [GUI] Repository managers attempted to call CMD on non-Windows OSes.
* `Fixed` [GUI] Opening a Terminal on macOS now works as intended.
* `Added` [GUI-Studio] Project search.

### Changed for 0.19.0

* `Added` A Texture WAD project type for new projects.

### Changed for 0.18.1

* `Fixed` [GUI] The Git repo manager did not pick up untracked changes.
* `Added` [GUI] The Beta version of the Mercurial repo manager.

### Changed for 0.18.0

* `Added` A "Studio" mode only runnable as a Desktop App.

### Changed for 0.17.0

* `Added` The `TOOL::WADTEX(...)` function was changed to support entry name override.
* `Added` The `TOOL::WSWANTBL(...)` function was changed to support source import.
* `Added` The `TOOL::WADMERGE(...)` function was changed to support alternate input charset encoding.
* `Added` The `TOOL::WADSCRIPT(...)` function was changed to support alternate input charset encoding.
* `Added` The `TOOL::DECOHACK(...)` function was changed to support alternate input charset encoding.
* `Added` Support for project-wide text encoding setting.
* `Changed` Default DECOHack source code output file was changed from `dehsrc.dh` to `decohack.dh`. More to the point.

### Changed for 0.16.0

* `Fixed` (GUI) GUI still checked for DoomMake on PATH in order to run. This was unnecessary. (Issue #69)
* `Added` The `TOOL::DECOHACK(...)` function was changed to support reading DECOHack source from STDIN.

### Changed for 0.15.0

* `Added` DoomMake Agent for listening for project changes. See help for more info!
* `Added` DoomMake GUI for individual projects and creating new ones.
* `Added` A `justrun` target for new projects using the `run` template to execute the project without building it.

### Changed for 0.14.0

* `Added` A switch for printing the targets for a project.
* `Changed` The conversion function in graphics conversions now looks for (and prioritizes) loose palette assets for source palettes (in asset global folder) (new projects).
* `Changed` Some WadMerge scripts for some templates to make use of the `FILECHARSUB` command for asset directory imports (new projects).

### Changed for 0.13.1

* `Fixed` The `texturewads` template added script lines that duped the extracted textures on export.

### Changed for 0.13.0

* `Added` `infiles` as a valid option field for `TOOL::DECOHACK`.
* `Changed` Improved HTML documentation output.
* `Changed` Single-patch texture generation added to the `textures` and `texturesboom` templates (new projects). (Enhancement #58)

### Changed for 0.12.0

* `Added` Some texture template types for Vanilla and Boom.
* `Changed` Template ordering and setup for other texture templates (new projects).
* `Changed` Some tweaks to default `.gitattributes` on Git template (new projects).
* `Changed` The project "TODO" list is now a Markdown file.
* `Changed` (Internal) Project Generator organization changes. (Issue #36)

### Changed for 0.11.0

* `Fixed` Some generated script documentation.
* `Changed` Attempting to reduce map textures without any texture WADs errors out (new projects).
* `Changed` Assets are now a separate template category.

### Changed for 0.10.0

* `Added` A patch source module for patches made in "not DECOHack".
* `Changed` `doClean()` will clean the build directory and distribution directories (new projects).
* `Changed` More informational output (new projects).

### Changed for 0.9.0

* `Added` `dsdhacked` as a valid DECOHack patch type.

### Changed for 0.8.0

* `Added` The ability to embed DoomMake into a project (`--embed` switch).

### Changed for 0.7.0

* `Added` The options for `TOOL::DOOMTOOLS`.
* `Added` Added including the DECOHack source in the result to DECOHack projects.
* `Added` A switch for dumping documentation as HTML. (Enhancement #45)
* `Fixed` Some tweaks to auto-detecting changes to projects.
* `Fixed` "Textures" template: Converting patches used the wrong default mode.
* `Changed` The options for `TOOL::DECOHACK` to include the source export.
* `Changed` Project TODO text file is now generated in uppercase: `TODO.txt`.
* `Changed` Repository "ignore" files changed slightly.

### Changed for 0.6.0

* `Added` HASHDIR() host function for detecting folder changes.
* `Added` Modules added for asset and texture auto-conversion of graphics and sound assets.
* `Added` The "--disassemble" switch. Not many people will use this.
* `Changed` New projects now auto-detect project changes on build.
* `Changed` The "TODO" list that gets printed at the end is now added to the project.

### Changed for 0.5.0

* `Added` Relocation of `src` directory via project property. (Enhancement #38)
* `Changed` The run module checks for default files generated and runs them automatically.

### Changed for 0.4.0

* `Added` A wizard during project creation.
* `Added` "TODOs" afterward when a project is made.
* `Added` A target for texture projects that can rebuild the TEXTUREx definition lists.

### Changed for 0.3.0

* `Added` All scripts can now make use of a global scope called `global`.

### Changed for 0.2.0

* `Added` Ability to invoke DImgConv.

### Changed for 0.1.1

* `Fixed` The `run` module did not write properly to the make script.
* `Fixed` Projects that are created without the init stubs do not try to append.
* `Added` Mercurial repository support (creates "ignore" file).

### Changed for 0.1.0

* Initial release.