Introduction

Welcome to Brushwood Buddies modding! Modding allows you to create:

• new scenarios with board configurations (appearing tiles, items, clues and so on)
• new items with your own item graphics
• new crafting recipes
• new tiles with your own tile floor graphics and your own tile decoration graphics

Language Modding

Before we start with the actual modding for creating new scenarios, items and more, a short note about language modding. Brushwood Buddies allows you to create your own language files and if you do that, that's totally awesome! A language file contains all the text displayed in the game and is delivered as a compact XML file. Even the languages supported with the original game (English and German) come with such a language file. If you are not interested in translating the game to another language, just skip this section.

Language files are stored in the "./Content/languages/" folder of the game's installation. If you play Brushwood Buddies on Steam, right-click on the game in the Steam library and choose "Properties". Select the "Local Files" tab und click on "Browse Local Files". Then navigate to the mentioned folder "./Content/languages/". Because we don't want to change the game's installation, we copy the "language_english.xml" in the "languages" folder to the following destination of the user folder:

• Windows: "C:\Users\YourUsername\Documents\BrushwoodBuddies\languages\"
• Linux: "%XDG_DATA_HOME%/BrushwoodBuddies/languages/" or "%HOME%/.local/share/BrushwoodBuddies/languages/"

If the "languages" folder doesn't exist there, create it. Now rename the language file by changing the "english" part of "language_english.xml" appropriate to your language, e.g. "language_spanish.xml". The language will be available in the game's options as "Spanish" then.

To make changes to the language file, open the "language_spanish.xml" (example) with a text editor (Notepad or Notepad++). You will see, that the whole file has a simple structure like:

<?xml version="1.0" encoding="utf-8"?>
<LocalizationWrapper xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
    <Entries>
      <Entry>
        <Name>... entry name ...</Name>
        <Data>
          <string>... some data ...</string>
          <string>... some data ...</string>
          ... more data strings ...
        </Data>
      </Entry>
      ... more entries ...
    </Entries>
</LocalizationWrapper>

A part of the English language file looks like this:

<?xml version="1.0" encoding="utf-8"?>
<LocalizationWrapper xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
    <Entries>
      ... more entries ...
      <Entry>
        <Name>MainMenu</Name>
        <Data>
          <string>Campaign</string>
          <string>Challenges</string>
          <string>Recipes</string>
          <string>Options</string>
          <string>Credits</string>
          <string>Exit</string>
        </Data>
      </Entry>
      ... more entries ...
    </Entries>
</LocalizationWrapper>

You see, the language file is full of "entries" (<Entries></Entries>) which have an "entry name" (<Name></Name>) and a couple of "data entries" (<Data></Data>) whereas every data entry is a line of text (<string></string>).

When you are going to translate the text, don't touch the entry names like "MainMenu". They are used by the game to access the data entries. So when the main menu is shown in the game, it checks the file for the entry "MainMenu" and gathers all the strings. How the data is read and used depends on the situation. For the main menu, it expects the buttons' names which appear from left to right in the game if you place the mouse on them. Therefore, to translate the main menu texts, you have to adapt the data entries to the language you are translating to. For Western languages, special characters like ä, ö, ü and ß in German, should be fully covered. If not, let me know via mail (info@stevencolling.com). Asian languages are not supported. The encoding of the file is "UTF without BOM".

Short note: the text sometimes uses codes like [color=255,0,0][/]. Don't touch them to reach similar results. You should pay attention to spaces, too. If a data entry starts with some space like " ", there is always a reason for that. The "#" character (or "#1", "#2" etc.) are used as placeholders. Don't forget to submit your language file to the Brushwood Buddies Steam community and big thanks for taking the time!

Example Mod

Before we start to make our first mod, please check out the example mod which comes already with the game. You have to activate mod loading in the game first. So start the game, go to the options and scroll all the way down until you find "Load Mods". Activate that and check the "Challenges" (second button in the main menu). The example mod will appear there and can be started. It's just a small proof of concept which adds a new forest tile with little yellow flowers on it as well as trees with beehives. It also includes a couple of new items relating to bees and honey and corresponding crafting recipes, like combining a campfire with a "beehive protected by a bee" to get an "unprotected beehive". Making your own mods is super easy, so let's do that.

Setting up a new Mod

To create a new mod, first browse to the game's content folder. If you play Brushwood Buddies via Steam, right-click on the Brushwood Buddies entry in your game library on Steam and click on "Properties" in the appearing context menu. Then head over to the "Local Files" tab and click on the "Browse Local Files" button. This will open the game's folder. Now navigate to "./Content/mods/". If you don't own the game on Steam, you can find the same folder in something along "installation path of Brushwood Buddies/Content/mods/".

Every mod is represented as a folder with files in it. The "Example Scenario" mod is accordingly stored in the "example" folder. We don't want to make direct changes to the installation of the game. Instead, we want to use the Content folders in our user directory instead. So our first task is to copy the example mod folder we found to the following destination:

• Windows: "C:\Users\YourUsername\Documents\BrushwoodBuddies\mods\"
• Linux: "%XDG_DATA_HOME%/BrushwoodBuddies/mods/" or "%HOME%/.local/share/BrushwoodBuddies/mods/"

If there is no "mods" folder within "BrushwoodBuddies", just create it. After copying the example folder to this place in the user directory, rename it to anything you want, but don't let the mod folder start with an underscore "_" as folders and files starting with this character are ignored by the game (it's a convenient way to make something temporarily not able to load). Call it, for example, "myfirstmod".

Your tasks:

• copy the example mod folder from the game's installation path to your user directory
• rename the copied example mod folder

Mod Structure

