KATA 3 OF 8 · XML LAYER

Add a New Item, Recipe & Localization

Katas 1 and 2 edited things that already existed. This one makes something new: a craftable item that did not ship with the game, with a real name and description. It is still pure XML, EAC stays on, and it is the moment modding starts to feel like creation rather than tweaking.

What you'll build

A new crafting material, resourceReinforcedPlank, that you craft at a workbench from wood and forged iron. It reuses a vanilla icon (custom icons are Kata 5), and it gets a proper name and tooltip through Localization. Three files working together: items.xml, recipes.xml, Localization.txt.

Step 1 - Append the item

In your modlet's Config/items.xml, use append (Kata 2) to add a brand-new <item> under /items:

<configs>
  <append xpath="/items">
    <item name="resourceReinforcedPlank">
      <property name="CustomIcon" value="resourceWood" />        <!-- reuse wood's icon -->
      <property name="CustomIconTint" value="caa472" />          <!-- recolour it (hex) -->
      <property name="Stacknumber" value="500" />
      <property name="EconomicValue" value="8" />
      <property name="DescriptionKey" value="resourceReinforcedPlankDesc" />
    </item>
  </append>
</configs>

The reliable way to author a real item is to open the game's own Data/Config/items.xml, find the closest existing item, and copy its block as your starting point - then rename it and adjust. The minimal block above is enough for a usable material; weapons, tools, and food carry many more properties (a Class, actions, buffs), and copying the nearest vanilla item is far safer than typing them from memory.

Step 2 - Add a recipe

An item with no recipe can only be spawned with cheats. Add one in Config/recipes.xml by appending to /recipes:

<configs>
  <append xpath="/recipes">
    <recipe name="resourceReinforcedPlank" count="1" craft_area="workbench" tags="learnable">
      <ingredient name="resourceWood" count="10" />
      <ingredient name="resourceForgedIron" count="2" />
    </recipe>
  </append>
</configs>

• name must match the item's name - that is how the recipe knows what it produces.
• count is how many you get per craft.
• craft_area is where it is crafted (workbench, campfire, forge, chemistryStation, or omit for the backpack crafting grid). A craft_tool attribute can require a specific tool.
• <ingredient> rows list inputs by item name and count.

Step 3 - Name it with Localization

Right now the item's name in-game would just be the raw key resourceReinforcedPlank. Localization maps keys to display text. Create Config/Localization.txt - it is a CSV whose first line is the header. You only need the columns you are providing (a Key column plus a language column):

Key,english
resourceReinforcedPlank,Reinforced Plank
resourceReinforcedPlankDesc,A wooden plank reinforced with forged iron - sturdier building stock.

The item's name is looked up for its title; the DescriptionKey you set in Step 1 is looked up for the tooltip. Add more language columns (french, german, ...) to translate; copy the exact header from the game's own Localization.txt if you want to match every column.

Test it

1. Folder check: Mods/ReinforcedPlank/Config/{items.xml,recipes.xml,Localization.txt} + ModInfo.xml at the root.
2. Restart, watch the log for Loaded Mod and for any red XML error.
3. In-game, open crafting at a workbench (or the backpack grid). Search "Reinforced Plank" - the name and description should read correctly, and the icon should be a tinted plank. Craft it.

Common pitfalls

• Name mismatch. The item name, the recipe's name, and the Localization Key must all be the exact same string. One typo and the recipe makes nothing or the item shows its raw key.
• Recipe but no item (or vice versa). Both appends must succeed. A red error in one file can stop the modlet loading - check the log.
• Ingredient names. They are item names from vanilla (resourceWood, resourceForgedIron); verify them in Data/Config/items.xml.
• No display name. Almost always a missing or mis-keyed Localization row, or the wrong header column.