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。奇数索引为 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 之间。

Array get_meshes() const 🔗

返回与栅格中非空单元格对应的数组，元素为 Transform3D 和 Mesh 引用。变换在局部空间中指定。奇数索引为 Transform3D，偶数索引为 Mesh，与前一个索引处的 Transform3D 对应。

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 的所有网格，会与 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 之间。

void set_navigation_map(navigation_map: RID) 🔗

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