Editing Basic Modding Tutorial 1

=== Introduction ===

In this section we will go over creating a very basic mod for 7 Days to Die (Alpha 19). It will be the simplest type of mod, which simply modifies some of the parameters of existing game objects.

Specifically, we will make the nice wooden doors found on prefabs available as craftable items for the player.

=== Files and Folder Structure ===
To begin with, we will need some very specific folders and files for our mod.

1. First we need the root folder of the mod. I'm just going to create a folder called "MoreDoors".

2. Within that folder, create a subfolder called "config".  This is where the actual configuration files will go. This is the only subfolder we need, because for this mod we are not adding any new assets to the game, just modifying existing assets.

3. Now create a new text file called "ModInfo.xml" in the root of MoreDoors.

4. Create three (3) text files in the config folder, called:  blocks.xml, Localization.xml, and recipes.xml.

That's all we need for this simple mod.  I'll explain the use of each file as we continue. Your folder structure should look like this:

 MoreDoors
     \config
         \blocks.xml
         \Localization.txt
         \recipes.xml
     \ModInfo.xml

=== Using Xpath ===
Before we go further, I want to talk a little bit about xpath.

==== What is Xpath? ====
Xpath is a way of finding information in xml files, and modifying values in those xml files. In the context of our 7 Days to Die mod, it will allow us to change some of the parameters set by the main game, when the game loads up.

Xpath uses a very specific syntax, which I'm not going to document here. (See:  [[XPath Explained]]) But to help understand it, think of an XML file as almost being like a folder structure in your computer's file system.

You can have items that contain subitems, and value assignments.  For example, a <block> item can have a bunch of attributes under it, which you could think of like:

 \block\attribute

Xpath uses that sort of syntax for finding, adding, removing, and changing attributes of things in the game.

You can easily search online for more assistance on using Xpath.

=== Modinfo.xml ===
This file is required by the game to even load your mod at all, and contains just some basic parameters. It's easiest to simply show you an example, which is the one I created for my MoreDoors mod:

