BlockCategories

HomeModdingTutorialsSBCBlockCategories

Beginner

Learnings

How to add a block to a category in the G-menu.

How to create your own category in the G-menu.

How to add a block to a scroll group (marked with the +).

How XML works.

Prerequisites

Completed setting up a modding environment for SBC modding.

Overview

Related

BlockCategories (Reference)

This tutorial teaches you how to add a block to one of the categories of blocks displayed in the G-menu on the left hand side and also explains how to add your own such category to the game. The relevant reference page for this tutorial is BlockCategories.

Adding to an existing BlockCategory

Step 1: Copy the vanilla BlockCategories file

Navigate to your game’s installation directory and into the Data-subfolder. There you will find the file named BlockCategories.sbc. Copy it into your mod’s Data-folder.

Step 2: Remove all unneeded categories

Open the file with your preferred XML editor. Within the element CategoryClasses you’ll see individual Category-entries defined. Search for the category you want to add your block(s) to either by looking at their Name or the individual block entries. Once you’ve found the Category you want, delete all other categories from the file.

Blocks are generally added to at least one vanilla category, which is the LargeBlocks or SmallBlocks category, depending on the block’s grid size.

Step 3: Add your block(s) to the entry

Next, you remove all existing blocks under ItemIds from the category and replace them with entries for your own blocks. An entry consists of a block’s TypeId and SubtypeId, separated by a / slash.

Note that these entries are additive, which means that you will not have to include all entries in the vanilla BlockCategory if you’d like to add your own.

For this example, I’m going to use my conveyor mod. As you can see below, I added the relevant blocks both to the Large Blocks and the Conveyor-categories. If my blocks were also available for small grid, I would be adding them to that category here too.

<?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>DisplayName_Category_LargeBlocks</DisplayName>
      <Name>LargeBlocks</Name>
      <ItemIds>
        <string>Conveyor/AQD_LG_ConveyorJunctionTubes</string>
        <string>Conveyor/AQD_LG_ConveyorX</string>
        <string>ConveyorConnector/AQD_LG_ConveyorStraight5x1</string>
        <string>ConveyorConnector/AQD_LG_ConveyorStraightArmored</string>
        <string>ConveyorConnector/AQD_LG_ConveyorCornerArmored</string>
        <string>Conveyor/AQD_LG_ConveyorTArmored</string>
        <string>Conveyor/AQD_LG_ConveyorXArmored</string>
        <string>CargoContainer/AQD_LG_ConveyorAccess</string>
        <string>CargoContainer/AQD_LG_ConveyorVent</string>
      </ItemIds>
    </Category>
    <Category xsi:type="MyObjectBuilder_GuiBlockCategoryDefinition">
      <Id>
        <TypeId>GuiBlockCategoryDefinition</TypeId>
        <SubtypeId/>
      </Id>
      <DisplayName>DisplayName_Category_ConveyorBlocks</DisplayName>
      <Name>Conveyors</Name>
      <ItemIds>
        <string>Conveyor/AQD_LG_ConveyorJunctionTubes</string>
        <string>Conveyor/AQD_LG_ConveyorX</string>
        <string>ConveyorConnector/AQD_LG_ConveyorStraight5x1</string>
        <string>ConveyorConnector/AQD_LG_ConveyorStraightArmored</string>
        <string>ConveyorConnector/AQD_LG_ConveyorCornerArmored</string>
        <string>Conveyor/AQD_LG_ConveyorTArmored</string>
        <string>Conveyor/AQD_LG_ConveyorXArmored</string>
        <string>CargoContainer/AQD_LG_ConveyorAccess</string>
      </ItemIds>
    </Category>
  </CategoryClasses>
</Definitions>

Step 4: Test ingame

Start up the game and add your mod to a savegame. Then load it and check your G-menu and the category you altered. The block(s) should now show up:

Creating a new BlockCategory

Step 1: Copy the vanilla BlockCategories file

In some cases, you might want to create your own category instead of extending an existing one. To do that, navigate to your game’s installation directory and into the Data-subfolder. There you will find the file named BlockCategories.sbc. Copy it into your mod’s Data-folder.

