InteractiveGrid3D

Note

GitHub repository: https://github.com/antoinecharruel/interactive_grid_gdextension.

Description

InteractiveGrid is a Godot GDExtension that allows player interaction with a 3D grid, including cell selection, pathfinding, and hover highlights.

Select individual cells.
Detect obstacles.
Align cells with the floor.
Calculate paths from a global position to selected cells using AStar2D.
Choose movement type: 4 directions, 6 directions, 8 directions.
Customize the grid from the editor: grid size, cell size, mesh, colors, and shaders.
High performance using MultiMeshInstance3D for efficient rendering of multiple cells.

Properties

Mesh	cell_mesh
Vector3	cell_rotation	`Vector3(0, 0 ,0)`
Shape3D	cell_shape
Vector3	cell_shape_offset	`Vector3(0, 0 ,0)`
Vector2	cell_size	`Vector2(1, 1)`
bool	collision_floor_enabled	`true`
int	collision_floor_mask	`1`
bool	collision_obstacles_enabled	`true`
int	collision_obstacles_mask	`1`
Color	color_accessible	`Color(1, 1, 1, 1)`
Color	color_hovered	`Color(1, 1, 1, 1)`
Color	color_path	`Color(1, 1, 1, 1)`
Color	color_selected	`Color(1, 1, 1, 1)`
Color	color_unaccessible	`Color(1, 1, 1, 1)`
Color	color_unreachable	`Color(1, 1, 1, 1)`
int	columns	`9`
Array	custom_cells_data	`[]`
bool	debug_execution_time_enabled	`false`
bool	debug_logs_enabled	`false`
Layout	layout	`0`
Material	material_override
Movement	movement	`0`
int	rows	`9`

Methods

void	add_custom_cell_data
void	center
void	clear_all_custom_cell_data
void	clear_custom_cell_data
void	compute_unreachable_cells
Color	get_cell_color
Vector3	get_cell_global_position
Transform3D	get_cell_global_transform
int	get_cell_index_from_global_position
Vector3	get_cell_position
Transform3D	get_cell_transform
int	get_latest_selected
Array	get_neighbors
PackedInt64Array	get_path
Array	get_selected_cells
int	get_size
bool	has_custom_cell_data
void	hide_distant_cells
void	highlight_on_hover
void	highlight_path
bool	is_cell_accessible
bool	is_cell_hovered
bool	is_cell_reachable
bool	is_cell_selected
bool	is_cell_visible
bool	is_created
bool	is_hover_enabled
void	reset_cells_state
void	select_cell
void	set_cell_accessible
void	set_cell_color
void	set_cell_reachable
void	set_hover_enabled
void	update_custom_data

Enumerations

enum Layout

LAYOUT_SQUARE = 0
LAYOUT_HEXAGONAL = 1

enum Movement

MOVEMENT_FOUR_DIRECTIONS = 0
MOVEMENT_SIX_DIRECTIONS = 1
MOVEMENT_EIGHT_DIRECTIONS = 2

Property Descriptions

Mesh cell_mesh

void set_cell_mesh (value: Mesh)
Mesh get_cell_mesh ()

The Mesh resource for the grid.

Vector3 cell_rotation

void set_cell_rotation (value: Vector3)
Mesh get_cell_rotation ()

Rotation of the cell in 3D space.

Shape3D cell_shape

void set_cell_shape (value)
Shape3D get_cell_shape ()

The Shape3D resource for the cell, used for obstacle detection and for detecting objects that have a collision shape on the same layer as a CustomCellData.

Vector3 cell_shape_offset = Vector3(0, 0, 0)

void set_cell_shape_offset (value: Vector3)
Vector3 get_cell_shape_offset ()

Offset of the cell shape relative to the cell origin.

Vector2 cell_size = Vector2(1, 1)

void set_cell_size (value: Vector2)
Vector2 get_cell_size ()

Size of each grid cell.

Bool collision_floor_enabled = true

void set_floor_collision_enabled (value: bool)
bool get_floor_collision_enabled ()

Enables or disables floor collision detection used to align the grid.

int collision_floor_mask = 1

void set_floor_collision_mask (value: int)
int get_floor_collision_mask ()

Collision masks used to detect the floor.

Bool collision_obstacles_enabled = true

void set_obstacles_collision_mask (value: bool)
bool get_obstacles_collision_mask ()

Enables or disables collision detection between the grid and obstacles.

int collision_obstacles_mask = 1

void set_obstacles_collision_mask (value: int)
int get_obstacles_collision_mask ()

Collision masks used to detect obstacles on the grid.

Color color_accessible = Color(1, 1, 1, 1)

void set_accessible_color (value: Color)
int get_accessible_color ()

Color used to indicate that the cell is accessible.

Color color_hovered = Color(1, 1, 1, 1)

void set_hovered_color (value: Color)
int get_hovered_color ()

Color used when the cell is hovered over.

Color color_path = Color(1, 1, 1, 1)