If you open your new mod's folder, you find a couple of files there, namely:

• "texture_x.png": texture files which contain the graphics we want to use within the mod
• "mod.xml": the mod's main file
• "scenario_x.xml": scenario files which add a whole new scenario to the "Challenge" scenarios in the game (the whole campaign would be stored as a single scenario file, as example)
• "items.xml": the mod's new items added to the game
• "recipes.xml": new crafting recipes
• "tiles.xml": new tile types
• "decorations.xml": new decoration objects (placed on tiles, like trees, rocks, houses and so on)

It's not necessary to have all the files, so if your mod doesn't add new decorations, you can remove this file. Don't change the file's name (except for changing the "x" in "texture_x.png" and "scenario_x.xml", as the file names indicate their use.

Mod Main Data (mod.xml)

The "mod.xml" contains the mod's main data. Open it with a text editor (Notepad or Notepad++) to have a look.

• Identifier: a unique identifier used within the game. It should be unique across all mods, so leaving it "example" won't work. As a best practice, change it to the name of your mod's folder.
• TargetVersion: for which game version this mod was created. It doesn't affect anything, just some information.
• Author: your name.
• OrderId: mods are loaded at the game's start and share the same namespaces for items and so on. This topic is for experienced modders and explained under "Sharing Data Across Mods" further below. The OrderId defines in which order mods are loaded. You can leave it at a "0" for now.
• ProcessorIdentifier: defines what kind of mod you are creating. Currently, only "brushmod" is available, so just leave it.

Make sure that you don't mess up the tags "<...></...>" as missing brackets or typos in the identifiers within these brackets will lead to a game crash.

Your tasks:

• set the Identifier to something unique
• set the Author

New Items (items.xml and texture files)

The "items.xml" contains all the information of the items you want to add, except their visual representation, which is stored in a texture file. After opening the file, you see a hierachy of things enclosed by <...></...> tags. You will see something along this:

<?xml version="1.0" encoding="utf-8"?>
<ItemSetModDescriptor xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  <ItemTextureId>1</ItemTextureId>
  <ItemTextureFirstSourceStart>
    <X>0</X>
    <Y>150</Y>
  </ItemTextureFirstSourceStart>
  <ItemTextureItemsPerRow>6</ItemTextureItemsPerRow>
  <ItemIndexUsedForSourceOffset>0</ItemIndexUsedForSourceOffset>
  <Items>
  ...
  </Items>
</ItemSetModDescriptor>

The presented properties mean the following:

• ItemTextureId: the id of the texture where the item graphics are stored. It's a "1", so the mod will check the "texture_1.png" in the mod's folder if it wants to load the item graphics. If you have a look at the "texture_1.png", you will see it contains item graphics (a bee, a beehive and so on) along other interface-related graphics.
• ItemTextureFirstSourceStart and ItemTextureItemsPerRow: item graphics are organized as a matrix of x*y items, whereas every item icon is 50x50 pixels big. In the "texture_1.png", you see it has 6*1 items. The ItemTextureFirstSourceStart's X and Y value define where this matrix within the texture file starts. The point (0,0) is in the top-left corner of the texture file, so a X=0 and Y=150 means, that the first item graphic will start "0 pixels to the right" and "150 pixels down" relative to the texture's upper-left corner. Textures can't be bigger than 4096x4096 pixels, so having a lot of items makes it necessary to start a new row eventually. ItemTextureItemsPerRow defines after how many items a new row is started.
• ItemIndexUsedForSourceOffset: is a special property which allows to ignore icons at the start of the matrix and therefore not important in our case. A value of "1" would skip the first icon within the defined matrix and expect the icon for the first item to be the second icon in the texture file and so on.
• Items: this area defines new items. Every new item is enclosed within a <ItemModDescriptor></ItemModDescriptor> and we look into these in a moment.

So basically the "items.xml" stores all the item information and how they are handled. It also references the texture file which stores the icons of the added items. Now let's check out how a single item is defined:

• Flag: the item's identifier, which has to be unique across the game and other mods. Setting this to "ROCK" will lead to an error, because "ROCK" is already defined in the main game. There are lists at the end of this guide containing all the flags which already appear in the game.
• Name: the item's name as shown on the recipe screen in the game. The name doesn't have to be unique.
• OrderIndex: if your scenario allows to display a recipe screen for the new items, this order index will define the order in which the items appear on the recipe screen. Lower order indices mean an earlier appearance on the recipe screen. For example, the item with an order index of 0 will appear in the top-left corner of the recipe screen.
• SoundTheme: which kind of sound the item will make when interacted with, for example if selected or crafted. The available themes are Wood, Stone, Meat, Paper, Coins and Water.
• IsListed: if this item appears on the recipe screen. The scenario must allow modded items to appear on the recipe screen, before this property has any effect.
• IsProtectedFromGlitchBeam: right now this property has little effect as it's only relevant during a boss fight against the glitch beam shooting skull. If set to true, the item can't be transformed to something else by the skull.
• BaseScore: it isn't possible right now to create score-based modes, but if so later on, the scores will be based on the item's base score.

The mod can't be loaded yet, as the flags of the items (and other parts of the mod) conflict with the example mod. To solve this, let's remove all the items in the items.xml, except one, which will be replaced with your first own item. As an example, we could add an orange fruit to the game. It's item data would look like that:

<ItemModDescriptor>
  <Flag>ORANGE</Flag>
  <Name>Orange</Name>
  <OrderIndex>0</OrderIndex>
  <SoundTheme>Meat</SoundTheme>
  <IsListed>true</IsListed>
  <IsProtectedFromGlitchBeam>false</IsProtectedFromGlitchBeam>
  <BaseScore>0</BaseScore>
</ItemModDescriptor>

Our orange fruit needs a graphic, too. Open the "texture_1.png" with the graphic editing program of your choice. GIMP, for example, is a free tool which does the job. Remove the old bee-related item icons. As defined in the "items.xml", the first item icon is expected at position (0,150) in the texture file. Some graphic programs support showing a raster. If so, set the raster size to 50x50 pixels, because that's the size of a single item icon. In GIMP, you can activate the raster by selecting "View > Show Raster" and configure it under "Image > Configure Raster" to be 50x50 pixels wide.

Draw a fancy orange fruit at the position where the beehive without a bee was.

Now let's add a second and a third item to the "items.xml". Why not something along orange juice and an orange tree?

<ItemModDescriptor>
  <Flag>ORANGE</Flag>
  <Name>Orange</Name>
  <OrderIndex>0</OrderIndex>
  <SoundTheme>Meat</SoundTheme>
  <IsListed>true</IsListed>
  <IsProtectedFromGlitchBeam>false</IsProtectedFromGlitchBeam>
  <BaseScore>0</BaseScore>
</ItemModDescriptor>
<ItemModDescriptor>
  <Flag>ORANGEJUICE</Flag>
  <Name>Orange Juice</Name>
  <OrderIndex>1</OrderIndex>
  <SoundTheme>Water</SoundTheme>
  <IsListed>true</IsListed>
  <IsProtectedFromGlitchBeam>false</IsProtectedFromGlitchBeam>
  <BaseScore>0</BaseScore>
</ItemModDescriptor>
<ItemModDescriptor>
  <Flag>ORANGETREE</Flag>
  <Name>Orange Tree</Name>
  <OrderIndex>2</OrderIndex>
  <SoundTheme>Wood</SoundTheme>
  <IsListed>true</IsListed>
  <IsProtectedFromGlitchBeam>false</IsProtectedFromGlitchBeam>
  <BaseScore>0</BaseScore>
</ItemModDescriptor>

The order index only affects the order on the recipe screen and is not related to the texture file. The second item in the "items.xml" file's list will get the second icon in the corresponding texture file. Therefore, we have to make an orange juice graphic to the right of the orange fruit icon (at (50,150)) and the orange tree at (100,150). Remember, our "items.xml" defines that there are only 6 item icons in one row, so the 7th icon starts a new row at (0,200). Save the texture file and "items.xml".

Your tasks:

• remove the old items in "items.xml" (relict from the example mod), so they doesn't conflict with the items defined in the example mod
• add own items
• remove the old item icons in the "texture_1.png"
• add your own item icons

New Recipes (recipes.xml)

Recipes define how items are combined to a new item. There are certain rules you have to follow:

• a recipe doesn't allow the same item type multiple times (so a recipe involving 2 trees isn't allowed)
• a recipe must consume at least one item (in "grindstone + flint = sharpened flint", the "grindstone" is protected and won't be consumed. "Flint" will be consumed and replaced by the "sharpened flint". If all ingredients would be protected, there would be no space to place the resulting item!)

The "recipes.xml" represents every single recipe enclosed in
<RecipeModDescriptor></RecipeModDescriptor>, like:

<RecipeModDescriptor>
  <IsProtoRecipe>true</IsProtoRecipe>
  <Incomes>
    <string>CAMPFIRE</string>
    <string>BEEHIVEBEE</string>
  </Incomes>
  <Outcomes>
    <RecipeOutcomeModDescriptor>
      <Outcome>BEEHIVE</Outcome>
      <Tokens>1000</Tokens>
    </RecipeOutcomeModDescriptor>
  </Outcomes>
  <Protections>
    <string>CAMPFIRE</string>
  </Protections>
</RecipeModDescriptor>

The recipe shown above allows to combine a "campfire" and a "beehivebee" (beehive with a bee) to get a beehive "beehive" (without a bee). The campfire won't be consumed during the crafting. The appearing properties mean the following:

• IsProtoRecipe: if "true", this is the recipe shown on the recipe screen for the outcoming item. As an example, you combine "apple" and "shrub" in the main game to get a "rabbit", but also "cooked apple" and "shrub" for the same result. The recipe screen shows only "apple + shrub = rabbit" if clicked on the "rabbit" symbol, as this was marked as the rabbit's "proto recipe". This is also a clever way to make a puzzle, like the "rope" in the campaign, where the recipe screen shows that it is made out of grass, but the board doesn't generate any so the player has to come up with the idea (together with the clues) to trade some rabbit fur with the trader.
• Incomes: the ingredients of the recipe, all enclosed within a "<string></string>". They refer to the items' flags. For items of the main game, please check the item lists at the end of this guide. For your own items, check the "items.xml" for their flags, like "ORANGE" or "ORANGEJUICE" in our example.
• Outcomes: some recipes can have multiple outcomes, others have only one. The example above does generate a "BEEHIVE" only when "CAMPFIRE" and "BEEHIVEBEE" are combined. If your recipe has only one outcome, leave the Tokens at 1000, especially don't set it to 0, as this can lead to a crash under certain circumstances. For multiple outcomes (like trees which drop sticks or apples), the Tokens define how likely this item will be created during the crafting process. Think of them as tokens of a lottery. Every token increases the chance. If one outcome would have 1000 tokens and the other 2000 tokens, the second one has a doubled chance to get chosen as the outcome if the recipe is executed.
• Protections: like already explained, the protected items are the ones which don't get destroyed/consumed during the crafting process. Like the campfire if you cook an apple. As said in the beginning, at least one item has to be consumed during the crafting.

Let's remove all the recipes of the example mod and add our own recipes:

<RecipeModDescriptor>
  <IsProtoRecipe>true</IsProtoRecipe>
  <Incomes>
    <string>ORANGETREE</string>
  </Incomes>
  <Outcomes>
    <RecipeOutcomeModDescriptor>
      <Outcome>ORANGE</Outcome>
      <Tokens>1000</Tokens>
    </RecipeOutcomeModDescriptor>
    <RecipeOutcomeModDescriptor>
      <Outcome>STICK</Outcome>
      <Tokens>500</Tokens>
    </RecipeOutcomeModDescriptor>
  </Outcomes>
  <Protections />
</RecipeModDescriptor>
<RecipeModDescriptor>
  <IsProtoRecipe>true</IsProtoRecipe>
  <Incomes>
    <string>BOTTLE</string>
    <string>ORANGE</string>
  </Incomes>
  <Outcomes>
    <RecipeOutcomeModDescriptor>
      <Outcome>ORANGEJUICE</Outcome>
      <Tokens>1000</Tokens>
    </RecipeOutcomeModDescriptor>
  </Outcomes>
  <Protections />
</RecipeModDescriptor>

<Protections /> is the way to indicate an empty list.

Your tasks:

• remove the old recipes (relict from the example mod)
• add your own recipes

New Tiles (tiles.xml)

We added our own items and recipes, now let's make our own tile, too. A tile is the place where items spawn. It defines which items can spawn and how the floor looks like. The tile type "FORESTTREES", for example, is a green floor with tree decoration left and right which appears in the forest environment during the main game's tutorial and generates trees only. Please open the "tiles.xml" now.

The file defines two properties TileTextureId and TileTextureTilesPerRow which are similar to the ones in the "items.xml":

• TileTextureId: in which texture the tile graphics are stored in. The example mod set this to "2", so "texture_2.png" will be references to load the tile graphics. While the example mod's "texture_2.png" contains only one tile graphics, it can contain more and similar to item icons, they are arranged in a matrix. While item icons have a size of 50x50 pixels, a tile graphics has a size of 334x200 pixels.
• TileTextureTilesPerRow: again, this defines how many tile graphics within the texture file are placed in one row before a new row is started. If this is set to "1", the next tile graphic is expected below the previous tile graphic.

After these two properties, a list of tile definitions within "<Tiles></Tiles>" adds new tile types to the game. A tile type definition can look like this:

<TileModDescriptor>
  <Flag>FORESTBEES</Flag>
  <DecorationReference>FORESTBEES</DecorationReference>
  <FloorReference>1</FloorReference>
  <HasFog>false</HasFog>
  <IsProtectedFromGlitchBeam>false</IsProtectedFromGlitchBeam>
  <Outcomes>
    <TileOutcomeModDescriptor>
      <Outcome>TREE</Outcome>
      <Tokens>2000</Tokens>
    </TileOutcomeModDescriptor>
    <TileOutcomeModDescriptor>
      <Outcome>BEEHIVEBEE</Outcome>
      <Tokens>1800</Tokens>
    </TileOutcomeModDescriptor>
  </Outcomes>
</TileModDescriptor>

And the appearing properties mean the following:

• Flag: similar to item flags, this flag is used to identify the tile type. It has to be unique across the game and other mods. You can use this flag later to reference this tile type, for example in the scenario where a board may have multiple tiles with this type.
• DecorationReference: You can set the DecorationReference in two ways. The first way is to set it to the tile's own flag, like in the example above. You will see later, that it's possible to assign new decoration objects to tile types, and assigning the DecorationReference to its own tile type does mean something along "use the decoration objects defined for this tile type". The second way to set DecorationReference is to use the type of an already existing tile, for example from the main game. Setting this property to "FORESTTREES" will load the normal tree decoration from the main game. Check the tile type list at the guide's end for every available tile type. If you want to reference tile types from other mods, be sure that your mod is loaded after the mod you reference from, which can be controlled with the OrderId in the "mods.xml".
• FloorReference: Again, this property can be set in two ways. One way is to reference an already existing tile type, like "FORESTTREES" from the main game. Then, the added tile type will use the green grass floor graphic of the referenced tile. If you want to use a tile graphic from your texture (e.g. from "texture_2.png" if the "TileTextureId" was set to "2"), then use a number as FloorReference. The example above uses a FloorReference of "1", which means, the first tile graphic in your tile graphics texture will be used. With "2", the second tile graphic in the file is used, which is normally the next to the right, but as we set TileTextureTilesPerRow to "1", a row has a length of 1 and therefore, the tile graphic in the next row is loaded.
• HasFog: if this tile has little fog clouds on it.
• IsProtectedFromGlitchBeam: similar to the glitch protection of items, this property only saves the tile from being targeted during the boss fight against the skull. Then, items on that tile won't be transmuted.
• Outcomes: this defines a group of items which can appear on this tile, for example when the current item on the tile is destroyed or used. Every item in this group is enclosed by "<TileOutcomeModDescriptor></TileOutcomeModDescriptor>" with two properties: the item's flag "Outcome" and the item's chance, namely the "Tokens". We will learn more about this in a second.

Now let's remove the old tile type and create a new tile type which can generate our added orange trees:

<TileModDescriptor>
  <Flag>FORESTORANGES</Flag>
  <DecorationReference>FORESTORANGES</DecorationReference>
  <FloorReference>1</FloorReference>
  <HasFog>false</HasFog>
  <IsProtectedFromGlitchBeam>false</IsProtectedFromGlitchBeam>
  <Outcomes>
    <TileOutcomeModDescriptor>
      <Outcome>TREE</Outcome>
      <Tokens>1000</Tokens>
    </TileOutcomeModDescriptor>
    <TileOutcomeModDescriptor>
      <Outcome>ORANGETREE</Outcome>
      <Tokens>2000</Tokens>
    </TileOutcomeModDescriptor>
  </Outcomes>
</TileModDescriptor>

The tile type definition above will give us a new tile type "FORESTORANGES" which will get its own decoration objects (DecorationReference is "FORESTORANGES"), uses the first tile graphic in the corresponding texture, has no fog, is not protected from a glitch beam and generates items of the type TREE and ORANGETREE, while the orange tree has a doubled chance to appear. You should also open the "texture_2.png" and change the tile's graphic if you want. Why not placing some oranges on the grass as decoration?

Your tasks:

• remove the old tile types (relict from the example mod)
• add a new tile type
• change the tile floor graphic in "texture_2.png"

New Decorations (decorations.xml)

Decorations are graphics placed on a tile, like trees, rocks or shrubs. Every tile has 4 of these decorations: two on the left side, two on the right side. The "decorations.xml" allows to define new decoration objects. Open it, so we can check out its properties:

• DecorationTextureId: which texture provides the decoration graphics. A "3" means, that it will look up the decoration graphics in the "texture_3.png" file.
• Decorations: contains the decoration sets.

A decoration set contains a list of sources (areas in the referenced texture file) and maps them to tile types. Here is an example from the example mod:

<DecorationModDescriptor>
  <Flags>
<string>FORESTBEES</string>
  </Flags>
  <Sources>
    <Rectangle>
      <X>0</X>
      <Y>0</Y>
      <Width>88</Width>
      <Height>124</Height>
    </Rectangle>
    <Rectangle>
      <X>88</X>
      <Y>0</Y>
      <Width>98</Width>
      <Height>109</Height>
    </Rectangle>
    <Rectangle>
      <X>186</X>
      <Y>0</Y>
      <Width>105</Width>
      <Height>113</Height>
    </Rectangle>
    <Rectangle>
      <X>291</X>
      <Y>0</Y>
      <Width>88</Width>
      <Height>95</Height>
    </Rectangle>
  </Sources>
</DecorationModDescriptor>

This DecorationModDescriptor will define which decoration objects will be available as decoration for a tile of the type FORESTBEES. The Sources are areas within the texture file. Every source is a Rectangle with a position X and Y as well as a Width and a Height. The first rectangle is therefore at (0,0,88,124). Coordinates in texture files always start at (0,0) in the top-left corner. Please open "texture_3.png" to check the decoration graphics. (0,0,88,124) refers to the leftmost tree in the texture file. The rectangle containing this tree starts at (0,0) and has a width of 88 and a height of 124. The second tree is at (88,0,98,109) and so on. You can make the texture file bigger in size and add additional decorations, which then have to be referenced in the "decorations.xml" with a corresponding source.

A generated tile will sample its decoration out of the provided sources. The source set can be smaller or bigger if you want, it doesn't have to have a size of 4 sources. So feel free to add more trees for our orange fruit mod with little oranges on them or remove the yellow beehives on the texture file provided with the example mod.

Don't forget to set the flag to FORESTORANGES, as this was the tile type we defined earlier in the tutorial. The decoration descriptor could look like this:

<DecorationModDescriptor>
  <Flags>
    <string>FORESTORANGES</string>
  </Flags>
  <Sources>
    <Rectangle>
      <X>0</X>
      <Y>0</Y>
      <Width>88</Width>
      <Height>124</Height>
    </Rectangle>
    <Rectangle>
      <X>88</X>
      <Y>0</Y>
      <Width>98</Width>
      <Height>109</Height>
    </Rectangle>
    <Rectangle>
      <X>186</X>
      <Y>0</Y>
      <Width>105</Width>
      <Height>113</Height>
    </Rectangle>
    <Rectangle>
      <X>291</X>
      <Y>0</Y>
      <Width>88</Width>
      <Height>95</Height>
    </Rectangle>
  </Sources>
</DecorationModDescriptor>

...but perhaps with more sources?

Your tasks:

• rename the flag of the decoration set (relict from the example mod) to the tile type you added in the "tiles.xml"
• modify or add new decorations to "texture_3.png"
• add the corresponding sources to the source set in the "decorations.xml", if new decorations were added

New Scenarios (scenario_1.xml)

The final step is to setup a scenario which actually uses the stuff we created. Please open the "scenario_1.xml" of our mod. It's a bit longer than the other files, but not complicated. Let's check the properties:

• Identifier: the identifier of this scenario. It has to be unique across the game and other mods, so change that to something else, for example including the mod's name: "myfirstmod_scenario".
• OrderId: modded scenarios appear before the challenge scenarios of the main game. With the order id you can arrange in which order the scenarios added by mods appear. A low order id means the scenario will appear before other scenarios with a higher order id.
• Name: the name how it appears in the game. Let's change that to something else.
• Description: the description of the scenario how it appears in the game. Tip: you can use colors with "[color=255,0,0]...[/]".
• CanBeSaved: if "true", the scenario will generate a save game (like the campaign), so players can continue after restarting the game. There will be also a little delete button near the scenario which allows to delete a previous save game. If "false", the scenario state will be reset after ending the session.
• HasOwnIcon: if "true", the scenario comes with an own icon which appears in the main menu of the game. If "false", a default icon for modded scenarios will be used.
• IconTextureId: defines in which texture the scenario icon can be found. A "1" refers to the "texture_1.png" file. Only relevant, when HasOwnIcon is "true".
• IconTextureSource: defines where the icon can be found within the texture. It's a source rectangle with a position X and Y as well as a Width and Height. If you check the "texture_1.png", you find the scenario's icon for "the scenario was solved" at (0,0,149,149). The icon for "the scenario wasn't solved yet" is inferred and expected to the right with a 1px gap, namely at (X+150,Y,149,149). Only relevant, when HasOwnIcon is "true".
• AreRecipesAvailable: if "true" recipes can be shown while playing the scenario.
• ShowOriginalItemRecipes: if recipes can be shown while playing the scenario, ShowOriginalItemRecipes defines if the recipes of the main game are shown on the recipe screen or not.
• ShowModdedItemRecipes: like ShowOriginalItemRecipes, this property defines if the recipes added by mods are shown on the recipe screen, if the recipe screen is available. Setting ShowOriginalItemRecipes to "false" and ShowModdedItemRecipes to "true" will only show the recipes added by the mod.
• AreOriginalItemRecipesDiscovered: if "true", all the recipes from the main game are already discovered and fully shown on the recipe screen.
• AreModdedItemRecipesDiscovered: if "true", all the recipes from the mod are already discovered.
• DiscoverItemsAdditionally and UndiscoverItemsAdditionally: DiscoverItemsAdditionally is a list of item type flags of items whose recipes will be discovered on starting the scenario and UndiscoverItemsAdditionally a list of item type flags whose discovery status will be reset. As an example, if you want to have only a couple of recipes to be discovered at the start, you should set AreOriginalItemRecipesDiscovered to "false" and add the recipes which should be discovered to DiscoverItemsAdditionally. If everything is discovered except a couple ones, set AreOriginalItemRecipesDiscovered to "true" and add the hidden ones to UndiscoverItemsAdditionally.
• Creatures: the creatures available in the scenario. More to creatures in a second.
• Boards: the single boards of this scenario. A board is a concrete puzzle the player has to solve. If solved, the creatures will walk out of the screen and the next board is loaded. More to boards in a second.

The Creatures part let you decide which creatures are available and therefore control which recipes are available, as the count of creatures represents how many ingredients a performed recipe can have. Each creature definition is wrapped up in a <CreatureDescriptor></CreatureDescriptor> like this:

<CreatureDescriptor>
  <Creature>WOODY</Creature>
  <StartBoardIndex>0</StartBoardIndex>
  <EndBoardIndex>2</EndBoardIndex>
  <UseCustomConfiguration>true</UseCustomConfiguration>
  <IsLovingDiscarding>true</IsLovingDiscarding>
  <ResetOriginalItems>false</ResetOriginalItems>
  <HappyItems>
    <string>HONEY</string>
  </HappyItems>
  <SadItems>
    <string>BEE</string>
  </SadItems>
</CreatureDescriptor>
<CreatureDescriptor>
  <Creature>TURNIP</Creature>
  <StartBoardIndex>0</StartBoardIndex>
  <EndBoardIndex>2</EndBoardIndex>
  <UseCustomConfiguration>false</UseCustomConfiguration>
</CreatureDescriptor>

The example above will add Woody as creature. The properties mean the following:

• Creature: which of the creatures is available. Right now, it's not possible to add your own creatures to the game. You have to choose one of available, namely WOODY, TURNIP, GHOST, WITCH, MACHICKEN or BOSSSKULL.
• StartBoardIndex: when the creature appears for the first time, but is not controllable yet. Instead, it will appear on the bottom-right tile and will be added to the group if the board is solved. The first board has an index of 1, so setting StartBoardIndex to 0 will make Woody already available on the first board. Setting this to 1 would make the first board unplayable, as Woody wouldn't be controllable and standing on the bottom-right tile instead.
• EndBoardIndex: the last board the creature is available. On the next board, the creature isn't available anymore. As this scenario only includes 2 boards, this was set to 2 and is not relevant.
• UseCustomConfiguration: if "true", you can change how the creature reacts on items, for example if it loses hearts if certain items are crafted or not. If this is set to "false", the remaining properties IsLovingDiscarding, ResetOriginalItems, HappyItems and SadItems have no effect.
• ResetOriginalItems: if "true", the main game's configuration of creatures is reset. So Woody wouldn't get hearts on discarding nor does the turnip lady likes apples anymore. If you want to extend their configuration and not reset the main game's one, set this to "false".
• HappyItems: a list of items which add a 1/4 heart to the creature's happiness, if crafted. Every item has to be enclosed in <string>...</string>.
• SadItems: correspondingly, which items lower the creature's happiness by 1/4 heart on crafting.

So the scenario from the example mod will have Woody and the turnip lady playable right on the first board. While the turnip lady doesn't had any changes, Woody will love HONEY and hate BEEs from the example mod. As we removed these items during the tutorial, you should remove or replace them, too. Perhaps Woody likes orange juice?

After we set the creatures, let's have a look at the final part of our mod: the boards. They are defined within the Boards area and every single board is enclosed in a <BoardModDescriptor></BoardModDescriptor>. Here is an example for a single board:

<BoardModDescriptor>
  <SizeX>4</SizeX>
  <SizeY>3</SizeY>
  <Environment>FOREST</Environment>
  <IsHappinessRelevant>true</IsHappinessRelevant>
  <TravelItem>HONEY</TravelItem>
  <ClueItems />
  <TilesAreRandomized>true</TilesAreRandomized>
  <Tiles>
    <string>FORESTBEES</string>
    <string>FORESTBEES</string>
    <string>FORESTBEES</string>
    <string>FORESTBEES</string>
    <string>FORESTTREESROCKS</string>
    <string>FORESTTREESROCKS</string>
    <string>FORESTTREESROCKS</string>
    <string>FORESTTREESROCKS</string>
    <string>FORESTGLADE</string>
    <string>FORESTGLADE</string>
    <string>FORESTGLADE</string>
    <string>FORESTGLADE</string>
  </Tiles>
  <ItemsAreRandomized>true</ItemsAreRandomized>
  <Items>
    <string>NONE</string>
    <string>NONE</string>
    <string>NONE</string>
    <string>NONE</string>
    <string>NONE</string>
    <string>NONE</string>
    <string>NONE</string>
    <string>NONE</string>
    <string>NONE</string>
    <string>NONE</string>
    <string>NONE</string>
    <string>NONE</string>
  </Items>
</BoardModDescriptor>

The properties of a board are:

• SizeX and SizeY: how big the board is. A SizeX of 4 and SizeY of 3 means, that there are 4x3=12 tiles. It's recommended to have 4x3 as a maximal size, because bigger boards aren't displayed within the screen's bounds on smaller resolutions.
• Environment: in which environment the board is placed. The environment sets the surrounding decorations and other properties, like if clouds or birds fly around. Currently, it's not possible to make your own environments, but you can choose an existing one: FOREST, STEPPE, VILLAGE, MAGICALFOREST and MAGETOWER.
• IsHappinessRelevant: if "true", creatures can gain or lose hearts and get sad if their hearts reach zero. If the board shouldn't have any creature happiness, set this to "false".
• TravelItem: the item which is required to solve this board. It's displayed on the bottom-right tile within a little speech bubble. If this is set to "NONE", the board is not solvable. For our new mod, you could set this to "ORANGEJUICE".
• ClueItems: the so-called clues are item symbols at the screen's top. They give some hints on how to approach a puzzle. Setting it to "<ClueItems />" will show no clues at all. You can replace this with something along...

<ClueItems>
  <string>BOTTLE</string>
  <string>ORANGE</string>
</ClueItems>

• ...just for the purpose of demonstration. It will show a bottle and our added orange item as a clue at the top.
• TilesAreRandomized: we will define which tile types appear on the board in a second. The TilesAreRandomized property will set if these tile types are randomly placed on the board or in the order of their definition.
• Tiles: this area defines what type the tiles of the board have. If you set the board's size to SizeX=4 and SizeY=3, you need 4*3=12 tile type definitions here. The example above added 4x FORESTBEES, 4x FORESTTREESROCKS and 4x FORESTGLADE. If TilesAreRandomized is set to "true", these 12 tile types are randomly placed on the 4x3 board. If set to "false", the upper row of the board will have FORESTBEES, the mid row FORESTTREESROCKS and the last row FORESTGLADE, as that's the order in the definition. Check the list of tile types at the guide's end to get the flags of the main game's tile types. For our own mod, you should replace FORESTBEES with FORESTORANGES, so our own tile type which can spawn orange trees is able to appear.
• ItemsAreRandomized: instead of having the tiles generate their items at the start, we are also able to set the items manually. If ItemsAreRandomized is set to "true", these items will be placed randomly on the board.
• Items: here, the boards items at the start are defined. Again, for a board of 4x3 tiles we need to define 4x3=12 entries and set every tile's item. Setting a tile's item to "NONE" will let the tile generate their own item, but sometimes you want to have a specific item available right at the start, instead. You should replace one of the NONE with a BOTTLE so the player has a bottle to combine it with the orange.

Your tasks:

• change the scenario's identifier, for example to "myfirstmod_scenario"
• set the name and description of your scenario
• change the icon of the scenario in the "texture_1.png" file, if you want
• remove old item references (HONEY and BEE) from the creature definitions and replace them with your own items
• remove the second <BoardModDescriptor></BoardModDescriptor>, so your scenario has only one board
• set the TravelItem of the board to ORANGEJUICE
• set the ClueItems of the board to BOTTLE and ORANGE
• replace FORESTBEES with FORESTORANGES in the Tiles definition
• replace one NONE with a BOTTLE in the Items area of the board definition

Congratulations for making your first mod! In the next part we will test it.

Testing Mods

Save every document you opened and start the game. If it instantly closes (sometimes without any notification), it likely crashed. There should be a crashlog generated in

• Windows: "C:\Users\YourUsername\Documents\BrushwoodBuddies\crashlogs\"
• Linux: "%XDG_DATA_HOME%/BrushwoodBuddies/crashlogs/" or "%HOME%/.local/share/BrushwoodBuddies/crashlogs/"

Open the crashlog and check what kind of error you had. It's often related to typos in flag names or accidentally redefining an already existing flag. If the error message doesn't help, visit the Steam Brushwood Buddies forum (there's a modding subforum). It's better to submit your problem there, so everyone can see the solution.

If the game started normal, please make sure in the options that mods are allowed to load. If so, there should be two mods available after you clicked on the "Challenges" button in the main menu: the example mod and your own mod. Go and pick some orange fruits!

Short note about a common mistake: sometimes you test a mod and then make changes to it but after you reloaded the game, the changes aren't visible. If your scenario can be saved, you are likely created a save game and instead of loading a new session with your scenario changes, it justs shows you the old state. Therefore, you should delete the scenario's save game beforehand (with the little red button below the scenario's button) or set CanBeSaved in the scenario's file to "false" while testing.

Another tip: mods do save data into the player profile, for example which of the mod's recipes were discovered or if the scenario was already solved. You can reset this data by scrolling down the options and clicking on the corresponding button (more details are available in the options menu).

Sharing Data

Mods are able to share definitions between them. Therefore, flags for created items and so on should be unique. A new item "ORANGE" will be available in other mods, so you can make additions to the creations of other creators or make a theme mod, which adds new items and recipes, but doesn't use them in a scenario, so others can utilize your mod for their own scenarios.

Sharing Mods

If your mod is ready, create an archive out of it: right click on the mod's folder and choose "Send to" and "Archive" (or similar) in the appearing context menu. It will generate a "yourfirstmod.zip" which others can extract in their mod folder to play your mod. Be sure to upload and download mods only from trusted sources!

Style Guidelines

Do whatever you want with the modding to achieve interesting puzzles others can play. If you check the style of the original game, you encounter a couple of style rules. You don't have to follow them, but if you want to have a consistent look, here they are:

• every graphic in the game hasn't any anti-aliasing
• item icons and decoration objects use very saturated colors
• item icons only have a couple of colors used (a main color and if the area is big enough, a second lighter color for a highlight or a darker color for a shadow)
• item icons share the same color palette (the red of an apple is the same red used for the campfire)
• item icons relating to animals show the items relevant to bait them (the wildcat icon shows a wildcat with some grass in the background and a fish in the mouth, because you get the wildcat by combining high grass with a fish)
• food always have a cooked variant which does increase the happiness of some of the creatures
• item icons relating to animals have a dead variant and sometimes different outcomes when the dead variant is combined with a knife or a saw

Lists

Sound Themes:

• Wood
• Stone
• Meat
• Paper
• Coins
• Water

Environment Types:

• Forest
• Steppe
• Village
• MagicalForest
• MageTower

Creature Types:

• Woody
• Turnip
• Ghost
• Witch
• Machicken
• BossSkull

Tile Types:

• ForestTrees
• ForestTreesRocks
• ForestGlade
• ForestGladeTrader
• SteppeGrassland
• SteppeHighGrassland
• SteppeGrove
• SteppeScreeSlope
• SteppeMoor
• SteppeRiver
• SteppeRuins
• VillageGraveyard
• VillagePark
• VillageMine
• VillageMeadow
• VillageDestroyedHouses
• VillageMarket
• VillageBattlefield
• MagicalTrees
• MagicalGlade
• MagicalLake
• MagicalCanyon
• MagicalWitchHouse
• MagicalMushroomCircle
• FinalTile
• MagicalOutpost
• MagicalRuinSentinel
• MageTowerRoom
• MageTowerTrap
• MageTowerGarden
• MageTowerBasin
• MageTowerLibrary
• MageTowerKitchen
• MageTowerElevatorUp
• MageTowerElevatorDown
• MageTowerStairsUp
• MageTowerStairsDown
• MageTowerBoss
• MageTowerGate
• VillageMarketCampaign

Item Types:

• None
• Rock
• Grindstone
• Flint
• SharpenedFlint
• Shrub
• Tree
• Stick
• Leaf
• Log
• Knife
• Scythe
• Apple
• Dummy
• Saw
• Cart
• Rabbit
• DeadRabbit
• Meat
• CookedMeat
• Fur
• Trader
• Rope
• Float
• Campfire
• HighGrass
• Water
• Altar
• GraveMound
• Grass
• Insects
• Brushwood
• LongStick
• Yak
• DeadYak
• Hide
• Leather
• Slingshot
• Bird
• DeadBird
• Feather
• Bow
• Arrow
• BowAndArrow
• ArmoredBug
• DeadArmoredBug
• Wolf
• DeadWolf
• Treant
• DeadTreant
• Chitin
• Bark
• WolfHeart
• HeartKey
• Treasure
• FishingRod
• PreparedFishingRod
• Fish
• CookedFish
• Wildcat
• DeadWildcat
• CookedApple
• CookedInsects
• Shovel
• Pickaxe
• Acorn
• DestroyedHouse
• House
• Villa
• Well
• Gravestone
• BigRock
• Oven
• Silver
• SilverIngot
• Gold
• GoldIngot
• Nails
• Coins
• Spider
• DeadSpider
• Silk
• Gargoyle
• DeadGargoyle
• Werewolf
• DeadWerewolf
• Corpse
• Zombie
• Ash
• Urn_0
• Urn_1
• Urn_2
• Urn_3
• Urn_4
• Urn_5
• Backpack
• GlitchDust
• Roots
• Kettle
• Sand
• TradeGrindstone
• TradeFlint
• TradeAcorn
• TradeMeat
• TradeFeather
• TradeInsects
• TradeSilverIngot
• Loot
• Dummy_0
• Dummy_1
• Dummy_2
• GlitchStone
• Bottle
• HealthPotion
• NoShieldPotion
• NecroPotion
• GlitchPotion
• PoisonedPotion
• FoodMixture
• PoisonMixture
• EvilMushroom
• DeadEvilMushroom
• MushroomPowder
• ProtectedSentinel
• Sentinel
• DestroyedSentinel
• BigStatue
• Furniture
• Book
• Wand
• BlueProtectedSentinel
• BlueSentinel
• BlueDestroyedSentinel
• RedProtectedSentinel
• RedSentinel
• RedDestroyedSentinel
• GreenProtectedSentinel
• GreenSentinel
• GreenDestroyedSentinel
• ElementalSpear
• BossHeart
• BrokenBossHeart
• Upstairs
• Downstairs
• SpellbookSpider
• SpellbookZombie
• SpellbookEvilMushroom
• SpellbookWerewolf
• SpellbookRabbit
• FinalHeart_0
• FinalHeart_1
• FinalHeart_2
• FinalHeart_3
• FinalHeart_4
• FinalHeartPiece
• TradeLeather

Thank you for being part of the modding community! Don't forget to share your mod in the Steam forums.

Cheers,
Steven