[Guide] How to set up ZDL [Updated 8/16/23]

Handy guides on how to do things, written by users for users.

Moderators: GZDoom Developers, Raze Developers

Forum rules
Please don't start threads here asking for help. This forum is not for requesting guides, only for posting them. If you need help, the Editing forum is for you.
User avatar
R4L
Global Moderator
Posts: 419
Joined: Fri Mar 03, 2017 9:53 am
Preferred Pronouns: He/Him
Operating System Version (Optional): Windows 11 Pro
Graphics Processor: ATI/AMD with Vulkan/Metal Support

[Guide] How to set up ZDL [Updated 8/16/23]

Post by R4L »

The Problem
You've seen it or have personally experienced it: You downloaded a cool Doom mod that has multiple files but, you have no idea how to load it. You drag and drop multiple .pk3s onto your GZDoom or Zandronum executable and that seems to work, but something is wrong! The mod isn't loaded correctly, or worse, it failed to load at all!

The Solution
If you are new to modding Doom or modding in general, this is obviously a huge frustration. You just want to play! One thing I've seen mentioned a lot online is that the mod files aren't in the proper order. A lot of times, a very brief explanation is given, and for a newbie these explanations can be jarring.

I won't waste time explaining how to use a batch file or command line to run mods, that's not the scope of this article. Instead, I will show you how to use ZDL, a launcher for Doom.

Where do I get ZDL?
First, a pre-requisite. You need Microsoft Visual C++ 2010 Service Pack 1 Redistributable x86 (vcredist_x86.exe). ZDL won't run without it.

I personally like lcferrum's fork, which you can find the downloads here. I'm using Windows, so this guide is tailored for Windows. Download the latest version of ZDL for Windows and extract it somewhere you have access to. For me, it's easiest to make a new folder in My Documents.

ZDL - Setup
For this article, I'm going to use my own mod, Metroid: Demon Hunter, as a reference since my project uses multiple files that need to be loaded in a precise order and Freedoom 2, since it's free to use. You can get Freedoom 1+2 together here for free.

First, open ZDL. You'll be greeted with a rather empty looking application:


The first thing to note is the General Settings tab. Click there first, we have to set up our source port of choice and any IWADs to load. An IWAD is basically a base game WAD file that comes with retail versions of Doom/Final Doom. For Doom II: Hell on Earth for example, you would want to find DOOM2.wad in your Doom II install directory. For this tutorial, we are going to use Freedoom 2 for our IWAD.

Under IWADs, click on the + symbol. Now browse to your copy of Doom II or Freedoom. My copy of Freedoom is in My Documents in a Freedoom folder:


Click Open. You'll See Freedoom listed an an IWAD now:


Cool! We're 1/3rd of the way there! Now, under Source ports, click the + symbol and this time you're going to find your GZDoom or Zandronum executable. My GZDoom executable is in a GZDoom folder in My Documents, so I'm going to browse there. Your ZDL settings should look similar to this so far:


Now we're 2/3rds of the way done! Click on the Launch Config tab at the top. On the right hand side, you will see your source port listed and your newly added IWAD:


Optional: I highly recommend that you take a second to save your ZDL settings! To do this, click on the ZDL button and choose Save .zdl. Name it and save it somewhere you can find it. Now, if you ever need to revert back to these base settings, you can simply load this file. You can also do this to save profiles of loadouts for certain mods!

How To Add Mods & Change The Load Order
For the last step, you can start adding your mod files to the External Files section. Click the + symbol under the External Files section and start adding your mod files:


If I were to load my mod right now, it will fail:


The issue is that my mod and many others have to be loaded in a specific order. For my mod, I should be loading my .pk3 files in this order:
  1. Main.pk3
  2. Metroid Levels.pk3
  3. Scans.pk3
The reason for this is rather complicated, but basically for certain things to be loaded, it depends on other things to be loaded first.

To change the order of the files loaded, simply click on one you need to move and click the Up or Down Arrow buttons on the bottom:
[imgur]blob:https://imgur.com/52ecdbb5-2e5e-4f38-ba26-49ee43861953[/imgur]

Now to make sure this works, I will make sure GZDoom/Zandronum is selected under Source Port and that my IWAD is also selected by clicking on Freedoom 2. If everything looks good, click the Launch button. GZDoom will load your mod!


And that's it! Like I said earlier, order is important for mods. With ZDL though, things are much easier with the added bonus of being able to save presets!

Happy Dooming!

Did I miss something? Please let me know and I'll add it in!

Change Log:

8/16/23 - Added Microsoft Visual C++ 2010 Service Pack 1 Redistributable x86 pre-requisite information.
Jareth247
Posts: 31
Joined: Mon Mar 20, 2023 3:16 pm
Preferred Pronouns: He/Him
Location: Avon, NC

Re: [Guide] How to set up ZDL [Updated 8/16/23]

Post by Jareth247 »

If anyone wants to know how to add mods to their Steam library there's two ways I do it.

The first is if you only need to add a few mods.
  1. Make a .ZDL file for your mod and copy the filename (i.e Abysm - Dawn of Innocence.zdl).
  2. Go into Steam and click "Add a Game", choose "Add a Non-Steam Game" and select ZDL.exe.
  3. Once added, right-click on ZDL.exe in your Steam Library and choose properties. Change "ZDL" to the name of your mod (i.e. Abysm 1 - Dawn of Innocence). Under "Launch Options", paste the file name and enclose it in quotations (i.e. "Abysm - Dawn of Innocence.zdl"). You can also paste it in "Target" next to the ZDL.exe's location (i.e. "C:\Games\FPS\ZDL\ZDL.exe" "Abysm - Dawn of Innocence.zdl").
  4. OPTIONAL: go to SteamGridDB and get the artwork for your mod. To do this, install a program called SGDB Boop, follow its setup and on the page for the mod (i.e. https://www.steamgriddb.com/game/5352544 for Abysm - Dawn of Innocence), find the artwork you want and click the blue button (it should say "Apply with BOOP (non-Steam)" when you hover over it and when the list of non-Steam games comes up, pick the one with the same name as your mod.
I made the last step optional since many mods don't have pages on SteamGridDB.

But if you're adding several, or a dozen, or in my case 127 (as of 7/14/2024), you'll definitely want to use a program designed to manage ROMs in your Steam Library. I use Steam Rom Manager. What I did was make a custom parser named GZDoom mods.
  • The "ROMS DIRECTORY" should be the folder you keep all your .ZDL files
  • Under "COMMAND LINE ARGUMENT", put in "${title}.zdl" with the quotes
  • Under "USER'S GLOB" put in ${title}.@(zdl)
A major downside to using Steam Rom Manager is that when it gets the artwork, it might not get the right artwork and might not have the right name, especially if you have less well-known mods.

Return to “Tutorials”