void set_path_color (value: Color)
int get_path_color ()

Color used to display the path.

Color color_selected = Color(1, 1, 1, 1)

void set_selected_color (value: Color)
int get_selected_color ()

Color used to indicate the currently selected cell.

Color color_unaccessible = Color(1, 1, 1, 1)

void set_unaccessible_color (value: Color)
Color get_unaccessible_color ()

Color used to indicate that the cell is not accessible or blocked.

Color color_unreachable = Color(1, 1, 1, 1)

void set_unreachable_color (value: Color)
int get_unreachable_color ()

Color used to indicate that the cell is not reachable.

int cell_columns = 9

void set_cell_columns (value: int)
int get_cell_columns ()

Number of columns in the grid.

Array custom_cells_data = []

void set_custom_cells_data (value: Array)
Array get_custom_cells_data ()

List of CustomCellData used to add additional states, behaviors, or visual effects to specific grid cells. Each CustomCellData can be applied via a collision mask or through GDScript, and is accessible in shader scripts via the INSTANCE_CUSTOM alpha channel.

bool debug_execution_time_enabled = false

void set_execution_time_enabled (value: bool)
bool is_execution_time_enabled ()

Enable printing execution time of grid operations for debugging.

bool debug_logs_enabled = false

void set_logs_enabled (value: bool)
bool get_logs_enabled ()

Enable printing debug logs related to grid operations.

Layout layout = 0

void set_layout (value: Layout)
Layout get_layout ()

Grid layout type (LAYOUT_SQUARE, LAYOUT_HEXAGONAL).

Material material_override

void set_material_override (value: Material)
Material get_material_override ()

Optional material override for the grid. Assign a custom ShaderMaterial to visually modify grid cells.

Movement movement = 0

void set_movement (value: Movement)
Movement get_movement ()

Type of movement on the grid for pathfinding: 4, 6, or 8 directions.

int rows = 9

void set_rows (value: int)
int get_rows ()

Number of rows in the grid.

Method Descriptions

void add_custom_cell_data (cell_index: int, custom_data_name: String) 🔗

Adds custom data to a specific cell.

Applies the associated layer mask to the cell.

If a custom color is defined, it is applied to the cell.

var neighbors: Array = interactive_grid_3d.get_neighbors(pawn_current_cell_index)

for neighbor_index in neighbors:
   interactive_grid_3d.add_custom_cell_data(neighbor_index, "CFL_NEIGHBORS")

interactive_grid_3d.add_custom_cell_data(pawn_current_cell_index, "CFL_PLAYER")

interactive_grid_3d.update_custom_data()

Note

You must first define a CustomCellData resource in the editor inside the Custom Cells Data array property.

This allows the layer mask to be used inside a GDShader for visual effects or cell-based rendering logic.

// interractive_grid.gdshader

shader_type spatial;
render_mode unshaded, cull_disabled, depth_draw_opaque;

varying vec4 instance_c;
varying vec4 instance_c_default;
varying float alpha;

// Default cell flags:
const int CFL_ACCESSIBLE = 1 << 0;
const int CFL_REACHABLE = 1 << 1;
const int CFL_IN_VOID = 1 << 2;
const int CFL_HOVERED = 1 << 3;
const int CFL_SELECTED  = 1 << 4;
const int CFL_PATH = 1 << 5;
const int CFL_VISIBLE = 1 << 6;

// Custom cell data:
const int CFL_PLAYER = 1 << 7;
const int CFL_NEIGHBORS = 1 << 9;
const int CFL_TRAP = 1 << 10;
const int CFL_PULSE = 1 << 8;

vec3 pulse_color(vec3 base_color, float speed, float min_val, float max_val) {
   float center = (min_val + max_val) * 0.5;
   float range  = (max_val - min_val) * 0.5;
   return base_color * (sin(TIME * speed) * range + center);
}

void vertex() {
   instance_c = INSTANCE_CUSTOM;
   int cell_flag = int(instance_c.a);
   alpha = 0.5;

   if ((cell_flag & CFL_ACCESSIBLE) == 0) {
      alpha = 0.20;
   }

   if ((cell_flag & CFL_NEIGHBORS) != 0
      && (cell_flag & CFL_PATH) == 0
      && (cell_flag & CFL_TRAP) == 0)
      {
         if ((cell_flag & CFL_ACCESSIBLE) != 0) {
            alpha = 0.40;
            instance_c.r = 0.2;
            instance_c.g = 0.5;
            instance_c.b = 1.0;
         }
      }

   if ((cell_flag & CFL_PATH) != 0) {
      VERTEX.y += sin(TIME * 4.0 + VERTEX.x * 2.0) * 0.2;
   }

   if ((cell_flag & CFL_HOVERED) != 0) {
      VERTEX.y += sin(TIME * 4.0) * 0.2;
   }

   if ((cell_flag & CFL_TRAP) != 0) {
      VERTEX.y += sin(TIME * 4.0 + VERTEX.x * 2.0) * 0.2;
   }

   if ((cell_flag & CFL_PULSE) != 0) {
      instance_c.rgb = pulse_color(vec3(instance_c.rgb), 4.0, 0.3, 0.8);
   }

   if ((cell_flag & CFL_VISIBLE) == 0) {
      alpha = 0.0; // invisible
   }

   if ((cell_flag & CFL_REACHABLE) == 0) {
      alpha = 0.0; // invisible
   }

   if ((cell_flag & CFL_IN_VOID) != 0) {
      alpha = 0.0; // invisible
   }
}

