Keen:GUI Category

OFFICIAL CONTENT NOTICE

OFFICIAL CONTENT

This article contains official content from or verified by the developers at Keen Software House. This information is intended to be accurate at the time it is posted, but may become obsolete over time. If you find errors in this article please describe the errors in the Discussion Page.

This guide shows you how to add custom search categories into Medieval Engineers. Categories in 0.6 have much of the same functionality as they did in 0.5 but the way the GUI uses them is different. Fundamentally, they are still a group of similar blocks, nothing more and nothing less. The differences are subtle but ultimately confusing for anyone looking for the simple functionality in previous versions of the game.

View items by category: This is still very much possible in the general search screen but there is no longer a category list to easily click on. If you check the help tab in the general search you will see that there is a symbol for categories $. Simply type this symbol followed by the name of the category to display only the item in that category.
Tabs replace the list: The list is gone but any search can be saved as a tab. This essentially keeps a smaller but more versatile list.
Categories can have items from other categories: It is also worth noting that categories are not mutually exclusive. This makes it possible to create custom groupings if that is desired.
Searches are sorted by category: In previous version of the game, items were arranged in a grid based on item position information that was unique for each item, and non-positioned items filled in empty spaces. In the general search screen items are arranged by category first and then by name. Both of these are sorted alphabetically, e.g. $arches comes before $battlements, so you will see the arches displayed first in any search containing arch items. The items in $arches are then sorted by title, e.g. Arch comes before Small Arch.

Version:

0.6.2

Tools Used

Notepad++: This, any other advanced text editor, or a full IDE, are recommended. While these tools offer seemingly endless ways to manipulate text, perhaps the most important feature for this simple kind of mod is syntax highlighting. This will make it easier to identify different parts of the code and to more easily see if you have made any syntax mistakes.

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.

Navigate to %appdata%/Roaming/MedievalEngineers/Mods
Create a new folder. Name it whatever you like. I'll be calling it ExampleMod. This is our mod's root folder.
Navigate to our mod's root folder.
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 SearchCategoryDefinition. This definition contains the name of the category, the items it contains.

Open a new document in Notepad++ and paste the following code.
Save the file in our mod's Data folder as ExampleMod_SearchCategory.sbc. The extension is mandatory, but the name can be anything you want. Prepending the name of the mod on the file name can also help avoid confusion with vanilla files and other mods.

<?xml version="1.0"?>
<Definitions xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  <Definition xsi:type="MyObjectBuilder_SearchCategoryDefinition">
    <Id Type="SearchCategoryDefinition" Subtype="stockpiles" />
    <DisplayName>Stockpiles Category</DisplayName>

    <Entry Type="CubeBlock" Subtype="StockpileTimber" />
    <Entry Type="CubeBlock" Subtype="StockpileLog" />
    <Entry Type="CubeBlock" Subtype="StockpileStone" />
  </Definition>
</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.

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 and you will see a version warning when loading the world)

Explanation

The XML prolog. Don't mess with it.

<?xml version="1.0"?>

There are two sets of tags that are used by every definition file. Definitions opens and closes the file, while Definition opens and closes each definition.

It is possible and common to have multiple Definition tags in a single file.
xsi:type="MyObjectBuilder_SearchCategoryDefinition" how this code tells the game what kind of data the definition contains. Without this, the definition cannot be used.
Notice the /> at the end. This is a self-contained tag which is completely valid syntax in XML when no value exists within the tag. The "Type" and "Subtype" are specified as attributes.

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

This is a standard definition ID. All definitions are loaded into a definition manager that serves as a temporary internal database while the world is loaded. ID's are the only way to identify definitions.

Type serves as a data category, there will be multiple SearchCategoryDefinition stored.
Subtype serves as a unique identifier, there can only ever be one stockpiles. This requirement is what makes modding of existing content possible. Created a duplicate definition ID will allow a modder to override a definition, e.g. by using Subtype="arches', the arches category could be changed.

<Id Type="SearchCategoryDefinition" Subtype="stockpiles" />

This is the name of the category that can be displayed on the GUI. Currently this is not being used but the GUI is not final so this should not be left out.

<DisplayName>Stockpiles</DisplayName>

These are the items that will appear in this category.

They use the standard ID format and must have the correct Type and Subtype. It is not possible to substitute Tag ID's at this time.
These are self-contained tags that use the /> closing.

<Entry Type="CubeBlock" Subtype="StockpileTimber" />
<Entry Type="CubeBlock" Subtype="StockpileLog" />
<Entry Type="CubeBlock" Subtype="StockpileStone" />

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 Search Categories. I hope it was useful to you. As an optional challenge to see if you got everything right, try to:

Add the small stockpile blocks to our Stockpile category.