KATA 1 OF 8 · XML LAYER

Your First Modlet: One XML Tweak

The whole point of this first kata is to prove the loop works end to end: make a folder, write two tiny files, launch the game, and see a value change. Once that loop is real for you, everything else in this series is just bigger versions of the same thing.

What you'll build

A modlet called MyFirstTweak that raises the stack size of wood from the vanilla default to 10,000 - so a single inventory slot holds far more. One <set> command does it. No assets, no code, EAC stays on.

Prerequisites

• Your game's Mods/ folder (see the series prerequisites). Create it if it does not exist.
• A plain-text editor (Notepad++, VS Code). Not Word - it inserts curly quotes that break XML.

Step 1 - Create the folder and ModInfo.xml

Inside Mods/, make a folder named MyFirstTweak. Inside it, create ModInfo.xml. This file is what tells the game "a mod lives here" - every mod needs exactly one, at the top level of the mod folder.

<?xml version="1.0" encoding="UTF-8"?>
<xml>
    <Name value="MyFirstTweak" />
    <DisplayName value="My First Tweak" />
    <Version value="1.0.0" />
    <Description value="Raises the stack size of wood." />
    <Author value="YourName" />
</xml>

• Name is the mod's identifier. Keep it identical to the folder name and use no spaces. (1.0+ uses the <xml> root shown above; the old <ModInfo> root is deprecated.)
• DisplayName is the friendly name shown in the in-game mods list - this one can have spaces.
• Version, Description, Author are self-explanatory and shown to players.

Step 2 - Add the Config folder and one edit

7 Days to Die loads gameplay data from XML files in its Data/Config/ folder. A modlet does not touch those files - instead it puts a same-named file in its own Config/ folder and uses XPath to patch the game's copy in memory at load. Nothing on disk is overwritten, which is why modlets stack and uninstall cleanly.

Make a folder named Config (capital C) inside MyFirstTweak, and create items.xml in it:

<configs>
    <set xpath="/items/item[@name='resourceWood']/property[@name='Stacknumber']/@value">10000</set>
</configs>

Read the xpath left to right: "in items.xml, find the <item> whose name is resourceWood, then its <property> named Stacknumber, then that property's value attribute - and set it to 10000." The wrapping element can be anything (<configs> is the convention); only the commands inside matter.

Your folder now looks like this:

Mods/
  MyFirstTweak/
    ModInfo.xml
    Config/
      items.xml

Step 3 - Load it and confirm

1. Start 7 Days to Die (or your dedicated server). Mods load at startup, so the game must be fully restarted - you cannot hot-load a modlet.
2. Check the log. Near the top of the session log you should see a line confirming the mod loaded, e.g. INF Loaded Mod: MyFirstTweak. The log lives at %APPDATA%\7DaysToDie\logs\ on Windows or ~/.local/share/7DaysToDie/logs/ on Linux. If the mod is malformed you will instead see a red XML error pointing at the file and line - read it, it is usually exact.
3. Test in-game. Start any world, give yourself wood (or chop a tree), and watch the stack climb past the old cap to 10,000.

What just happened

You used one of seven XML modification commands the game exposes: <set>, which changes an existing attribute's value. The XPath was the address of the exact thing you changed. That is the entire foundation of XML modding - everything in Katas 2 through 4 is more commands and sharper addresses. One important detail about set: if the attribute you target does not already exist, it will not create it - it logs a warning instead. (To add something new you use append, which is Kata 2.)

Common pitfalls

• Folder depth. The path must be Mods/MyFirstTweak/ModInfo.xml. A common mistake is an extra nested folder (Mods/MyFirstTweak/MyFirstTweak/ModInfo.xml) after unzipping - the game will not find it.
• Linux is case-sensitive. On a Linux dedicated server, Config must match the casing exactly (capital C, as vanilla uses). On Windows it is forgiving; ship as Config so it works on both.
• Curly quotes. If you pasted from a word processor, " may be a smart quote and the XML will fail to parse. Use a code editor.
• Nothing changed and no error. Usually a typo in the name (it is resourceWood, case-sensitive) - set warns rather than errors when its target is not found, so check the log for the warning.