GUI Category Modding Guide/0.5

This guide shows you how to add custom GUI categories into Medieval Engineers. These are the categories that appear to the left of the blocks' list in the G-Screen and are especially useful to organize all of a mod's items in one place. We'll be making an example mod in which the large stockpile blocks will be located under the Stockpile category.

Tools Used

• Notepad++

Prerequisites

• No prior programming knowledge is required, as we will only be dealing with XML. That being said, a superficial understanding of how it works can help you prevent syntax mistakes.

Mod Structure

Our example mod contains two folders and one file. First, let's create the folders.

1. Navigate to %appdata%/Roaming/MedievalEngineers/Mods
2. Create a new folder. Name it whatever you like. I'll be calling it ExampleMod. This is our mod's root folder.
3. Navigate to our mod's root folder.
4. Create a new folder. Name it Data, with a capital letter D.

Now that we have our mod structure, let's start adding the definitions.

Definitions

To create a GUI category, define a GuiBlockCategoryDefinition. This definition contains the name of the category, the items it contains, along with other options.

1. Open a new document in Notepad++ and paste the following code.
2. Save the file in our mod's Data folder as ExampleMod_GUICategory.sbc. The extension is mandatory, but the name is not. Prepending the name of the mod on the file name can also help avoid confusion with vanilla files.

<?xml version="1.0"  encoding="utf-8"?>
<Definitions xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  <CategoryClasses>
    <Category xsi:type="MyObjectBuilder_GuiBlockCategoryDefinition">
      <Id>
        <TypeId>GuiBlockCategoryDefinition</TypeId>
        <SubtypeId/>
      </Id>
      <DisplayName>Stockpiles</DisplayName>
      <Name>Stockpiles</Name>
      <Icon>Textures\GUI\Icons\Props\StockpileLogSmall.dds</Icon>
      <AvailableInSurvival>true</AvailableInSurvival>
      <ItemIds>
        <string>CubeBlock/StockpileTimber</string>
        <string>CubeBlock/StockpileLog</string>
        <string>CubeBlock/StockpileStone</string>
      </ItemIds>
    </Category>
  </CategoryClasses>
</Definitions>

Tip: Life is hard on its own. Go to the Language menu in Notepad++ and select XML as the file language, this will enable syntax highlighting.

1. Start the game and load our mod. Take a look at what we did and come back to the explanation later. (Note: Local mods can only be loaded in offline mode)

Explanation

• The XML prolog. Don't mess with it.

<?xml version="1.0" encoding="utf-8"?>

<?xml version="1.0"  encoding="utf-8"?>

• Opens (<>) and closes (</>) our definitions. A file can have multiple GuiBlockCategoryDefinitions in it, but all of them must be inside these tags.

<Definitions xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<CategoryClasses>
</CategoryClasses>
</Definitions>

• Tells the game we want to create a GUI Category, hence type GuiBlockCategoryDefinition.

<Category xsi:type="MyObjectBuilder_GuiBlockCategoryDefinition">
</Category>

• This is a standard definition ID. Judging by the way it's used here, it doesn't serve any purpose except to maintain compatibility with the game's definition manager. Changing anything here will break the definition. NOTE: This format is obsolete in 0.5 and will be incompatible in 0.6.

<Id>
<TypeId>GuiBlockCategoryDefinition</TypeId>
<SubtypeId/>
</Id>

• This is the name of the category that gets displayed in the toolbar configuration screen.

<DisplayName>Stockpiles</DisplayName>

• This must be a unique name. It can be used programmatically to identify the category.

<Name>Stockpiles</Name>

• This is the icon that will appear next to the category's name in the G-Sceen. The path is relative to you mod's root folder. If the file does not exist there, it will fallback to the Content folder in the game's files. This means you can use files from the game without copying them to your mod's folder.

<Icon>Textures\GUI\Icons\Props\StockpileLogSmall.dds</Icon>

• Whether this category should show up in Survival mode.
• There is a similar tag for Creative mode. It's <ShowInCreative>. Defaults to true.

<AvailableInSurvival>false</AvailableInSurvival>

• These are the items that will appear under this category.
• The strings format is TypeId/SubtypeId (Note the "/" between them)

<ItemIds>
  <string>CubeBlock/StockpileTimber</string>
  <string>CubeBlock/StockpileLog</string>
  <string>CubeBlock/StockpileStone</string>
</ItemIds>

Tip: Use Notepad++ Search in Files function to search vanilla definitions on the game's Data folder. You can access it by pressing Ctrl + Shift + F.

Conclusion & Challenge

This wraps up this guide about GUI Categories. I hope it was useful to you. As an optional challenge to see if you got everything right, try to:

1. Add the small stockpile blocks to our Stockpile category.