(NOTE:  There is actually an extra line that needs to be at the beginning of the file, but the editor thinks that this is a "Link in Non-wiki Syntax" so it won't let me put it in here...)

 <xml>
   <Name value="More Doors" />
   <Description value="Adds more doors to craft." />
   <Author value="IcebergTitanic" />
   <Version value="1.3" />
 </xml>

You can put whatever you want in there, to be honest. It's mostly to help document the mod.


=== config\blocks.xml ===
This is where the fun begins. To start with, we're going to first look at the configuration of the doors in the base game.  To do so, I searched for "Door" in the file blocks.xml that I found in my 7D installation directory.

I located this:

 <block name="houseFrontDoor1_v1">

I also located a section for the doors that players can already craft in the game:

 <block name="secureDoorWooden">

So now I have two important things:  What a craftable door looks like, and what the uncraftable door that I want to make craftable looks like. Yay!

I also noted that there's several versions of each of these two things:

 <block name="secureDoorWooden">
 <block name="secureReinforcedDoorWooden">
 <block name="metalReinforcedDoorWooden">

And

 <block name="houseFrontDoor1_v1">
 <block name="houseFrontDoor1_v2">
 <block name="houseFrontDoor1_v3">

And also there's a houseFrontDoor2 set with the same three versions.

Digging into those sections, I see this interesting section:

 <property class="UpgradeBlock">
   <property name="ToBlock" value="houseFrontDoor1_v2"/>
   <property name="Item" value="resourceWood"/>
   <property name="ItemCount" value="4"/>
   <property name="UpgradeHitCount" value="4"/>
 </property>

So this tells us that those three versions are the three possible upgrades for the door. v1 is the unreinforced door, v2 is the wood reinforced door, and v3 is the metal reinforced door.

Now, looking at the two block groups, I noted several attributes that appear on the secureDoorWooden set that are missing from the houseFrontDoor set:

* MaxDamage - How much damage can it take?
* FuelValue - How long will it fuel a campfire or a forge?
* CustomIcon - What does it look like in your inventory.
* TakeDelay - How long it takes to pick one up
* Group - (I can't actually remember what this does! Someone help! :D )
* EconomicValue - What is it worth to a vendor?
* EconomicBundleSize - How many of them can we stack?

So what we need to do is insert those attributes into the definitions for the Front Doors.  We'll use the Xpath directive "setattribute" to insert new attributes into those blocks (in the config/blocks.xml file):

 <configs>
 
   <setattribute xpath="/blocks/block[@name='houseFrontDoor1_v1']" name="MaxDamage">250</setattribute>
   <setattribute xpath="/blocks/block[@name='houseFrontDoor1_v1']" name="FuelValue">200</setattribute>
   <setattribute xpath="/blocks/block[@name='houseFrontDoor1_v1']" name="CustomIcon">houseFrontDoor1_v1</setattribute>
   <setattribute xpath="/blocks/block[@name='houseFrontDoor1_v1']" name="TakeDelay">10</setattribute>
   <setattribute xpath="/blocks/block[@name='houseFrontDoor1_v1']" name="Group">Building,advBuilding</setattribute>
   <setattribute xpath="/blocks/block[@name='houseFrontDoor1_v1']" name="EconomicValue">10</setattribute>
   <setattribute xpath="/blocks/block[@name='houseFrontDoor1_v1']" name="EconomicBundleSize">10</setattribute>
 
   <setattribute xpath="/blocks/block[@name='houseFrontDoor2_v1']" name="MaxDamage">250</setattribute>
   <setattribute xpath="/blocks/block[@name='houseFrontDoor2_v1']" name="FuelValue">200</setattribute>
   <setattribute xpath="/blocks/block[@name='houseFrontDoor2_v1']" name="CustomIcon">houseFrontDoor1_v1</setattribute>
   <setattribute xpath="/blocks/block[@name='houseFrontDoor2_v1']" name="TakeDelay">10</setattribute>
   <setattribute xpath="/blocks/block[@name='houseFrontDoor2_v1']" name="Group">Building,advBuilding</setattribute>
   <setattribute xpath="/blocks/block[@name='houseFrontDoor2_v1']" name="EconomicValue">10</setattribute>
   <setattribute xpath="/blocks/block[@name='houseFrontDoor2_v1']" name="EconomicBundleSize">10</setattribute>
 
 </configs>

We won't worry about the v2 and v3 sections, since we don't plan on players being able to remove the reinforced doors without first demolishing them down to the base door.

Also, for the CustomIcon, I found the picture I wanted in the /data/ItemIcons folder within the 7D install folder, and used the name of the picture that was appropriate.

=== config\Localization.txt ===
This file is pretty simple. We need to provide the text for the item as it appears in the crafting menus. So in your Localization.txt file, we should have these lines:

 Key,Source,Context,Changes,English,French,German,Klingon,Spanish
 houseFrontDoor1_v1,blocks,Door,,Front Door,Porte avant,Eingangstür,,Puerta
 houseFrontDoor2_v1,blocks,Door,,Front Door,Porte avant,Eingangstür,,Puerta

We only need these for the v1 doors because the player won't be crafting the reinforced doors directly. (And hey, if someone knows the French, German, Klingon and Spanish for "Front Door" feel free to update this tutorial!)

=== config\recipes.xml ===
Finally, we want to make a way for the players to craft the doors. In this case we'll use the xpath "append" method to add some new recipes to the game.  Looking at the main recipes.xml file in the 7 Days to Die install folder, we can see that it's a really simple section:

 <recipe name="secureDoorWooden" count="1">
   <ingredient name="resourceWood" count="4"/>
 </recipe>

So what do we want to use?  Just for our example, let's say a brass doorknob, some brass bits (that would be hinges) and some wood.  Another quick search through the recipes and I find the three resource names I want:

* resourceWood
* resourceScrapBrass
* resourceDoorKnob

So we add those as items required for our recipe, and we get the following recipe:

   <recipe name="houseFrontDoor1_v1" count="1" craft_area="workbench">
     <ingredient name="resourceWood" count="6"/>
     <ingredient name="resourceScrapBrass" count="2"/>
     <ingredient name="resourceDoorKnob" count="1"/>
   </recipe>

Do the same for the houseFrontDoor2_v1, and then use the xpath Append function to give us a final recipes.xml file that looks like this:

 <configs>
 
   <append xpath="/recipes">
 
     <recipe name="houseFrontDoor1_v1" count="1" craft_area="workbench">
       <ingredient name="resourceWood" count="6"/>
       <ingredient name="resourceScrapBrass" count="2"/>
       <ingredient name="resourceDoorKnob" count="1"/>
     </recipe>
 
     <recipe name="houseFrontDoor2_v1" count="1" craft_area="workbench">
       <ingredient name="resourceWood" count="6"/>
       <ingredient name="resourceScrapBrass" count="2"/>
       <ingredient name="resourceDoorKnob" count="1"/>
     </recipe>
 
   </append>
 
 </configs>

=== Wrapping up ===

Ok, so we should now have four files within our MoreDoors folder:

* \ModInfo.xml
* configs\blocks.xml
* configs\Localization.txt
* configs\recipes.xml

That's all there is! Copy that whole MoreDoors folder into a "Mods" folder within your 7 Days to Die main installation, and give it a try!

You might want to actually add a recipe to craft doorknobs rather than waiting to scavenge them, but that's up to you. I've posted the full texts of each file at the very end of this article for you.

=== Full Files ===

config\recipes.xml

 <configs>
 
   <append xpath="/recipes">
 
     <recipe name="houseFrontDoor1_v1" count="1" craft_area="workbench">
       <ingredient name="resourceWood" count="6"/>
       <ingredient name="resourceScrapBrass" count="2"/>
       <ingredient name="resourceDoorKnob" count="1"/>
     </recipe>
 
     <recipe name="houseFrontDoor2_v1" count="1" craft_area="workbench">
       <ingredient name="resourceWood" count="6"/>
       <ingredient name="resourceScrapBrass" count="2"/>
       <ingredient name="resourceDoorKnob" count="1"/>
     </recipe>
 
   </append>
 
 </configs>

config\Localization.txt

 Key,Source,Context,Changes,English,French,German,Klingon,Spanish
 houseFrontDoor1_v1,blocks,Door,,Front Door,,,,
 houseFrontDoor2_v1,blocks,Door,,Front Door,,,,

config\blocks.xml
 
 <configs>
 
   <setattribute xpath="/blocks/block[@name='houseFrontDoor1_v1']" name="MaxDamage">250</setattribute>
   <setattribute xpath="/blocks/block[@name='houseFrontDoor1_v1']" name="FuelValue">200</setattribute>
   <setattribute xpath="/blocks/block[@name='houseFrontDoor1_v1']" name="CustomIcon">houseFrontDoor1_v1</setattribute>
   <setattribute xpath="/blocks/block[@name='houseFrontDoor1_v1']" name="TakeDelay">10</setattribute>
   <setattribute xpath="/blocks/block[@name='houseFrontDoor1_v1']" name="Group">Building,advBuilding</setattribute>
   <setattribute xpath="/blocks/block[@name='houseFrontDoor1_v1']" name="EconomicValue">10</setattribute>
   <setattribute xpath="/blocks/block[@name='houseFrontDoor1_v1']" name="EconomicBundleSize">10</setattribute>
 
   <setattribute xpath="/blocks/block[@name='houseFrontDoor2_v1']" name="MaxDamage">250</setattribute>
   <setattribute xpath="/blocks/block[@name='houseFrontDoor2_v1']" name="FuelValue">200</setattribute>
   <setattribute xpath="/blocks/block[@name='houseFrontDoor2_v1']" name="CustomIcon">houseFrontDoor1_v1</setattribute>
   <setattribute xpath="/blocks/block[@name='houseFrontDoor2_v1']" name="TakeDelay">10</setattribute>
   <setattribute xpath="/blocks/block[@name='houseFrontDoor2_v1']" name="Group">Building,advBuilding</setattribute>
   <setattribute xpath="/blocks/block[@name='houseFrontDoor2_v1']" name="EconomicValue">10</setattribute>
   <setattribute xpath="/blocks/block[@name='houseFrontDoor2_v1']" name="EconomicBundleSize">10</setattribute>
 
 </configs>

ModInfo.xml


 <xml>
   <Name value="More Doors" />
   <Description value="Adds more doors to craft." />
   <Author value="IcebergTitanic" />
   <Version value="1.3" />" />
 </xml>
[[Category:Modding]]