Workbench Script Debugging – DayZ

Using the diagnostic version of the game executable (DayZDiag_x64.exe), it is possible to connect Workbench tool to a running instance of the game client/server and break and debug it's execution.

File Setup

You will require official DayZ Tools where the Workbench tool is located and a way to unpack PBOs, using either the WorkDrive to unpack all the PBOs to your P:\ drive (recommended) or manually extract the script .pbo files (located inside your steam folder, by default C:\Program Files (x86)\Steam\steamapps\common\DayZ\dta\) using the BankRev tool.

P:\ drive with extracted PBOs

Note: For script debugging, only the script.pbo file needs to be extracted, containing the scripts\ folder. This will allow you to debug the running script. It is recommended to extract everything as Workbench has additional tools that can help you with modding.

Workbench Setup

Launch the Workbench from Dayz Tools\Bin\Workbench\workbenchApp.exe or using the tool launcher. From the top menu, navigate to "Workbench → Options" and point the Source Data directory to where you have your data extracted, ideally just P:\

After confirming it will prompt for a restart (let it), after which you should be able to see the project structure in the Workbench Resource Browser just as they appear on your P:\ drive.

Connecting Workbench to DayZ

The DayZDiag_x64.exe is able to act as a client or as a server (with the addition of the -server command line parameter). It takes all the other parameters like the base executable.

With workbench running, open the Script Editor module.

It has it's own Resource Browser but you can open .c files from the base Resource Browser by double clicking them, which automatically opens the Script Editor and loads the selected file.

When both the diagnostic executable and the Script Editor are running, it should automatically connect them, which will be announced by a brief popup window in the lower right part of your screen.

Now you will be able to see text Output that the diagnostic executable is printing for debug purposes and also debug your code by inserting breakpoints and step through the execution.

Note: If you only want to see the console output, then extracting and loading PBOs is not needed, Script Editor should connect to the diagnostic executable without them, but then only the console output is available.

Script Breakpoints

You can pause the script execution when it reaches a certain line in the script by inserting a Breakpoint - locate the line you are interested in and then by pressing F9 a red dot should appear to the left, indicating the execution will stop once it reaches that line. If a yellow exclamation mark in a red circle appears instead, it means that that line of code is never really executed and the script will not stop there.

When the script reaches the indicated line, it will pause it's execution and show you where by a yellow arrow.

Basic controls and what you can do now are displayed in the top menu under Debug option. Here you also have to switch to the Debug Server option if you want to debug the script running on the server.

Note: You can also add and remove Breakpoints by left clicking where the red dots appear. Right clicking adds a blue Bookmark - these don't have any inherent function except marking script in interesting places so you can then easily navigate to them.

Debugging Modded Scripts

You need to load your modded scripts into Workbench if you want to debug them.

Run workbenchApp.exe with

-mod=pathToFolder\YourModFolder;pathToFolder\YourOtherModFolder

If done correctly, after opening the Script Editor you should see all your .c mod files in the Script Editor Resource Browser, in the root of the module that you are modding. So for example if you are modding the Mission module using class missionScriptModule in your config.cpp, all your scripts should appear directly under Mission(scripts/5_Mission) in the Script Editor. You should also be able to find them using the search functions of the script editor.

Note: You can still use your own folder structure/custom folders inside the script module path in whatever way you want, since the script does not care where the files are placed beside them being in a correct script module. With the above example, placing the scripts in a scripts/5_Mission/ModdedScripts might help with a visibility while sorting in workbench.

You will also need to have your packed mod properly loaded in the game, which means launching the DayZDiag_x64.exe with

-mod=pathToFolder/YourPackedModFolder

Make sure that your packed mod folder has identical data as your unpacked mod folder loaded into workbench. If they are not the same, breakpoints might not work at all. For debugging with unpacked data, see Filepatching below. If you are debugging in a multiplayer environment (DayZDiag_x64.exe with -server launch parameter), you may need to change some of the following settings in serverDZ.cfg

BattlEye = 0; // turn off BE since diag exe does not run with it

verifySignatures = 0; // if testing mods which aren't properly signed

Filepatching

Filepatching allows you to work with unpacked data, saving you the need to repack your pbo every time you make a change. It works by loading your packed mod in a standard fashion while at the same time using -filePatching launch parameter and having unpacked data present in your steam DayZ folder. If such data is found, the existing data from the packed mod will be patched by the unpacked data.

Requirements:

• You need to pack your unpacked data at least once - this packed version will be used when launching the game with -mod=Mod parameter. If you add/remove additional files, you will have to repack the pbo as well
• Your folder with unpacked data needs to be present in your steam DayZ root folder ( path\Steam\steamapps\common\DayZ )
• Structure of the unpacked folder has to be the same as the packed pbo, including the prefix - If your pbo named MyMod is in P:\Mods\MyMod\... and is built with Mods\MyMod prefix then your unpacked data have to be present in path\DayZ\Mods\MyMod\... as well
• Your DayZDiag_x64.exe has to be launched with -filePatching (both client and server)
• If in multiplayer environment (DayZDiag_x64.exe with -server launch parameter), you will need to have allowFilePatching = 1; setting in serverDZ.cfg

Advanced Configuration

Additional configuration options are possible using the dayz.gproj file in the Workbench directory

FileSystem allows you to specify path where workbench looks for data which is needed for browsing files and creating ScriptModulePaths. This is the source data directory which you are setting in workbench options, so path to your P: is not necessary if you have set it there instead.

Be aware of prefixes! When launching Workbench with -mod=YourUnpackedMod parameter to set the ScriptModulePaths automatically, FileSystemPath is used as part of the final path. This means that if your mod folder is located in

P:\OtherMods\MyMod

and it's ScriptModulePath in config.cpp is

MyMod/scripts/etc

then your file system has to point to

P:\OtherMods

OR the path in config.cpp has to be updated to

OtherMods/MyMod/scripts/etc

in order to create correct full path(FileSystemPath+ScriptModulePath) which will work in Script Editor.

   FileSystem {
		 FileSystemPathClass {     // This is usually set in Workbench -> Options -> Source data directory instead
            Name "Project Drive"
            Directory "P:"
         } 
		 FileSystemPathClass {     // Custom Dir for Mods
            Name "Mods folder"
            Directory "P:\OtherMods"
         } 
		 FileSystemPathClass {     // Game dir 
            Name "Steam folder"
            Directory "D:\SteamGames\steamapps\common\DayZ"
         }

ScriptModules are paths which are required for script editor functionalities. They are automatically set when you launch Workbench with a -mod=YourUnpackedMod parameter, only set these if you require a custom setup

	 ScriptModules {
		ScriptModulePathClass {
			Name "core"
			Paths {
				"scripts/1_Core"
			}
			EntryPoint ""
		}
		ScriptModulePathClass {
			Name "gameLib"
			Paths {
				"scripts/2_GameLib"
			}
			EntryPoint ""
		}
		ScriptModulePathClass {
			Name "game"
			Paths {
				"scripts/3_Game"
			}
			EntryPoint "CreateGame"
		}
		ScriptModulePathClass {
			Name "world"
			Paths {
			 "scripts/4_World"
			 }
			EntryPoint ""
		}
		ScriptModulePathClass {
			Name "mission"
			Paths {
			 "scripts/5_Mission"
			 }
			EntryPoint "CreateMission"
		}
		ScriptModulePathClass {
			Name "workbench"
			Paths {
			 "scripts/editor/Workbench"
			 "scripts/editor/plugins"
			}
			EntryPoint ""
		} 
	 }