Attention: Here be dragons

This is the latest (unstable) version of this documentation, which may document features not available in or compatible with released stable versions of Godot.

Checking the stable version of the documentation...

GridMap

继承： Node3D < Node < Object

基于 3D 图块地图的节点。

描述

GridMap 允许以交互的方式将网格放置在栅格上。它在编辑器和脚本中均可使用，可帮助创建游戏内的关卡编辑器。

GridMap 使用一个包含图块列表的 MeshLibrary。每个图块都是一个带有材质的网格以及可选的碰撞和导航形状。

GridMap 包含一组单元格。每个栅格单元格引用 MeshLibrary 中的一个图块。地图中的所有单元格都具有相同的大小。

在内部，GridMap 会根据卦限进行拆分，形成卦限的稀疏合集，能够进行高效的渲染和物理处理。每个卦限的大小是相同的，可以包含多个单元格。

注意：GridMap 不是从 VisualInstance3D 扩展的，因此不能基于 VisualInstance3D.layers 隐藏或剔除掩码。如果使灯光不影响第一层，则整个 GridMap 将不会被该灯光照亮。

教程

属性

bool

bake_navigation

false

bool

cell_center_x

true

bool

cell_center_y

true

bool

cell_center_z

true

int

cell_octant_size

8

float

cell_scale

1.0

Vector3

cell_size

Vector3(2, 2, 2)

int

collision_layer

1

int

collision_mask

1

float

collision_priority

1.0

MeshLibrary

mesh_library

PhysicsMaterial

physics_material

方法

void

clear()

void

clear_baked_meshes()

RID

get_bake_mesh_instance(idx: int)

Array

get_bake_meshes()

Basis

get_basis_with_orthogonal_index(index: int) const

int

get_cell_item(position: Vector3i) const

Basis

get_cell_item_basis(position: Vector3i) const

int

get_cell_item_orientation(position: Vector3i) const

bool

get_collision_layer_value(layer_number: int) const

bool

get_collision_mask_value(layer_number: int) const

Array

get_meshes() const

RID

get_navigation_map() const

int

get_orthogonal_index_from_basis(basis: Basis) const

Array[Vector3i]

get_used_cells() const

Array[Vector3i]

get_used_cells_by_item(item: int) const

Vector3i

local_to_map(local_position: Vector3) const

void

make_baked_meshes(gen_lightmap_uv: bool = false, lightmap_uv_texel_size: float = 0.1)

Vector3

map_to_local(map_position: Vector3i) const

void

resource_changed(resource: Resource)

void

set_cell_item(position: Vector3i, item: int, orientation: int = 0)

void

set_collision_layer_value(layer_number: int, value: bool)

void

set_collision_mask_value(layer_number: int, value: bool)

void

set_navigation_map(navigation_map: RID)

信号

cell_size_changed(cell_size: Vector3) 🔗

当 cell_size 改变时触发。

changed() 🔗

该 GridMap 的 MeshLibrary 发生改变时发出。

常量

INVALID_CELL_ITEM = -1 🔗

可以在 set_cell_item 中清除单元格（或在 get_cell_item 中重新代表一个空的单元格）的无效单元格。

属性说明

bool bake_navigation = false 🔗

  • void set_bake_navigation(value: bool)

  • bool is_baking_navigation()

如果为 true，则为每个使用带有导航网格的 mesh_library 项目的单元格，该 GridMap 将创建一个导航区域。创建的导航区域将使用分配给该 MeshLibrary 项目的导航层位掩码。

bool cell_center_x = true 🔗

  • void set_center_x(value: bool)

  • bool get_center_x()

如果为 true，则网格项以 X 轴为中心。

bool cell_center_y = true 🔗

  • void set_center_y(value: bool)

  • bool get_center_y()

如果为 true，则网格项以 Y 轴为中心。

bool cell_center_z = true 🔗

  • void set_center_z(value: bool)

  • bool get_center_z()

如果为 true，则网格项以 Z 轴为中心。

int cell_octant_size = 8 🔗

  • void set_octant_size(value: int)

  • int get_octant_size()

每个卦限的大小，单位为单元格的数量。适用于全部三个轴。

float cell_scale = 1.0 🔗

  • void set_cell_scale(value: float)

  • float get_cell_scale()

单元格项目的比例。

这不会影响网格单元本身的大小，只会影响其中的项目。这可用于使单元格项目与其邻居重叠。

Vector3 cell_size = Vector3(2, 2, 2) 🔗

网格单元的尺寸。

这并不影响网格的尺寸大小。见 cell_scale。

int collision_layer = 1 🔗

  • void set_collision_layer(value: int)

  • int get_collision_layer()

这个 GridMap 所处的物理层。

GridMap 作为静态体，意味着它们不会受到重力或是其他力的影响。它们只会受到其他与它们碰撞的物理体的影响。

