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
基于 3D 图块地图的节点。
描述
GridMap，即栅格地图，允许以交互的方式将网格放置在栅格上。它在编辑器和脚本中均可使用，可以用来创建游戏内的关卡编辑器。
GridMap 使用了一个 MeshLibrary，包含一组图块。每个图块都是一个网格，带有材质以及可选的碰撞形状和导航形状。
GridMap 中包含了若干单元格。每个栅格单元格都引用着 MeshLibrary 中的一个图块。地图中所有单元格的大小都相同。
在内部，GridMap 会根据卦限进行拆分，形成卦限的稀疏合集，能够进行高效的渲染和物理处理。每个卦限的大小是相同的，可以包含多个单元格。
注意：GridMap 不是从 VisualInstance3D 扩展的，因此无法隐藏，也无法根据 VisualInstance3D.layers 进行掩码剔除。如果使灯光不影响第一层，则整个 GridMap 将不会被该灯光照亮。
教程
属性
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
方法
信号
cell_size_changed(cell_size: Vector3) 🔗
当 cell_size 改变时触发。
changed() 🔗
该 GridMap 的 MeshLibrary 发生改变时发出。
枚举
enum DebugVisibilityMode: 🔗
DebugVisibilityMode DEBUG_VISIBILITY_MODE_DEFAULT = 0
在编辑器中隐藏碰撞调试形状，并使用调试设置来决定它们在游戏内的可见性（例如 SceneTree.debug_collisions_hint 或 SceneTree.debug_navigation_hint）。
DebugVisibilityMode DEBUG_VISIBILITY_MODE_FORCE_SHOW = 1
始终显示碰撞调试形状。
DebugVisibilityMode DEBUG_VISIBILITY_MODE_FORCE_HIDE = 2
始终隐藏碰撞调试形状。
常量
INVALID_CELL_ITEM = -1 🔗
可以在 set_cell_item() 中清除单元格（或在 get_cell_item() 中重新代表一个空的单元格）的无效单元格。
属性说明
如果为 true，则为每个使用带有导航网格的 mesh_library 项目的单元格，该 GridMap 将创建一个导航区域。创建的导航区域将使用分配给该 MeshLibrary 项目的导航层位掩码。
如果为 true，则网格项以 X 轴为中心。
如果为 true，则网格项以 Y 轴为中心。
如果为 true，则网格项以 Z 轴为中心。
每个卦限的大小，单位为单元格的数量。适用于全部三个轴。
单元格项目的比例。
这不会影响网格单元本身的大小，只会影响其中的项目。这可用于使单元格项目与其邻居重叠。
Vector3 cell_size = Vector3(2, 2, 2) 🔗
网格单元的尺寸。
这并不影响网格的尺寸大小。见 cell_scale。
这个 GridMap 所处的物理层。
GridMap 作为静态体，意味着它们不会受到重力或是其他力的影响。它们只会受到其他与它们碰撞的物理体的影响。
此 GridMap 检测碰撞的物理层。更多信息请参阅文档《碰撞层与掩码》。
float collision_priority = 1.0 🔗
发生穿透时用于解决碰撞的优先级。优先级越高，对物体的穿透度就越低。例如，可以用来防止玩家突破关卡的边界。
DebugVisibilityMode collision_visibility_mode = 0 🔗
void set_collision_visibility_mode(value: DebugVisibilityMode)
DebugVisibilityMode get_collision_visibility_mode()
显示或隐藏 GridMap 的碰撞形状（collision shapes）。如果设置为 DEBUG_VISIBILITY_MODE_DEFAULT，则取决于“显示碰撞调试”（show collision debug）的全局设置。
MeshLibrary mesh_library 🔗
void set_mesh_library(value: MeshLibrary)
MeshLibrary get_mesh_library()
指定的 MeshLibrary。
PhysicsMaterial physics_material 🔗
void set_physics_material(value: PhysicsMaterial)
PhysicsMaterial get_physics_material()
覆盖整个 GridMap 的默认摩擦力和反弹物理属性。
方法说明
void clear() 🔗
清除所有单元格。
void clear_baked_meshes() 🔗
清除所有烘焙过的网格。见 make_baked_meshes()。
RID get_bake_mesh_instance(idx: int) 🔗
返回索引为 idx 的烘焙网格的 RID。
返回当前 GridMap 中存在的已烘焙网格数组，元素为 ArrayMesh 和 Transform3D。奇数索引为 ArrayMesh，偶数索引为 Transform3D，始终等于 Transform3D.IDENTITY。
这个方法依赖于 make_baked_meshes() 的输出，如果尚未调用，则会使用 gen_lightmap_uv 为 true、lightmap_uv_texel_size 为 0.1 进行调用。
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 之间。
返回与栅格中非空单元格对应的数组，元素为 Transform3D 和 Mesh 引用。变换在局部空间中指定。奇数索引为 Transform3D，偶数索引为 Mesh，与前一个索引处的 Transform3D 对应。
返回该 GridMap 节点用于其单元格烘焙导航网格的导航地图的 RID。
该函数始终返回在 GridMap 节点上设置的地图，而不是 NavigationServer 上的地图。如果直接使用 NavigationServer API 更改地图，则 GridMap 节点将不会感知到地图的更改。
Vector3i get_octant_coords_from_cell_coords(cell_coords: Vector3i) const 🔗
返回 cell_coords（单元格坐标）所在的八分体（octant）的 Vector3i（三维整数向量）坐标。
Array[Vector3i] get_octants_in_bounds(bounds: AABB) const 🔗
返回一个包含 Vector3i 卦限坐标的数组，这些卦限位于给定的 bounds 范围内，包括那些未被使用的单元格所在的卦限。
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 中指定的项目索引的单元格的数组。
Array[Vector3i] get_used_cells_in_octant(octant_coords: Vector3i) const 🔗
返回一个包含 Vector3i 的数组，其中包含位于 octant_coords（八分体坐标）处的八分体（octant）内所有非空单元格的坐标。
Array[Vector3i] get_used_cells_in_octant_by_item(octant_coords: Vector3i, item: int) const 🔗
返回一个包含 Vector3i 的数组， 表示位于 octant_coords 指定卦限内、且使用了指定单元格 item 的单元格坐标。
Array[Vector3i] get_used_octants() const 🔗
返回一个包含 Vector3i 的数组，其中包含网格地图（grid map）中所有非空八分体（octant）的坐标。
Array[Vector3i] get_used_octants_by_item(item: int) const 🔗
返回一个包含 Vector3i 的数组，其中包含网格地图（grid map）中所有使用了指定 item（物品）的八分体（octant）的坐标。
Array[Vector3i] get_used_octants_in_bounds(bounds: AABB) const 🔗
返回一个包含 Vector3i 的数组，其中包含在局部 bounds（边界范围）内、所有非空八分体（octant）的坐标。
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 的所有网格，会与 LightmapGI 一起使用。如果 gen_lightmap_uv 为 true，则将为当前在 GridMap 中使用的每个网格生成 UV2 数据。否则，只有已经存在 UV2 数据的网格才能使用烘焙光照贴图。在生成 UV2 时，lightmap_uv_texel_size 控制的是光照贴图的纹素密度，值越低得到的光照贴图越详细。如果 gen_lightmap_uv 为 false，则会忽略 lightmap_uv_texel_size。另见 get_bake_meshes()，依赖本方法的输出。
注意：调用该方法并不会对光照贴图进行烘焙，因为光照贴图是使用 LightmapGI 节点烘焙的。
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 之间。
设置导航地图 RID，用于 GridMap 节点单元格所烘焙的导航网格。