[Experimental] ZDRay - Lightmapping utility for GZDoom

[Redneckerz]

Disclaimer: Read the credits. Use ZDRay only with the build that is featured in GZDoom-ZDRay!

 

This is going to be a lengthy and thorough thread. In the middle of this i have added a line for those who just want a less detailed explanation. For those who want more, well there is more.

 

Looking for GZDoom-ZDRay? Look here.

 

Introduction:
I am making this thread because the contents of this originally resided at Discord. I felt it made sense to have it archived here for historic purposes, similar to the ZDuke port, and to provide a complete package for users to toy with. A lot of info was harvested from picking apart the ZDoom Discord and compiling it together for this thread.

 

This is provided as-is. It represents a compiled snapshot of experimental work that has since become abandoned by its creator (dpJudas). I am an archivist/editor, not a developer. It may or may not work on your system.

 

A special thanks to Rachael for generously hosting this and Nash for the majority grunt of getting this together and providing the latest working build.

 

Do not pester Judas, Rachael, Graf or Nash with feature requests or requesting it to be ported over to the latest GZDoom.

 

What this is:
It is a node generator and light baking utility for ZDoom. In the words of dpJudas: ''ZDRay is a node and lightmap generator. It is based on zdbsp for the node generation and dlight for the lightmap generation. Special thanks to Randi Heit, Samuel Villarreal, Christoph Oelckers and anyone else involved in creating or maintaining those tools.''

 

Basically, with this you are able to get Quake-style/Unreal style lightmaps in your Doom. It supports surface-based area lights (linedef or sector) and it has extended baking features like light bouncing, 3d floors, and so forth. The results can be quite incredible, thanks to Nash:

 

See this post here for more.

 

 

 

 

 

The contents are as follows:

 

zdray.7z:
This is the latest version of ZDRay as a standalone executable only.
Contents:

• zdray.exe
• map01unlit.wad: An unlit version of Nash's WAD fully baked in the gzdoom-zdray package for testing purposes.
• zdrayparameters.PNG: A screenshot of ZDRay's options prompt.

What this isn't:

• Something which will be in the latest GZDoom. Unless a variety of variables are met, this code as-is will never be in GZ.

To use ZDRay, the following parameters are available:

 

 

Downloads:
ZDRay
Readme

 

Stuff you may encounter:

• It *may* crash. It is experimental, after all!
• Won't work on all ZDoom slopes
• Sprites may not get correctly lit
• Setting up lights needs to be done manually in-editor
• You need to manually key in unsupported args into the things on the map
• You must create a lightconfig.txt file, it can be empty but you must at least insert 1 line
• ZDRay ideally works in tandem with a level editor. At the time, GZDoomBuilder-BugFix was the preferred solution, but you are better off using Ultimate Doom Builder
• And various other wonky stuff that may occur. This is experimental quality, so expect experimental fuckery along the way. See also the ''So how does this work, anyway?'' section for a more detailed usage on how to set this up

A more detailed background will now follow. Those who just want to download ''the goods''can exit this thread. For those who want to read further, stick by!

 

So how does this work, anyway?

I let Nash fill you in on this. What follows is a compiled explanation of his Discord commentary from 2019 and 2018. Be advised that Nash refers to GZDoomBuilder-Bugfix, so usage in Ultimate Doom Builder might be different, and things may contradict.

''You make your map in GZDB, then run your map through zdray.exe. The custom build of gzdoom would then be able to read that compiled data to draw complex shadows. So, basically the same workflow as building quake and unreal maps. In order to get baked lights, you have to specifically place them in the map, then run zdray on your wad. 2 ways:

 

• either set your lights to "static"
  or
• tag surfaces (sectors or lines; udmf only) to be light emitters. zdray will take care of the rest.

Currently (and understandably, as everything is so early in production) i use dynamic lights first for the blocking phase (because GZDB doesn't show static lighting) then when i'm finally satisfied, i convert all the dynamic lights to the UDMF static lights, by hand. then run zdray.''

 

dpJudas has a nice but sparse summary of the tool: ''You run a tool called zdray, like you run zdbsp today. It picks up certain UDMF properties from the map itself and sunlight properties from MAPINFO, then it bakes the lightmaps and generates the BSP nodes.''

 

UDMF Properties of ZDRay:

linedef
{
    lightcolor = <int> (color, default: white)
    lightintensity = <float> (default: 1)
    lightdistance = <float> (default: 0, no light)
}

thing
{
    lightcolor = <int> (color)
    lightintensity = <float> (default: 1)
    lightdistance = <float> (default: 0, no light)
    lightinnerangle = <float> (default: 180)
    lightouterangle = <float> (default: 180)
}

sector
{
    lightcolorfloor = <int> (color, default: white)
    lightintensityfloor = <float> (default: 1)
    lightdistancefloor = <float> (default: 0, no light)

    lightcolorceiling = <int> (color, default: white)
    lightintensityceiling = <float> (default: 1)
    lightdistanceceiling = <float> (default: 0, no light)
}

Package details:
Originally i planned on using the package provided by a user called Kizoky on Discord, but as it turns out through some more digging, as Kizoky's compile had some issues since a user back then couldn't get things to work. dpJudas provided a proper gzdoom.exe and the overall package then seemed to work, along with test maps. Nash then was kindly enough to compile a proper build of the latest state of the lightmaps branch compiled before dpJudas abandoned it, paired with the latest version of ZDRay, with the latest lightmaptest iteration with lights pre-built.

 

All ive done is some clean up, making a seperate standalone archive for ZDRay and including the unlit WAD.

 

Credits:

• The Strife VE team for their lightmapper, of which ZDRay is derived of
• Nash Muhandes for providing the latest compiled build of the ZDRay code, lit and unlit versions of his test map, derived fancy screenshots and ZDRay descriptions
• Rachael for hosting on the ZDoom servers so that it has a permanent home
• Magnus Norddahl (dpJudas) for the code work and test maps aswell as prior test builds
• Graf Zahl for the pull requests on the Github branch
• Kizoky for compiling zdray.zip, initial build package and initial uploading over at Discord

Links:

• Github (Latest source-only): ZDRay
• ZDoom thread

Edited January 17, 2020 by Redneckerz : Different title that suits the content better.