int collision_mask = 1 🔗

  • void set_collision_mask(value: int)

  • int get_collision_mask()

此 GridMap 检测碰撞的物理层。更多信息请参阅文档《碰撞层与掩码》。

float collision_priority = 1.0 🔗

  • void set_collision_priority(value: float)

  • float get_collision_priority()

发生穿透时用于解决碰撞的优先级。优先级越高，对物体的穿透度就越低。例如，可以用来防止玩家突破关卡的边界。

MeshLibrary mesh_library 🔗

指定的 MeshLibrary。

PhysicsMaterial physics_material 🔗

覆盖整个 GridMap 的默认摩擦力和反弹物理属性。

方法说明

void clear() 🔗

清除所有单元格。

void clear_baked_meshes() 🔗

清除所有烘焙过的网格。见 make_baked_meshes。

RID get_bake_mesh_instance(idx: int) 🔗

返回索引为 idx 的烘焙网格的 RID。

Array get_bake_meshes() 🔗

返回当前 GridMap 中存在的所有烘焙网格的 ArrayMesh 和 Transform3D 引用的数组。

Basis get_basis_with_orthogonal_index(index: int) const 🔗

返回沿向量 (x,y,z) 的 24 种可能旋转中的一种，每个分量为 -1、0 或 1。有关详细信息，请参阅 Godot 源代码。

int get_cell_item(position: Vector3i) const 🔗

位于给定栅格坐标的 MeshLibrary 项目的索引。如果单元格为空，则将返回 INVALID_CELL_ITEM。

Basis get_cell_item_basis(position: Vector3i) const 🔗

返回为指定单元格提供方向的基。

int get_cell_item_orientation(position: Vector3i) const 🔗

给定栅格坐标处的单元格的方向。如果该单元格为空，则返回 -1。

bool get_collision_layer_value(layer_number: int) const 🔗

返回 collision_layer 中是否启用了指定的层，给定的 layer_number 应在 1 和 32 之间。

bool get_collision_mask_value(layer_number: int) const 🔗

返回 collision_mask 中是否启用了指定的层，给定的 layer_number 应在 1 和 32 之间。

Array get_meshes() const 🔗

返回对应于栅格中非空单元格的 Transform3D 和 Mesh 引用的数组。变换在局部空间中指定。

RID get_navigation_map() const 🔗

返回该 GridMap 节点用于其单元格烘焙导航网格的导航地图的 RID。

该函数始终返回在 GridMap 节点上设置的地图，而不是 NavigationServer 上的地图。如果直接使用 NavigationServer API 更改地图，则 GridMap 节点将不会感知到地图的更改。

int get_orthogonal_index_from_basis(basis: Basis) const 🔗

该函数考虑将旋转离散化为单位球体上的 24 个点，沿向量 (x,y,z) 放置，每个分量为 -1、0 或 1，并返回索引（在 0 到 23 的范围内 ) 最能代表物体方向的点。 有关详细信息，请参阅 Godot 源代码。

Array[Vector3i] get_used_cells() const 🔗

返回一个包含网格中非空单元格坐标的 Vector3 数组。

Array[Vector3i] get_used_cells_by_item(item: int) const 🔗

返回所有具有 item 中指定的项目索引的单元格的数组。

Vector3i local_to_map(local_position: Vector3) const 🔗

返回包含给定 local_position 的单元格的地图坐标。如果 local_position 在全局坐标中，请考虑在将其传递给该方法之前使用 Node3D.to_local。另请参阅 map_to_local。

void make_baked_meshes(gen_lightmap_uv: bool = false, lightmap_uv_texel_size: float = 0.1) 🔗

为指定的 MeshLibrary 中的所有网格烘焙光照贴图数据。

Vector3 map_to_local(map_position: Vector3i) const 🔗

返回栅格单元格在 GridMap 的局部坐标空间中的位置。要将返回值转换为全局坐标，请使用 Node3D.to_global。另请参阅 local_to_map。

void resource_changed(resource: Resource) 🔗

已弃用： Use Resource.changed instead.

这个方法什么也不做。

void set_cell_item(position: Vector3i, item: int, orientation: int = 0) 🔗

设置由其栅格坐标引用的单元格的网格索引。

诸如 INVALID_CELL_ITEM 之类的负的项目索引将清除该单元格。

可选地，可以传入该项目的方向。有关有效的方向值，请参阅 get_orthogonal_index_from_basis。

void set_collision_layer_value(layer_number: int, value: bool) 🔗

根据 value，启用或禁用 collision_layer 中指定的层，给定的 layer_number 应在 1 和 32 之间。

void set_collision_mask_value(layer_number: int, value: bool) 🔗

根据 value，启用或禁用 collision_mask 中指定的层，给定的 layer_number 应在 1 和 32 之间。

void set_navigation_map(navigation_map: RID) 🔗

设置该导航地图的 RID，该 GridMap 节点应该用于其单元格烘焙导航网格。