0 - Introduction

Before you go on to actual examples, there is some information that's crucial for you to start making your own replacers. Actually it's just one piece of information.

All of the example files are to be placed in Game Directory > UserData > ItemReplacer > Configs. This folder contains ALL of the actual replacers. That's where your own replacer will be located. The replacer file must be in that folder in order for the mod to load it.

1 - Basics

This is an example that explains in detail how the Config file works.

Example Code

{
  "$schema": "https://raw.githubusercontent.com/TarekLP/BONELAB-ItemReplacer/refs/heads/master/Utilities/schema.json",
  "name": "Simple",
  "description": "A simple replacer that replaces the base game AKM with the Remox's Weapon Pack one!",
  "color": "#FFEA00",
  "id": "simple",
  "enabled": true,
  "dependencies": [
    {
      "title": "Remox's Weapon Pack",
      "barcode": "Remox.RemoxsWeaponPack",
      "modId": 5278839
    }
  ],
  "categories": [
    {
      "name": "AKM",
      "description": "I wonder what this does",
      "enabled": true,
      "entries": [
        {
          "original": "c1534c5a-a6b5-4177-beb8-04d947756e41",
          "replacement": "Remox.RemoxsWeaponPack.Spawnable.AKM",
          "type": "compare"
        }
      ]
    }
  ]
}

The first two properties - name and color are purely you could say decorational. They are used when creating the page & button in the Menu (as shown in the picture above).

The color property MUST be in the format #RRGGBB (aka HEX Color), you can easily get the the hex color by using an online color picker such as HTML Color Codes

There's also an optional property - description, which provides a tooltip on the button that navigates to the page of the replacer. You can put anything there - what it does or something else.

The id is a property that MUST be unique, you cannot register two configs with the same ID.

The $schema property allows for a code/text editor (like Visual Studio Code) to know how the config file is supposed to work, providing autocompletion, showing descriptions of properties and other useful things. For the most up-to-date schema, set the $schema property to https://raw.githubusercontent.com/TarekLP/BONELAB-ItemReplacer/refs/heads/master/Utilities/schema.json

The replacer can be disabled or enabled using the enabled property.

There's also another optional property - dependencies. This property holds a list of mod.io mods that are required for the replacer to function correctly. To set up correctly, you need to define the following for each mod:

• title - this will appear on the menu when the mod is missing, PLEASE set it to the actual mod name, not something else.
• barcode - the barcode of the pallet/mod. This can usually be taken from one of the replacements (the format usually is [pallet barcode].Spawnable.[item name])
• modId - this is the ID of the mod, which is used to install the mod DIRECTLY from the game (requires LabFusion). This can retrieved from the mod page. (see image below)

The way replacements are handled is pretty simple:

• The config file has categories, which can be enabled or disabled by the player via the BoneMenu.

• Those categories can also have descriptions! (optional)

• These categories hold entries, which contain the actual replacements.

• For each replacement, you have to define the original (this is a barcode, you can use RegEx here, see the 2.2 - RegEx example for more information) and a replacement (replacement property, also a barcode).

• You can also set the type (available: compare, regex or scriban). By default the compare one is set, which means in most cases you won't have to even add the type property. The compare type checks if the barcode is equal to the barcode of the spawnable being spawned. On how to use the other types, check the 2.1 - RegEx and 2.2 - Scriban sections

In this case, the replacer has only ONE category - AKM. This category contains one entry, which replaces c1534c5a-a6b5-4177-beb8-04d947756e41 (base game AKM. For list of barcodes of the base game spawnables, go to the Barcode List) with the Remox's Weapon Pack AKM.

2 - Advanced

This example will showcase the more advanced options that the ItemReplacer offers. In most cases you won't have to use them.

Example Code

{
  "$schema": "https://raw.githubusercontent.com/TarekLP/BONELAB-ItemReplacer/refs/heads/master/Utilities/schema.json",
  "name": "Miku",
  "description": "A silly replacer that has Hatsune Miku replacements. Why did I do this? Purely for testing purposes",
  "color": "#00FFFF",
  "id": "miku-all",
  "dependencies": [
    {
      "title": "Baba's Toybox",
      "barcode": "BaBaCorp.BaBasToybox",
      "modId": 5029559
    },
    {
      "title": "Hatsune Miku NPCs",
      "barcode": "QuAd.HatsuneMiku",
      "modId": 5629247
    }
  ],
  "enabled": true,
  "categories": [
    {
      "name": "Miku Plush",
      "enabled": false,
      "entries": [
        {
          "original": "(.*?)",
          "replacement": "BaBaCorp.BaBasToybox.Spawnable.MikuPlush",
          "type": "regex"
        }
      ]
    },
    {
      "name": "Miku NPC",
      "description": "Replaces all NPCs with a Hatsune Miku NPC",
      "enabled": true,
      "entries": [
        {
          "original": "{{ tags | array.contains `NPC` }}",
          "replacement": "QuAd.HatsuneMiku.Spawnable.HatsuneMiku",
          "type": "scriban"
        }
      ]
    }
  ]
}

Because there are A LOT of things here, let's split this into multiple sections.

2.1 - RegEx

Let's focus on a little fragment of code, an entry in a category in this case.

{
  "name": "Miku Plush",
  "enabled": true,
  "entries": [
    {
      "original": "(.*?)",
      "replacement": "BaBaCorp.BaBasToybox.Spawnable.MikuPlush",
      "type": "regex"
    }
  ]
}

To use regex, in the entry you have to set the type property to regex.

Now what (.*?) does is match EVERYTHING. That means it's gonna replace EVERYTHING with a Miku Plush. I doubt any genuine serious replacer would need to do that, but you can.

Does it actually have any real use case that's not replacing everything? If barcodes for different variants of code are similar, then you can simply use one entry to replace all of the variants with something.

2.2 - Scriban

You've probably never heard this word before, it's a library that allows for really complex and cool things

Let's focus on another entry

{
  "name": "Miku NPC",
  "description": "Replaces all NPCs with a Hatsune Miku NPC",
  "enabled": true,
  "entries": [
    {
      "original": "{{ tags | array.contains `NPC` }}",
      "replacement": "QuAd.HatsuneMiku.Spawnable.HatsuneMiku",
      "type": "scriban"
    }
  ]
}

Now what this does is... you can already see in the description.

To use Scriban, you have to set the type property to scriban. This will allow you do all sorts of interesting replacements. But what does the original property actually do?

The original has a structure like this:

• All of the contents are in {{ }}, this signals to the parser for Scriban that it should replace things here
• We reference the tags property, which is an array of strings/text. The tags allow to differentiate crates, for example NPCs have the NPC tag, melee weapons have the Melee tag and so on.
• Typically, to use a method in C# you would have to do method(args), but here it's a bit different. To call a method on a property you have to add | and the name of the method. In this case that would be array.contains which checks if the array (tags) has a value, this value is indicated by a parameter in the method (parameters are after the method, example: method param1 param2). In this case the parameter is NPC.

This will either replace the entire thing with true or false. If true, it will be replaced. (Fun fact: just by writing true into the original property will replace everything)

A documentation on how to use Scriban and all of the methods can be found here.

A list of properties can be found here