Your First Integration

If you're wondering how to get started, this page should show you how to create your first Replace Stuff Integration. This page assumes that you already know the basics of creating a mod and focuses specifically on the XML of creating your first Replace Stuff integration.

Let's say that you've created a Torch and a Lamp as part of your mod, and you'd like players to be able to use them to replace each other. Your XML so far might look something like this:

<Defs>
  <ThingDef ParentName="BuildingBase">
    <defName>MyCoolTorch</defName>
    <label>A Very Cool Torch</label>
    <description>This Very Cool Torch that I've created.</description>
    <category>Building</category>
  </ThingDef>
  
  <ThingDef ParentName="BuildingBase">
    <defName>MyCoolLamp</defName>
    <label>A Very Cool Lamp</label>
    <description>This Very Cool Lamp that I've created.</description>
    <category>Building</category>
  </ThingDef>
</Defs>

If you want them replaceable, you'd just need to define a new Def called Replace_Stuff_Compatibility.InterchangeableItems with the following structure:

<Defs>
  <Replace_Stuff_Compatibility.InterchangeableItems>
    <defName>ReplacementMod_MyCoolLights</defName>
    <replaceLists>
      <li>
        <items>
          <li>MyCoolTorch</li>
          <li>MyCoolLamp</li>
        </items>
      </li>
    </replaceLists>
  </Replace_Stuff_Compatibility.InterchangeableItems>
</Defs>

Doing this will allow players to replace those two items with each other. Further explanation of the rules for interchangeable items are explained here. However, this definition would only allow your two lights to replace each other. If you wanted them to be interchangeable with the Vanilla lights, or lights from other mods who integrate into Replace Stuff, you just need to add <category>Lights</category> to your XML, as such:

<Defs>
  <Replace_Stuff_Compatibility.InterchangeableItems>
    <defName>ReplacementMod_MyCoolLights</defName>
    <replaceLists>
      <li>
        <category>Lights</category>
        <items>
          <li>MyCoolTorch</li>
          <li>MyCoolLamp</li>
        </items>
      </li>
    </replaceLists>
  </Replace_Stuff_Compatibility.InterchangeableItems>
</Defs>

If you want to understand more about how Categories work, give the page on Interchangeable Categories a read.

Your mod is unlikely just to contain two or three items and probably instead contains several different items that you want to put into several different replacement lists. In this instance, you can either add another list to replacementLists like so:

<Defs>
  <Replace_Stuff_Compatibility.InterchangeableItems>
    <defName>ReplacementMod_MyCoolLights</defName>
    <replaceLists>
      <li>
        <category>Lights</category>
        <items>
          <li>MyCoolTorch</li>
          <li>MyCoolLamp</li>
        </items>
      </li>

      <li>
        <items>
          <li>MyAwesomeBesideTable</li>
          <li>MyAwesomeBesideLamp</li>
        </items>
      </li>
    </replaceLists>
  </Replace_Stuff_Compatibility.InterchangeableItems>
</Defs>

Or you could create two separate definitions for them as such:

<Defs>
  <Replace_Stuff_Compatibility.InterchangeableItems>
    <defName>ReplacementMod_MyCoolLights</defName>
    <replaceLists>
      <li>
        <category>Lights</category>
        <items>
          <li>MyCoolTorch</li>
          <li>MyCoolLamp</li>
        </items>
      </li>
    </replaceLists>
  </Replace_Stuff_Compatibility.InterchangeableItems>

  <Replace_Stuff_Compatibility.InterchangeableItems>
    <defName>ReplacementMod_MyCoolBedsideItems</defName>
    <replaceLists>
      <li>
        <items>
          <li>MyAwesomeBesideTable</li>
          <li>MyAwesomeBesideLamp</li>
        </items>
      </li>
    </replaceLists>
  </Replace_Stuff_Compatibility.InterchangeableItems>
</Defs>

They both end up with the same result, two separate replacement lists being created, so whichever format you choose to go for is entirely up to preference.