Rules
Rules are the core concept of a Theme. They are grid patterns that decide whether a specific Tile is placed in a corresponding tilemap.
Creating a rule
To create a rule, click the Add rule button inside the header of a rule group.
Next, click on the grid on the left-hand side of the newly created rule. The Rule editor should open. It is a good idea to dock the window somewhere if you plan to create a bunch of rules.
At the top of the window, we configure the output of the rule. We can use the dropdown to change between Tiles and Game objects. If we click the Add tile button, it prompts us to choose a tile. After we do that, the tile should appear at the top of the window.
Selecting a tile in the default object picker is sometimes a bit cumbersome. Therefore, there are two more ways to add tiles. First, if you select the Default brush in the Tile Palette window and click on a tile with the Paint with active brush tool, you can then click Add from brush button and the output should appear. This approach is quite nice if you like picking the tiles from the palette.
The second option is to just drag and drop the tile directly from the Project view onto the output area of the window.
You can add more than one output and one will be chosen randomly each time a rule is applied. You can also remove output by right-clicking on them.
With the output in place, we can focus on setting up the grid pattern. The idea is very similar to Rule tiles from the 2D Tilemap Extras package from Unity. On the left-hand side of the window, you have a list of Int grid tiles that you created in the Theme. Click on a tile to select it and then click anywhere in the grid to set the tile. You can clear a cell by middle-clicking or add a negative tile by right-clicking.
For example, the grid pattern below will get applied whenever a tile is a Wall tile, the tile to the top is a Floor and the tile on the left is NOT a Floor tile.
Controls
Apart from the grid pattern, there are other controls that influence when a rule can be applied. These controls can be found in the Theme editor window inside each rule item.
Probability
The Probability control adds randomness when deciding whether a rule can be applied. By default, the probability of a rule is set to 100%, meaning that the rule is applied whenever it can be applied. Using the control, the probability can be set between 1% and 100%.
The Probability control is not the best way to apply rules in regular intervals/distances. Each time a rule is evaluated, we roll a dice and check whether the value is less than or equal to the selected probability. This can lead to a rule being applied to 2 adjacent tiles even though the probability is set to 1%.
Mirror X, Mirror Y
These two controls make it possible to mirror the whole rule horizontally and/or vertically. Both the rule output and grid pattern are mirrored.
Note that you can use the Lock transform control to only transform the grid pattern while keeping the original orientation of output tiles and/or game objects.
Rotate
This control makes it possible to rotate the rule by multiples of 90 degrees. Whenever enabled, all 4 rotations of the rule are allowed.
Note that you can use the Lock transform control to only transform the grid pattern while keeping the original orientation of output tiles and/or game objects.
Lock transform
This control is used in combination with Mirror X, Mirror Y or Rotate controls. Whenever enabled, it keeps the original orientation of a rule output even though the grid pattern itself can be transformed.
This behavior can be very useful when working with 2D tiles because it is often not possible to rotate/transform these tiles but it can be beneficial to transform the grid pattern itself.
Modulo
The Modulo control makes it possible to apply a rule every N tiles.
The Modulo control can also be used to create a checkerboard pattern. You simply need to create another rule with the same modulo values, but offset by 1.
Transform
The Transform control makes it possible to move and rotate the output of a rule. In 2D levels, this might be useful if you have a tile that you need to rotate because it does not have all the rotations provided in a tileset. In 3D levels, it might be even more useful whenever we need to make sure the game object is oriented according to the grid pattern.
Perlin noise
The Perlin noise control samples a Perlin noise texture and based on the value decides whether the rule should be applied or not. Three parameters control the noise.
Scale controls the frequency of the noise. When the scale is small, there are large areas where the rule is applied and large areas where not. If we increase the scale, we can see that now there are many smaller areas where the noise is applied.
Threshold controls how large the underlying noise value must be to apply the rule. With the default value of 50, the rule is applied for approximately 50% of the time. If we increase the value, the rule is applied less often, while if we decrease the value, the rule is applied more often.
Seed is used to control the seed of the noise. If you want two rules to share the same noise values, you need to use the same seed.
A common use case of Perlin noise is when we want to introduce randomness that does not change as often as rolling a dice. With perlin noise, we get consecutive areas where a rule is applied, and consecutive areas where not.
Blue noise
The Blue noise control makes it possible to place tiles a specific distance from each other. There are 2 parameters that control the noise.
Distance controls how far from each other the tile should be. The maximum allowed distance is 16 tiles. Note that it is not possible to enforce the exact distances. For example, if we set the distance to 5 tiles, there might be pairs of tiles that are only 4 tiles away from each other, and there might also be tiles that are more than 6 tiles away from each other.
Seed controls the seed of the noise. Allowed values are from 0 to 63 (inclusive).
One possible use case for the blue noise would be placing trees or enemies that should be approximately N tiles away from each other. You can also use it if you want to place some rewards like treasure chests and you want to make sure there are no treasure chests right next to each other, as it could happen with the probability control