Introduction

Gridmaps are a tool for creating 3Dgame levels, similar to the wayTileMapworks in 2D. You start with a predefined collection of 3D meshes (aMeshLibrary) that can be placed on a grid,as if you were building a level with an unlimited amount of Lego blocks.

Collisions and navigation can also be added to the meshes, just like youwould do with the tiles of a tilemap.

Example project

To learn how GridMaps work, start by downloading the sample project:gridmap_starter.zip.

Unzip this project and add it to the Project Manager using the "Import"button. You may get a popup saying that it needs to be converted to a newer Godotversion, clickConvert project.godot.

Creating a MeshLibrary

To begin, you need aMeshLibrary, which is a collectionof individual meshes that can be used in the gridmap. Open the "mesh_library_source.tscn"scene to see an example of how to set up the mesh library.

As you can see, this scene has aNode3D node as its root, anda number ofMeshInstance3D node children.

If you don't need any physics in your scene, then you're done. However, in mostcases you'll want to assign collision bodies to the meshes.

Collisions

You can manually assign aStaticBody3D andCollisionShape3D to each mesh. Alternatively, you can use the "Mesh" menuto automatically create the collision body based on the mesh data.

Note that a "Convex" collision body will work better for simple meshes. For morecomplex shapes, select "Create Trimesh Static Body". Once each mesh hasa physics body and collision shape assigned, your mesh library is ready tobe used.

Materials

Only the materials from within the meshes are used when generating the meshlibrary. Materials set on the node will be ignored.

NavigationMeshes

Like all mesh instances, MeshLibrary items can be assigned aNavigationMeshresource, which can be created manually, or baked as described below.

To create the NavigationMesh from a MeshLibrary scene export, place aNavigationRegion3D child node below the main MeshInstance3D for the GridMapitem. Add a valid NavigationMesh resource to the NavigationRegion3D and some sourcegeometry nodes below and bake the NavigationMesh.

Nodes below the NavigationRegion3D are ignored for the MeshLibrary scene export, soadditional nodes can be added as source geometry just for baking the navmesh.

MeshLibrary format

To summarize the specific constraints of the MeshLibrary format, a MeshLibraryscene has a Node3D as the root node, and several child nodes which will becomeMeshLibrary items. Each child of the root node should:

• Be aMeshInstance3D, which will become the MeshLibrary item. Onlythis visual mesh will be exported.

• Have a material, in the mesh's material slot,not the MeshInstance3D'smaterial slots.

• Have up to oneStaticBody3D child, for collision. TheStaticBody3D should have one or moreCollisionShape3D children.

• Have up to oneNavigationRegion3D child, for navigation. TheNavigationRegion3D can have one or more additionalMeshInstance3Dchildren, which can be baked for navigation, but won't be exported as a visualmesh.

Only this specific format is recognized. Other node types placed as childrenwill not be recognized and exported. GridMap is not a general-purpose system forplacingnodes on a grid, but rather a specific, optimized system, designed toplacemeshes with collisions and navigation.

Exporting the MeshLibrary

To export the library, click onScene > Export As... > MeshLibrary..., and save itas a resource.

You can find an already exported MeshLibrary in the project named "MeshLibrary.tres".

Using GridMap

Create a new scene and add a GridMap node. Add the mesh library by draggingthe resource file from the FileSystem dock and dropping it in theMesh Libraryproperty in the Inspector.

Inspector properties

ThePhysics Material setting allows you to override the physics material forevery mesh in the NavigationMesh.

UnderCells, theSize property should be set to the size of your meshes. Youcan leave it at the default value for the demo. Uncheck theCenter Y property.

TheCollision options allow you to set the collision layer, collision mask, andpriority for the entire grid. For more information on how those work see thePhysics section.

UnderNavigation is the "Bake Navigation" option. If enabled it creates anavigation region for each cell that uses a mesh library item with a navigationmesh.

If you click on the MeshLibrary itself in the inspector you can adjust settings forindividual meshes, such as their navigation mesh, navigation layers, or if the meshcasts shadows.

GridMap panel

At the bottom of the editor is the GridMap panel, which should have openedautomatically when you added the GridMap node.

From left to right in the toolbar:

• Transform: Adds a gizmo to the scene that allows you to change therelative position and rotation of the gridmap in the scene.

• Selection: While active you can select an area in the viewport, click and dragto select more than one space on the grid.

• Erase: While active, click in the viewport and delete meshes.

• Paint: While active, click in the viewport and add whatever mesh is currentlyselected in the GridMap panel to the scene.

• Pick: While active, clicking on a gridmap mesh in the viewport will causeit to be selected in the GridMap panel.

• Fill: Fill the area that has been selected in the viewport with whatever meshis selected in the GridMap bottom panel.

• Move: Move whatever mesh or meshes are currently selected in the viewport.

• Duplicate: Create a copy of whatever the selected mesh or meshes in theGridMap are.

• Delete: Similar to erase, but for the entire selected area.

• Cursor Rotate X: While the paint tool is selected, this will rotate the meshthat will be painted on the X-axis. This will also rotate selected areas if theyare being moved.

• Cursor Rotate Y: While the paint tool is selected, this will rotate the meshthat will be painted on the Y-axis. This will also rotate selected areas if theyare being moved.

• Cursor Rotate Z: While the paint tool is selected, this will rotate the meshthat will be painted on the Z-axis. This will also rotate selected areas if theyare being moved.

• Change Grid Floor: Adjusts what floor is currently being worked on, can bechanged with the arrows or typing

• Filter Meshes: Used to search for a specific mesh in the bottom panel.

• Zoom: Controls the zoom level on meshes in the bottom panel.

• Layout toggles: These two buttons toggle between different layouts for meshesin the bottom panel.

• Tools dropdown: This button opens a dropdown menu with a few more options.

Clicking onSettings in that dropdown brings up a window that allows you tochange thePick Distance, which is the maximum distance at which tiles can be placedon a GridMap, relative to the camera position (in meters).

Using GridMap in code

SeeGridMap for details on the node's methods and member variables.