void fragment() {
   if (alpha == 0.0) {
      discard;
   }
   ALBEDO = instance_c.rgb;
   EMISSION = instance_c.rgb;
   ALPHA = alpha;
}

void center (center_position: Vector3) 🔗

Centers the grid around the given global position and rebuilds its layout.

Note

This operation repositions all cells, realigns them with the environment, rescans obstacles and custom data, and refreshes A* navigation.

void clear_all_custom_cell_data (cell_index: int) 🔗

Resets the cell's custom_flags and removes any custom_color.

void clear_custom_cell_data (cell_index: int, custom_data_name: String, clear_custom_color: bool) 🔗

Resets the custom data of a given cell.

void compute_unreachable_cells (start_cell_index: int) 🔗

Iterates over all grid cells and marks as unreachable those cells that cannot be reached from the specified start_cell.

Updates the visual representation by applying unreachable_color to the cells.

Note

Unreachable cells are not automatically marked as unaccessible, allowing gameplay features such as teleportation.

Color get_cell_color (cell_index: int) 🔗

Returns the color of the cell identified by index.

Vector3 get_cell_global_position (cell_index: int) const 🔗

Returns the global_position of the cell identified by index.

Transform3D get_cell_global_transform (cell_index: int) const 🔗

Returns the global Transform3D of the cell identified by index.

int get_cell_index_from_global_position (global_position: Vector3) const 🔗

Returns the index of the grid cell that is closest to the supplied world position.

Vector3 get_cell_position (cell_index: int) const 🔗

Returns the local position of the cell identified by index.

Transform3D get_cell_transform (cell_index: int) const 🔗

Returns the local Transform3D of the cell identified by index.

int get_latest_selected () const 🔗

Returns the most recently selected_cell.

Array get_neighbors (cell_index: int) const 🔗

Returns the indices of neighboring cells for the specified grid cell.

PackedInt64Array get_path (cell_index: int) const 🔗

Computes a path between two cells on the grid using A* pathfinding.

Array get_selected_cells () 🔗

Returns an array of all cells currently marked as selected.

int get_size () const 🔗

Returns the total number of cells in the grid.

bool has_custom_cell_data (cell_index: int, custom_data_name: String) const 🔗

Checks if a specific cell has the given CustomCellData applied. Returns true if the cell's flags include the full layer mask of the specified CustomCellData, otherwise returns false.

void hide_distant_cells (start_cell_index: int, distance: float) const 🔗

Iterates over all grid cells and hides those located farther than the specified distance from the start_cell. Marks them as unaccessible.

void highlight_on_hover (global_position: Vector3) 🔗

Updates the hover highlight state based on the specified global_position. Identifies the corresponding cell, clears any previous hover, and applies the hover color unless the cell is already selected.

void highlight_path (path: PackedInt64Array) 🔗

Highlights a given path on the grid by changing the color of each cell along the path to the predefined path color.

bool is_cell_accessible (cell_index: int) const 🔗

Returns true if the cell at the specified index is currently marked as accessible.

bool is_cell_hovered (cell_index: int) const 🔗

Returns true if the cell at the specified index is currently marked as hovered.

bool is_cell_reachable (cell_index: int) const 🔗

Returns true if the cell at the specified index is currently marked as unreachable.

bool is_cell_selected (cell_index: int) const 🔗

Returns true if the cell at the specified index is currently marked as selected.

bool is_cell_visible (cell_index: int) const 🔗

Returns true if the cell at the specified index is currently marked as visible.

bool is_created (cell_index: int) const 🔗

Checks if the grid has been created.

bool is_hover_enabled (cell_index: int) const 🔗

Checks whether hover functionality is currently disabled.

void reset_cells_state () 🔗

Clears all CustomCellData, resets cell_flags.

void select_cell (cell_index: int) 🔗

Selects a grid cell based on a cell_index.

void set_cell_accessible (cell_index: int, is_accessible: bool) 🔗

Sets whether a specific cell is accessible or not.

void set_cell_color (cell_index: int, color: Color) 🔗

Sets the color of a specific cell.

void set_cell_reachable (cell_index: int, set_cell_reachable: bool) 🔗

Sets whether a given grid cell is unreachable.

void set_hover_enabled (enabled: bool) 🔗

Enables or disables hover functionality.

void update_custom_data () 🔗

Refreshes custom_cell_flags, colors, and A* configuration based on the current CellCustomData.