Step 2: Remove all entries except for one

Open the file with your preferred XML editor and delete all Category-entries from the file except one. It doesn’t really matter which one - it’s kept purely so that we don’t have to write it from scratch.

Step 3: Adjust entry

Change the DisplayName property like so: <DisplayName>{LOC:DisplayName_Category_[YourIdentifier]}</DisplayName and replace [YourIdentifier] with a name that identifies your category.

Use the same identifier in the Name-element of your Category-entry.

Replace the block entries under ItemIds with your own block entries as normal.

For this example I’m using my concrete mod, in which I add a new category for concrete blocks:

<?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>{LOC:DisplayName_AQD_Cat_Concrete}</DisplayName>
      <Name>Concrete</Name>
      <ItemIds>
        <string>CubeBlock/AQD_LG_Concrete_Block</string>
        <string>CubeBlock/AQD_LG_Concrete_Slope</string>
        <string>CubeBlock/AQD_LG_Concrete_Corner</string>
        <string>CubeBlock/AQD_LG_Concrete_Corner_Inv</string>
        <string>CubeBlock/AQD_LG_Concrete_Half_Block</string>
        <string>CubeBlock/AQD_LG_Concrete_Half_Block_Slope</string>
        <string>CubeBlock/AQD_LG_ReinforcedConcrete_Block</string>
        <string>CubeBlock/AQD_LG_ReinforcedConcrete_Slope</string>
        <string>CubeBlock/AQD_LG_ReinforcedConcrete_Corner</string>
        <string>CubeBlock/AQD_LG_ReinforcedConcrete_Corner_Inv</string>
        <string>CubeBlock/AQD_LG_ReinforcedConcrete_Half_Block</string>
        <string>CubeBlock/AQD_LG_ReinforcedConcrete_Half_Block_Slope</string>
      </ItemIds>
    </Category>
  </CategoryClasses>
</Definitions>

Step 4: Create RESX entry

Follow the Localization-tutorial to create a RESX-entry for your `DisplayName_Category_[YourIdentifier]` name of the category.

Step 5: Test ingame

Start up the game and add your mod to a savegame. Then load it and check your G-menu. The category you added should now be present in the list and feature any blocks you’ve added to it:

Sub-categories explained

All the entries on the left of the Toolbar Config (g-menu) are just categories, the ones that look like "sub-categories" have 3 spaces before their name, that's all.
Their order is determined by the <Name>, see below for details.

Placing a category after an existing one

Simplest way is to find the category that you want to follow and copy its <Name>, then append something after said name and use that as your category's <Name>.

For example: to add a category after Armor Blocks, its name is Section1_Position2_Armorblocks therefore your category's name can be Section1_Position2_Armorblocks_Fancy which will position it right after that.
This also means if another mod adds a Section1_Position2_Armorblocks_Athing category, then their category will be in between yours and theirs, because A is before F.

If you wish it to look like a "sub-category" then add the 3 spaces before the visual name in the <DisplayName> element.

Example

    <Category xsi:type="MyObjectBuilder_GuiBlockCategoryDefinition">
      <Id>
        <TypeId>GuiBlockCategoryDefinition</TypeId>
        <SubtypeId/>
      </Id>
      <DisplayName>   Fancy Armor</DisplayName>
      <Name>Section1_Position2_Armorblocks_Fancy</Name>
      <ItemIds>
        <string>CubeBlock/YourFancyArmorBlock</string>
        <!-- etc... -->
      </ItemIds>
    </Category>

Here's how this would look like:

Troubleshooting

My block does not show up in the category I added it to

Solution

1. Did you pair your block with another block in the same category using BlockPairName? If you pair a small grid and a large grid block using BlockPairName in the CubeBlocks-definition, and both are added to the same BlockCategory, only the large grid block will be displayed. The only way to show the small grid version separately is to add it to a category that its large grid counterpart is not part of.

My weapon / tool cannot be placed as such onto the hotbar

Solution

1. Is it part of a category marked with IsToolCategory = true ? In order for your weapon or tool to show up as such in the Hotbar Config menu, it must be part of a category marked as a tool category using IsToolCategory = true in its category definition.