Modding Basics

From Bohemia Interactive Community
Jump to navigation Jump to search

We will be creating a simple mod that will print a message into the script log whenever the player jumps.

In order to do so we have to create the folder structure of the mod and then pack it into a .pbo file. A mod can have several .pbo files but most smaller mods will only ever need a single one.

Requirements

  • Steam Version of DayZ SA
  • DayZ Tools (Available through steam by navigating through Library -> Tools)
  • Basic syntax understanding of Enforce Script
  • Understanding of the PBO Structure

Setting up the Project Drive

Create a Project Drive to store a representation of the DayZ filesystem and all of its files.

  • Launch DayZ Tools from Steam, selecting "Play DayZ Tools"
  • In the menubar, click Settings.
  • Adjust the path to the Project Drive by unchecking Default and then choosing a path that has a minimum of 20gb free space on the drive.
  • In the dropdown for Drive Letter, select one. Make sure to note which one you selected. It is recommended to use 'P:\'.
  • Click apply
  • In the menubar, navigate to Tools and then select Extract Game Data.
  • Wait for the process to finish

Folder Structure and config.cpp

  • Start by creating a folder that will house the mod namesake. This is otherwise called the root prefix of a mod. In this example, we will create one in our 'P:\' drive called FirstMod.
  • Within that folder let's create another folder called Scripts and then within that folder create another folder called 4_World.
  • Let's first create the mod configuration. Within the Scripts folder create a new file called config.cpp and then copy the following sample:
class CfgPatches
{
	class FirstMod
	{
		requiredAddons[]=
		{
			// ""
		};
	};
};

class CfgMods
{
	class FirstMod
	{
		type = "mod";

		class defs
		{
			class worldScriptModule
			{
				value = "";
				files[] = {"FirstMod/Scripts/4_World"};
			};
		};
	};
};
Read up on the config.cpp CfgMods structure

DayZ standalone has 5 script modules that can be modded. In order that they load they are 'engineScriptModule', 'gamelibScriptModule', 'gameScriptModule', 'worldScriptModule' and 'missionScriptModule'. Using the correct script module is very important!

Packing the Mod

Although we are not ready to test, let's pack the mod. This is so we can create and edit scripts through file patching.

When packing a mod, make sure the addons (and keys) folder are in lower case and that the files within addons are also lowercase. This is so your mod will work with the DayZ Linux Server binaries.

  • To start off, let's create a folder where we will place all of our packed mods. Within your work drive, create a new folder called Mods.
  • Within that folder let's create the folder that will be our first mod. Let's name it @FirstMod. All mods require an addons folder so let's also create that within the mod folder.
  • Launch DayZ Tools from Steam, selecting "Play DayZ Tools"
  • Click "Addon Builder"
  • Set the Addon source directory directory, in our case it will be P:\FirstMod\Scripts'
  • Set the Destination filename, in our case it will be P:\Mods\@FirstMod\addons\
  • At the bottom left of the window, select Options and set path to project folder to your work drive
  • Click Pack and wait (if this process fails check 'Enable extended logging' to see why or uncheck 'Binarize').

Preparing FilePatching

  • Go to your DayZ installation folder. It will be within the steamapps folder at 'steamapps/common/DayZ'.
  • Copy the full path.
  • Open a command line window and run the following command, replacing 'DayZInstallationFolder' with the path you copied earlier.
mklink /J "DayZInstallationFolder\FirstMod" "P:\FirstMod"
  • Navigate back to the DayZ installation folder, you should now see 'FirstMod' there. Enter the folder and you should see 'Scripts' and the files within it as you would see in the work drive.

Creating our First Script

Let's create a script inside the world script module that will output to the script log whenever we jump.

To start navigate to the '4_World' folder created earlier.

If you are or ever wish to work with workbench then do the following. Create a new folder called 'FirstMod'. This is because 'Workbench' does not distinguish the files and folders between what mod they come from, or if it was even a mod.

Let's create a script that will "mod" an existing class. Let's first create the 'PlayerBase.c' file within the current folder. We do that by adding the 'modded' keyword to the class declaration. Within this new class let's override a method to add our own behavior, in this case, it would be to print to the script log.

modded class PlayerBase	// modded keyword for modding an existing class
{
	override void OnJumpStart()	// overriding an existing method
	{
		super.OnJumpStart();			// call the original jump callback method so we don't break stuff
		Print("My first mod, yay!");	// our modded print
	}
}

Testing the Mod

Make sure to always properly test your mod before releasing it to the public!

Singleplayer

Let's first create a simple singleplayer mission that will spawn a playable character within chernarus on game load.

  • Within your DayZ installation folder, if it doesn't exist create a new folder named 'missions'. Enter the folder.
  • Create a new folder called 'firstMission.ChernarusPlus'. Note that the 'firstMission' is the name of the mission and 'ChernarusPlus' is the name of the world as named within 'CfgWorlds'.
  • Within the newly created mission create the entry point script 'init.c' and paste the following player spawn script
Mission CreateCustomMission(string path)
{
	return new MissionGameplay();
}

void main()
{
	PlayerBase player;
	ItemBase item;

	// Create player
	player = PlayerBase.Cast((GetGame().CreatePlayer(NULL, "SurvivorF_Linda", "2200 10 2200", 0, "NONE")));

	// Spawn a black t-shirt
	item = player.GetInventory().CreateInInventory("TShirt_Black");

	// Spawn an apple in the t-shirt, don't redefine 'item' so we can still spawn other items in the t-shirt
	item.GetInventory().CreateInInventory("Apple");

	// Select player the client will be controlling
	GetGame().SelectPlayer(NULL, player);
}

Open a command-line window and run the following command, replacing 'DayZInstallationFolder' with the path dayz is installed at.

start /D "DayZInstallationFolder" DayZDiag_x64.exe "-mod=P:\Mods\@FirstMod" "-mission=./missions/firstMission.ChernarusPlus" -filePatching

Additional mods can be added by being delimited by a semi-colon. For example: -mod=P:\Mods\@FirstMod;P:\Mods\@SecondMod.

We are using the singleplayer mission created earlier.

If you are using the Script Editor within Workbench, you will now see the custom message in the output section every time you jump. If you are not, navigate to your profiles folder ( default: "%localappdata%/DayZ" ) and open the most recent file starting with script. This will contain the message.

Multiplayer

Open a command-line window and run the following command, replacing 'DayZInstallationFolder' with the path dayz is installed at.

start /D "DayZInstallationFolder" DayZDiag_x64.exe "-mod=P:\Mods\@FirstMod" -filePatching -server -config=serverDZ.cfg

where the serverDZ.cfg can be copied from the DayZ Server distribution on Steam. It is loading the 'dayzOffline.ChernarusPlus' mission by default. Within the server configuration, you will need to modify the following options:

BattlEye = 0;			// turn off BE since diag exe does not run with it
verifySignatures = 0;	// if testing mods which aren't properly signed yet
allowFilePatching = 1;  // allow clients with unpacked data to join

You can then join the server by using the following command:

start /D "DayZInstallationFolder" DayZDiag_x64.exe "-mod=P:\Mods\@FirstMod" -filePatching -connect=127.0.0.1 -port=2302

Publishing

Before publishing disable filepatching by removing the launch parameter and pack all the .pbo files again. Verify that everything works without filepatching enabled.

Additional steps you will need to go through when you want to share the mod with the world through the steam workshop:

  • Use DS utils (DayZ Tools) to create a private and public bikey and use it to sign your pbo, as well as include the public bikey in your mod
  • Use Publisher (DayZ Tools) to upload to Steam Workshop