Grouping

Block grouping is an advanced mechanic by which blocks of the same group will propagate the same ID or IDs from a seed to each other.
Grouping is cross screens, as such a block on the top edge of a screen will group with a block at the bottom of the next screen.
This feature is mainly used in the group and sequence block types, but will also find use in single use levers of the countdown type.
After starting the game in debug mode you will find seeds and resets .xml files inside the saves folder.

It is recommended to keep the ids tightly packed avoiding large gaps.

Groups

The mod provides four different colour groups (A, B, C, and D) that create a group if placed next to each other on the hitbox file. This is according to the four colour theorem and allows for any combination of groups. If you however find an example that requires five you may report your findings to the nearest academy.
This means, if you do not plan on having platforms touch, you will be fine using only colour group A.

Seed

To have consistent groups across sessions a file is created containing hitbox position and the associated group number.
While this file, like the save, is created automatically, it should be included in your steam upload.
The file gets created in the [OnLevelStart] step. Modifying this file allows for various effects like setting multiple groups to use the same group number syncing them up despite not being neighbours or even of the same colour. However do not use the 0 as a group number as this is used internally as "is not part of a group". Despite its .sav file ending it can be opened like any text/.xml file. Position is stored in a single integer. X and Y can never be a three digit number. Screen can never be a four digit number (it actually can be as the game does not hardcode a screen number, it is unlikely for a map to use over 1 thousand screens). As such the integers form is 0...00SSSXXYY. While it might be awkward compared to using a more coherent representation like a Vector3, this is an optimization that significantly improves load times (~80% speed-up).

Group Example

Note that the groups are:

• On screen 9, X 19, Y 25 (91925)
• On screen 9, X 25, Y 25 (92525)
• On screen 9, X 31, Y 25 (93125)

<?xml version="1.0" encoding="utf-8"?>
<SeedsGroup>
  <_seeds>
    <_seed>
      <_position>91925</_position>
      <_id>1</_id>
    </_seed>
    <_seed>
      <_position>92525</_position>
      <_id>2</_id>
    </_seed>
    <_seed>
      <_position>93125</_position>
      <_id>3</_id>
    </_seed>
    <_seed>
  </_seeds>
</SeedsGroup>

Resets

To limit which groups a lever is able to reset a file is created containing hitbox position and the group numbers the lever can reset. While this file, like the save, is created automatically, it should be included in your steam upload. The file gets created in the [OnLevelStart] step. It uses the same coordinate format as the seed. The <_id> lists all group ids this reset block can reset, however 0 once again is used to indicate that there is no restriction and all groups will be reset. Adding more <_id>X</_id> (where X is the group id) limits the reset to those groups, therefore <_id>8</_id> would reset only group 8.

Reset Example

Note that the reset:

• On screen 19, X 10, Y 13 (191013) can reset groups with the id 8 and 9

<ResetsGroup>
  <_resets>
    <_reset>
      <_position>191013</_position>
      <_id>8</_id>
      <_id>9</_id>
    </_reset>
  </_resets>
</ResetsGroup>

Linking drawables

When placing a drawable at the same position as the block the mod will automatically associate the drawable to the blocks id.
However to allow for drawables to be placed anywhere while still being associated with the block you may add a <Link> element to your drawable that point it to the right block position. Inside the link element you define <Screen>, <X>, and <Y> of the block in hitbox coordinates (This is the screen position divided by 8).

Linking example

<?xml version="1.0"?>
<Platforms xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <Platform>
        <Texture>example_platform_texture</Texture>
        <Position>
            <X>300</X>
            <Y>180</Y>
        </Position>
        <Link>
            <Screen>9</Screen>
            <X>19</X>
            <Y>25</Y>
        </Link>
        <Animation>
            <Style>bottom</Style>
            <Curve>easeInOut</Curve>
        </Animation>
        <AnimationOut>
            <Style>left</Style>
        </AnimationOut>
        <IsForeground />
    </Platform>
</Platforms>

Legacy files

Cache is the old legacy file that held group information, when the Mod moved away from using an XmlSerializer in favour of LINQ the files created changed name and structure, but remained more or less the same in terms of how information is conveyed, while the mod can handle these legacy files it is recommended to use the new system as it creates smaller files with an easier to read structure.