Grate-Documentation
Workflow Overview
Grate generates levels by filling a three-dimensional cells with modular assets.
The typical workflow for creating level with Grate goes as follows:
- Create a cell size object that determines the size of the cells.
- Create a ruleset object that determines what will be instantiated in a cell.
- Create a level object that defines that defines the layout of the cells and how they will be connected.
- Create a area object that specifies a specific layout of cells withing the level.
Each of these objects can be created through the Tools/Grate/ menu.
The Create Level Template option does fill out a template level with the steps 2 to 4 in the list and prefabs for the objects will be created and put in the Level Templates folder.
All of the examples in this documentation are taken from the Basic Example which can be found in the Grate/Examples/Basic Example/ folder.
The Cell Size
Choosing the cell’s size is the most important decision in generation a level with Grate. It defines the height and width of each cell. A cell size is a ScriptableObject and can be created through the Tools/Grate/ menu.
The Ruleset
A ruleset defines what objects to instantiate in a specific cell.
A ruleset is defined as a hierarchy of game objects. On the top hierarchy we have an object with the ruleset instantiator component. A ruleset may inherit rules from other rulesets.
Each child rule of the ruleset instantiator will be evaluated. There two types of rules: Content Rules and Selector Rules.
The Content Rule
A content rule specifies a local condition. It also specifies what to instantiate if that condition is satisfied.
When a content rule is evaluated it is supplied with a location and rotation within an area in a level. The local condition is visualized in the scene by 3x3x3 grid of spherical nodes. This grid of nodes may be modified by clicking on the nodes and selecting an appropriate in the inspector.
When a content rule applies to some specific location and rotation it will randomly select an object among it’s children and instantiate it in the corresponding location and rotation.
Instantiation Modifiers
There are a number of components that may be added to the children of a content rule in order to modify its instantiation or selection.
Adding random transform to Selections
There are three components that may assist in adding some random size, rotation, or position offset to the spawned objects.
- Scale Modifier
- Position Modifier
- Rotation Modifier
Each of these specifies a range of possible random values that may be applied to the corresponding object.
Weighting Selections
A Selection Weight component may be supplied in order make a child of the Content Rule to be more or less likely to be selected than their siblings. If not Selection Weight is attached the child will automatically receive a weight of 1.
The Selector Rule
A Selector Rule selects among it’s children a rule that may apply within a given cell and rotation. The selector will evaluate it’s children from top to button until it finds one that satisfied in the given location and rotation.
There are two rotational evaluation modes for the Selector Rule. These modes are the following:
- Individual
- Grouped
If the individual mode is toggled the selector will for each rotation individually evaluate the child rules. If the grouped active on the other hand the selector will for each child rule test all possible rotations before proceeding to the next rule.
The Level
A level is defined by an level generator and a hierarchy of regions. The regions defines the physical bounds of the level. The level generates room and corridors in the regions in such a way that all horizontally connected regions are connected by said rooms and corridors. The level may also insert certain specified areas into the regions. Once the regions are filled with rooms and corridors they are instantiated with the provided rulesets.
A generation log is shown in the level generator inspector. If the generation fails the log serves as an aid in figuring out why the generation failed.
Regions
The Level Generator operates on an hierarchy of regions when generating the level. The region objects with exception of the root region is supplied with a cell grid snapper witch forces it to align the region or area with the cell grid.
Composite Regions
Composite regions does not itself define the bounds of an level. Instead the composite regions’ aggregate child regions into a separate part of a level.
Leaf Regions
A leaf region regions defines an horizontal portion of a level and the locations of the leaf region is defined by location box components
Each location box component are displayed in the scene view as a colored box with white arrow handles. The white arrow handles can be dragged in order to manipulate a location box’s size.
Region Settings
There are 3 types of setting objects that can be attached a region.
Region Insertion Settings
The region insertion settings can be used to insert a specified area in a level. The level generator will attempt to insert the provided areas in the associated region. If the Is Required checkbox is selected the level generation process will fail if the specified amount of areas could not be inserted into the level.
Region Instantiation Settings
The region instantiation settings specifies what to rulesets to use for corridors and room in a leaf region. If the setting is added to a composite region the setting will be propagated downwards in the region tree unless another region instantiation setting supplied below.
If more than one ruleset is provided for the room or corridors one of them will be selected at random to instantiate the area.
Region Generation Settings
The region generation settings determines how rooms and corridors will be generation in a region.
In the same way as the instantiation settings the generation settings will propagate down unless another generation settings is supplied further down the hierarchy.
Static Areas
A static areas is actually a specified area statically placed within the level.
The Specified Area
A specified areas specifies and collection of cells and relations their neighbors. The cells of an area may be instantiated separately from an level and may contain assets that are not defined by a ruleset. An area may be set to be instantiated in a level or be made part of a level in a specified location.
A specified area may be created from the /Tools/Grate/Create Area menu.
Editing the cells
The area is specified through the area editing UI. The UI is composed of spheres and lines between them. A cell maybe selected and the state of that area may be altered.
Preview Mode
And Specified area my serve as an preview for an instantiator by enabling the preview mode. In this mode the area will be instantiated on each scene update in the editor.
Settings
The colors displayed in the rulests and Areas editing modes can be changed through the Edit/Preferences/Grate tab.
