BlockVariantGroups

HomeModdingTutorialsSBCBVGs

beginner

Learnings

How to add a block to an existing BVG in the G-menu.

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

How to add a block variant group.

How XML works.

Prerequisites

Completed setting up a modding environment for SBC modding.

Overview

Related

BlockVariantGroups (Reference)

This tutorial teaches you how to add a block to one of the block “scroll groups” marked with + in the G-menu (called BlockVariantGroup or BVG) and also explains how to create your own such group. The relevant reference page for this tutorial is BlockVariantGroups.

Adding to a BlockVariantGroup

Step 1: Copy the vanilla BlockVariantGroup file.

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

Step 2: Remove all unused groups.

Open the file with your preferred XML editor. Within the element BlockVariantGroups you'll see individual BlockVariantGroup-entries defined. Search for the groupyou want to add your block(s) to either by looking at their Subtype or the individual block entries. Once you’ve found the BVG you want, delete all other groups from the file.

Step 3: Add your block(s) to a group.

Next, you create entries for each of the blocks you want to add to the group under Blocks. Note that the first entry in the list defines the block that is shown on the “face” of the group, marked with the + and the order in which they are listed in the BVG corresponds to the order of the entries under Blocks. An entry for a block consists of the following:

<Block Type="MyObjectBuilder_CubeBlock" Subtype="LargeBlockArmorBlock" />

Type is your block’s TypeId with MyObjectBuilder_ added to the front of it.

Subtype is the same as your block’s SubtypeId.

Note that BVGs are non-additive. This means that you have to redefine the entire BlockVariantGroup and all its entries if you would like to extend one that exists in the base game. It also means that if two mods edit the same group, the one higher in the mod list will entirely overwrite the one lower in the list.

As an example of amending an existing BVG, I’m going to use my conveyor expansion mod. Below you’ll see an example of a BVG I have adjusted, which is the ConveyorThickGroup that is essentially the large grid and medium size small grid conveyor group:

<?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">
  <BlockVariantGroups>
    <BlockVariantGroup>
      <Id Type="MyObjectBuilder_BlockVariantGroup" Subtype="ConveyorThickGroup" />
      <Icon>Textures\GUI\Icons\Cubes\ConveyorTube.dds</Icon>
      <DisplayName>DisplayName_ConveyorTube</DisplayName>
      <Description>Description_ConveyorTube</Description>
      <Blocks>
        <Block Type="MyObjectBuilder_ConveyorConnector" Subtype="ConveyorTube" />
        <Block Type="MyObjectBuilder_ConveyorConnector" Subtype="ConveyorTubeCurved" />
        <Block Type="MyObjectBuilder_Conveyor" Subtype="ConveyorTubeT" />
        <Block Type="MyObjectBuilder_Conveyor" Subtype="AQD_LG_ConveyorX" />
        <Block Type="MyObjectBuilder_Conveyor" Subtype="AQD_LG_ConveyorJunctionTubes" />
        <Block Type="MyObjectBuilder_ConveyorSorter" Subtype="LargeBlockConveyorSorter" />
        <Block Type="MyObjectBuilder_ConveyorConnector" Subtype="ConveyorTubeMedium" />
        <Block Type="MyObjectBuilder_ConveyorConnector" Subtype="ConveyorTubeCurvedMedium" />
        <Block Type="MyObjectBuilder_Conveyor" Subtype="SmallShipConveyorHub" />
        <Block Type="MyObjectBuilder_ConveyorConnector" Subtype="ConveyorFrameMedium" />
        <Block Type="MyObjectBuilder_Conveyor" Subtype="SmallBlockConveyorConverter" />
        <Block Type="MyObjectBuilder_ConveyorSorter" Subtype="MediumBlockConveyorSorter" />
      </Blocks>
    </BlockVariantGroup>
  </BlockVariantGroups>
</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 BVG you altered. The group should now show up with your added blocks:

Creating a new BlockVariantGroup

Step 1: Copy the vanilla BlockVariantGroups file.

In some cases, you might want to create your own BVG 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 BlockVariantGroups.sbc. Copy it into your mod’s Data-folder.

Step 2: Remove all groups except for one.

Open the file with your preferred XML editor and delete all BVG-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 one from scratch.

Step 3: Adjust group.

Change the SubtypeId to a unique one fitting the contents of your group.

For Icon, DisplayName and Description, insert the information from the CubeBlocks-entry of the block that you want to display first in the BVG.

Finally, replace all entries under Blocks with your own entries - be they your blocks or base game blocks as normal.

As an example, for the conveyor expansion mod I made, I moved all the reinforced conveyors into their own BVG instead of being part of a general one:

<?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">
  <BlockVariantGroups>
    <BlockVariantGroup>
      <Id Type="MyObjectBuilder_BlockVariantGroup" Subtype="ConveyorReinforcedGroup" />
      <Icon>Textures\GUI\Icons\Cubes\ConveyorDuct.dds</Icon>
      <DisplayName>DisplayName_ConveyorTubeDuct</DisplayName>
      <Description>Description_ConveyorTubeDuct</Description>
      <Blocks>
        <Block Type="MyObjectBuilder_ConveyorConnector" Subtype="ConveyorTubeDuct" />
        <Block Type="MyObjectBuilder_ConveyorConnector" Subtype="ConveyorTubeDuctCurved" />
        <Block Type="MyObjectBuilder_Conveyor" Subtype="ConveyorTubeDuctT" />
        <Block Type="MyObjectBuilder_ConveyorConnector" Subtype="ConveyorTubeDuctSmall" />
        <Block Type="MyObjectBuilder_ConveyorConnector" Subtype="ConveyorTubeDuctSmallCurved" />
        <Block Type="MyObjectBuilder_Conveyor" Subtype="ConveyorTubeDuctSmallT" />
      </Blocks>
    </BlockVariantGroup>
  </BlockVariantGroups>
</Definitions>

Step 4: Test ingame.

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

Troubleshooting

The BVG cannot be moved to the hotbar / is blocked

Solution

1. Is the first block in the BVG a block marked as restricted to a DLC you don’t own? If the first block in a BVG is restricted to a DLC that you do not own, the whole BVG will be blocked from use, even if other blocks in the group might not be restricted.

Blocks do not appear in the correct position within the BVG

Solution

1. Is the wrong block displayed as the first block in the group? BVGs are hardcoded to always prefer blocks that have a paired small grid / large grid block via BlockPairName defined in their CubeBlocks-definition. If such a block is in the group, a block without small grid / large grid equivalent can never be listed in first position.

My block does not appear in the BVG it was added to

Solution

1. Is the BVG pointing to the block's <TypeId> and <SubtypeId> node? Ignore the xsi:type and copy the value from <TypeId> on your block and append MyObjectBuilder_ in front of it.
2. Is another mod installed in your savegame that alters the same BVG? As BVGs are not additive, if two mods alter the same one, the mod that is located higher in the modlist of the savegame will always overwrite the changes the other mod has made.