GUI Category Modding Guide/0.5: Difference between revisions

From Medieval Engineers Wiki
Jump to navigation Jump to search
mNo edit summary
mNo edit summary
 
(3 intermediate revisions by the same user not shown)
Line 1: Line 1:
<small> &lt; [[GUI Category Modding Guide]]</small>
{{SEO|description=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.}}
 
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.
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.
{{Version <!-- Do not change the version until the entire page is up-to-date -->
{{Version <!-- Do not change the version until the entire page is up-to-date -->
Line 27: Line 26:
# 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.
# 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.


<source lang="xml" collapse="false">
<syntaxhighlight lang="xml" collapse="false" line>
<?xml version="1.0"  encoding="utf-8"?>
<?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">
<Definitions xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
Line 48: Line 47:
   </CategoryClasses>
   </CategoryClasses>
</Definitions>
</Definitions>
</source>
</syntaxhighlight>




Line 58: Line 57:
== Explanation ==
== Explanation ==
* The XML prolog. Don't mess with it.
* The XML prolog. Don't mess with it.
<source lang="xml" collapse="false">
<syntaxhighlight lang="xml" collapse="false">
<?xml version="1.0"  encoding="utf-8"?>
<?xml version="1.0"  encoding="utf-8"?>
</source>
</syntaxhighlight>
<br>
<br>
* Opens (<>) and closes (</>) our definitions. A file can have multiple ''GuiBlockCategoryDefinitions'' in it, but all of them must be inside these tags.
* Opens (<>) and closes (</>) our definitions. A file can have multiple ''GuiBlockCategoryDefinitions'' in it, but all of them must be inside these tags.
<source lang="xml" collapse="false">
<syntaxhighlight lang="xml" collapse="false">
<Definitions xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<Definitions xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<CategoryClasses>
<CategoryClasses>
</CategoryClasses>
</CategoryClasses>
</Definitions>
</Definitions>
</source>
</syntaxhighlight>
<br>
<br>
* Tells the game we want to create a GUI Category, hence type ''GuiBlockCategoryDefinition''.
* Tells the game we want to create a GUI Category, hence type ''GuiBlockCategoryDefinition''.
<source lang="xml" collapse="false">
<syntaxhighlight lang="xml" collapse="false">
<Category xsi:type="MyObjectBuilder_GuiBlockCategoryDefinition">
<Category xsi:type="MyObjectBuilder_GuiBlockCategoryDefinition">
</Category>
</Category>
</source>
</syntaxhighlight>
<br>
<br>
* 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.  
* 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.  
<source lang="xml" collapse="false">
<syntaxhighlight lang="xml" collapse="false">
<Id>
<Id>
<TypeId>GuiBlockCategoryDefinition</TypeId>
<TypeId>GuiBlockCategoryDefinition</TypeId>
<SubtypeId/>
<SubtypeId/>
</Id>
</Id>
</source>
</syntaxhighlight>
<br>
<br>
* This is the name of the category that gets displayed in the toolbar configuration screen.
* This is the name of the category that gets displayed in the toolbar configuration screen.
<source lang="xml" collapse="false">
<syntaxhighlight lang="xml" collapse="false">
<DisplayName>Stockpiles</DisplayName>
<DisplayName>Stockpiles</DisplayName>
</source>
</syntaxhighlight>
<br>
<br>
* This must be a unique name. It can be used programmatically to identify the category.
* This must be a unique name. It can be used programmatically to identify the category.
<source lang="xml" collapse="false">
<syntaxhighlight lang="xml" collapse="false">
<Name>Stockpiles</Name>
<Name>Stockpiles</Name>
</source>
</syntaxhighlight>
<br>
<br>
* 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.
* 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.
<source lang="xml" collapse="false">
<syntaxhighlight lang="xml" collapse="false">
<Icon>Textures\GUI\Icons\Props\StockpileLogSmall.dds</Icon>
<Icon>Textures\GUI\Icons\Props\StockpileLogSmall.dds</Icon>
</source>
</syntaxhighlight>
<br>
<br>
* Whether this category should show up in Survival mode.
* Whether this category should show up in Survival mode.
* There is a similar tag for Creative mode. It's <ShowInCreative>. Defaults to true.
* There is a similar tag for Creative mode. It's <ShowInCreative>. Defaults to true.
<source lang="xml" collapse="false">
<syntaxhighlight lang="xml" collapse="false">
<AvailableInSurvival>false</AvailableInSurvival>
<AvailableInSurvival>false</AvailableInSurvival>
</source>
</syntaxhighlight>
<br>
<br>
* These are the items that will appear under this category.
* These are the items that will appear under this category.
* The strings format is '''TypeId'''/'''SubtypeId''' (Note the "/" between them)
* The strings format is '''TypeId'''/'''SubtypeId''' (Note the "/" between them)
<source lang="xml" collapse="false">
<syntaxhighlight lang="xml" collapse="false">
<ItemIds>
<ItemIds>
   <string>CubeBlock/StockpileTimber</string>
   <string>CubeBlock/StockpileTimber</string>
Line 113: Line 112:
   <string>CubeBlock/StockpileStone</string>
   <string>CubeBlock/StockpileStone</string>
</ItemIds>
</ItemIds>
</source>
</syntaxhighlight>




Line 123: Line 122:


# Add the small stockpile blocks to our Stockpile category.
# Add the small stockpile blocks to our Stockpile category.
[[Category:Community_Guides]]

Latest revision as of 20:18, 18 July 2022


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.

Version: 0.5

Tools Used

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"?>


  • 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.