Add battle grids to your scenes using Battle Grid components.

This document only focuses on adding battle grids to your scenes – if you want to learn more about ORK Framework’s grid battles, see this documenation for details.

Battle Grid Components #

The Battle Grid component is used to create and place a grid at a specific location in your scene. The battle grid must be set up in the scene before it can be used in a battle.

The component only defines the battle grid, to use it in an action battle, you still need to involve a Battle component. Learn more about setting up a battle in a scene in this documentation.

Battle Grid Generation #

The grid is generated based on the defined number of rows and columns. The position anchor defines which part of the grid (e.g. the middle center) will be placed at the position of the Battle Grid component.

Cell Settings #

Define the grid cell type that should be used for your regular cells, as well as an empty cell type for cells that couldn’t be placed (e.g. no ground).

You can optionally use a blocked cell type to use cells that can’t be moved on based on the ground’s slope.

Placing cells can also optionally use the slope of the ground for their rotation, to align them with the ground below them.

Raycast Settings #

Finding cell positions on the ground uses raycasting. Define the layer mask that’ll be used – you should only include layers your ground is placed on to not have other parts of the scene interfere with the grid cell creation.

You can optionally use separate layer masks for blocked and empty cells, i.e. if the raycast hits something on those layers, a cell will use the blocked or empty cell type you defined in the cell settings. This check uses a spherecast, i.e. you can define the cell size that’ll be checked for.

The raycast is fired downward from the position/height of the grid’s game object for each individual grid cell. You can use the source offset to add an additional offset to that position, e.g. firing from higher above. Either make sure your grid’s game object is high enough to not be below any ground in your scene, or use the source offset for that. If you end up with empty cells where there shouldn’t be some, try creating the grid from a higher position.

Raycasting for the grid generation (and grid battles in general) uses the horizontal plane you defined in Battles > Battle Grid Settings. This defaults to the Default horizontal plane, i.e. what’s defined in Game > Game Settings. The horizontal plane determines if this is a 2D (XY for top down, i.e. when Unity is in 2D mode) or a 3D (XZ) game by defining which is the horizontal axis. For raycasting, this decides which direction the raycast is fired to hit the ground.

This all might sound more complicated than it is – all you need to keep in mind is to use the correct layers in your layer mask. The horizontal plane is usually a one-time setup in the game settings for the entire framework.

Generating #

Click the Generate Grid button to generate a grid with your settings.

If you don’t like the grid, you can also remove it via the Remove Grid button, or just click Generate Grid again to create a new grid (destroying the old).

In case you want to keep your old grid but update the grid positions, enable Keep Old Cells before using Generate Grid. This’ll only update the cell positions based on raycasting, but keep the previous setup of all cells.

After your first grid generation, you’ll probably not see much – this is because you don’t see the individual cell prefabs yet.

Grid Setup #

The grid setup is used to manipulate the grid, e.g. paint new cell types, change connections or move cells around.

If you enable Auto Show (Scene Load), the grid will be automatically show it’s cells when the scene is loaded in-game. Otherwise you need to manually show the grid, e.g. in the battle start schematic using the Show Battle Grid node.

Editor Setup #

The editor setup lets you define when to show the grid in the editor.

If you want to see the grid and the cell prefabs at all times in the editor, enable Show Grid (Editor), Show Prefabs (Editor) and Show Unselected (Editor). If you only want to see it when the grid is selected, enable the first 2 (show grid/prefabs).

Manipulating the Grid #

The Mode in the grid setup settings of the Battle Grid component defines which mode you currently use to interact with the grid.

Select #

Allows selecting the individual cells. The setup of the selected cell can be changed (see below in the Battle Grid Cell Components for details).

Since the grid cells are game objects, you can use the usual ways of manipulating/changing the position, rotation or scale.

You can also select individual cells by simply selecting their game objects in the scene or scene hierarchy. The cells are child objects of the grid’s game object.

Move #

Allows moving the individual cells. It’s recommended to use this mainly for changing the height of the cell (i.e. Y-axis of the position).

Using this to swap cells or rearranging will result in unexpected behaviour in battles, since highlighting, ranges and movement will still rely on the row/column index of the cells.

Rotate #

Allows rotating the individual cells.

This can be used to further adjust a cell’s alignment with the ground.

Paint #

Allows painting cell types on the grid. You can paint a selected cell type directly on the cells in the scene view by holding down the left mouse button and dragging the mouse over the cells you want to paint on.

You can change the size of the used brush (measured in cell size).

Connections #

Allows changing the connections between cells. You can change connections by dragging a connection arrow holding down the left mouse button.

Drag the arrow on the cell itself to remove a connection, or drag it on another cell to connect it to that cell.

Connections are one-way, e.g. you can block moving into one direction, but allow moving the other way.

Additionally, connections don’t need to go to neighbouring cells. E.g. use this to connect far away cells to create things like teleports, shortcuts, etc.

You can also use this to create multi-layered grids.

Battle Grid Cells #

Each grid cell of a battle grid has a Battle Grid Cell component attached when it’s created.

You can use the component to change the cell type and other settings of the cell.

Deployment #

Optionally override the deployment settings of the cell’s grid cell type.

This has the same deployment settings available as the battle grid cell types – see this documentation for more details.

Spawn Rotation #

Optionally define the rotation for the spawned combatant.

In the scene, the spawn rotation is indicated with a small yellow arrow.

Blocked Settings #

Optionally override the blocked settings of the cell’s grid cell type.

E.g. set a cell to be blocked, but passable during movement.

Using Battle Grids #

Using a battle grid for a battle can be done in different ways.

Battle Components #

The Battle component that’s starting the battle determines if a Battle Grid component is used. Learn more about the Battle component and how to set up battles in the scene in this documentation.

• No Grid
  No Battle Grid component is used.
  I.e. the battle isn’t a grid battle.
• Nearest Grid
  Uses the nearest Battle Grid component.
  I.e. the game object with a Battle Grid component that’s closest to the battle.
• Defined Grid
  Uses a defined Battle Grid component.

By default, battles use the Nearest Grid. If you want a different setup in situations where you don’t use a Battle component (e.g. when using Combatant Spawner components), you can set up a Battle component for none-start use to define the settings of a battle.

Schematics #

Schematics can set the battle’s grid using the Set Battle Grid node.

If the battle grid isn’t using Auto Show to automatically spawn the cell prefabs when the scene loads, you need to use a Show Battle Grid node, e.g. in the battle start schematic. You also use this node to hide the grid again, e.g. in the battle end schematic.

Scripting #

You can also set the battle’s grid via scripting:

ORK.Battle.Grid = gridComponent;

The gridComponent is the Battle Grid component you want to use.

Or to remove the grid:

ORK.Battle.Grid = null;