GFTileMapCache

API Reference / Standard / 类索引

• 路径：addons/gf/standard/foundation/math/gf_tile_map_cache.gd
• 模块：Standard
• 继承：Resource
• API：public
• 类别：资源定义 (resource_definition)
• 首次版本：3.17.0

通用格子数据快照与差分缓存。 用 Vector2i 管理格子字典数据，既可手动写入，也可从 TileMapLayer 采集基础 source/atlas/alternative/terrain 信息。它不规定字段语义，项目可扩展记录内容。

成员概览

类型	名称	签名
属性	cells	var cells: Dictionary = {}
方法	update_from_tile_map	func update_from_tile_map(layer: TileMapLayer, target_cells: Array[Vector2i] = []) -> void:
方法	apply_to_tile_map	func apply_to_tile_map( layer: TileMapLayer, origin: Vector2i = Vector2i.ZERO, options: Dictionary = {} ) -> Dictionary:
方法	extract_region	func extract_region(region: Rect2i, normalize_origin: bool = true) -> GFTileMapCache:
方法	translated	func translated(offset: Vector2i) -> GFTileMapCache:
方法	transformed	func transformed(transform: int, options: Dictionary = {}) -> GFTileMapCache:
方法	remapped_tiles	func remapped_tiles(remaps: Dictionary, options: Dictionary = {}) -> GFTileMapCache:
方法	transformed_and_remapped	func transformed_and_remapped(transform: int, remaps: Dictionary, options: Dictionary = {}) -> GFTileMapCache:
方法	get_used_rect	func get_used_rect() -> Rect2i:
方法	set_cell_data	func set_cell_data(cell: Vector2i, data: Dictionary) -> void:
方法	erase_cell	func erase_cell(cell: Vector2i) -> void:
方法	has_cell	func has_cell(cell: Vector2i) -> bool:
方法	get_cell_data	func get_cell_data(cell: Vector2i) -> Dictionary:
方法	get_value	func get_value(cell: Vector2i, key: StringName, default_value: Variant = null) -> Variant:
方法	clear	func clear() -> void:
方法	diff_cells	func diff_cells(other: GFTileMapCache, compare_key: StringName = &"") -> Array[Vector2i]:
方法	to_dict	func to_dict() -> Dictionary:
方法	from_dict	func from_dict(data: Dictionary) -> void:

属性

cells

• API：public

var cells: Dictionary = {}

格子数据，结构为 Vector2i -> Dictionary。

结构：

• cells: Dictionary mapping Vector2i cells to Dictionary cell records.

方法

update_from_tile_map

• API：public

func update_from_tile_map(layer: TileMapLayer, target_cells: Array[Vector2i] = []) -> void:

从 TileMapLayer 更新缓存。

参数：

名称	说明
layer	目标 TileMapLayer。
target_cells	要更新的格子；为空时采集 layer.get_used_cells()。

apply_to_tile_map

• API：public
• 首次版本：6.0.0

func apply_to_tile_map( layer: TileMapLayer, origin: Vector2i = Vector2i.ZERO, options: Dictionary = {} ) -> Dictionary:

将缓存写回 TileMapLayer。

参数：

名称	说明
layer	目标 TileMapLayer。
origin	写回偏移，缓存坐标会加上该偏移。
options	可选参数，支持 overwrite、erase_empty。

返回：写回报告。

结构：

• options: Dictionary with optional overwrite: bool and erase_empty: bool.
• return: Dictionary with ok, applied_count, skipped_count, erased_count, failed_count, applied_cells, skipped_cells, erased_cells, failed_cells, and error.

extract_region

• API：public
• 首次版本：6.0.0

func extract_region(region: Rect2i, normalize_origin: bool = true) -> GFTileMapCache:

提取区域片段。

参数：

名称	说明
region	要提取的区域。
normalize_origin	为 true 时把区域左上角归一到 Vector2i.ZERO。

返回：新缓存。

translated

• API：public
• 首次版本：6.0.0

func translated(offset: Vector2i) -> GFTileMapCache:

创建坐标平移后的缓存副本。

参数：

名称	说明
offset	坐标偏移。

返回：新缓存。

transformed

• API：public
• 首次版本：6.0.0

func transformed(transform: int, options: Dictionary = {}) -> GFTileMapCache:

创建坐标变换后的缓存副本。

参数：

名称	说明
transform	GFGridTransform2D.Transform 枚举值。
options	可选参数，支持 target_origin、normalize_origin。

返回：新缓存。

结构：

• options: Dictionary with optional target_origin: Vector2i and normalize_origin: bool.

remapped_tiles

• API：public
• 首次版本：6.0.0

func remapped_tiles(remaps: Dictionary, options: Dictionary = {}) -> GFTileMapCache:

创建 tile identity 重映射后的缓存副本。

参数：

名称	说明
remaps	重映射表。
options	可选参数，支持 preserve_unknown。

返回：新缓存。

结构：

• remaps: Dictionary mapping Vector4i(source_id, atlas_x, atlas_y, alternative_tile) or source_id int to Dictionary/Vector4i/int.
• options: Dictionary with optional preserve_unknown: bool.

transformed_and_remapped

• API：public
• 首次版本：6.0.0

func transformed_and_remapped(transform: int, remaps: Dictionary, options: Dictionary = {}) -> GFTileMapCache:

创建坐标变换并重映射 tile identity 后的缓存副本。

参数：

名称	说明
transform	GFGridTransform2D.Transform 枚举值。
remaps	重映射表。
options	可选参数，支持 target_origin、normalize_origin、preserve_unknown。

返回：新缓存。

结构：

• remaps: Dictionary mapping Vector4i(source_id, atlas_x, atlas_y, alternative_tile) or source_id int to Dictionary/Vector4i/int.
• options: Dictionary transform and remap options.

get_used_rect

• API：public
• 首次版本：6.0.0

func get_used_rect() -> Rect2i:

获取缓存覆盖区域。

返回：覆盖区域；缓存为空时返回空 Rect2i。

set_cell_data

• API：public

func set_cell_data(cell: Vector2i, data: Dictionary) -> void:

设置一个格子的字典数据。

参数：

名称	说明
cell	格坐标。
data	格子数据。

结构：

• data: Dictionary cell record copied into the cache.

erase_cell

• API：public

func erase_cell(cell: Vector2i) -> void:

移除一个格子。

参数：

名称	说明
cell	格坐标。

has_cell

• API：public

func has_cell(cell: Vector2i) -> bool:

检查格子是否存在。

参数：

名称	说明
cell	格坐标。

返回：存在时返回 true。

get_cell_data

• API：public

func get_cell_data(cell: Vector2i) -> Dictionary:

获取格子数据副本。

参数：

名称	说明
cell	格坐标。

返回：格子数据。

结构：

• return: Dictionary cell record copy.

get_value

• API：public

func get_value(cell: Vector2i, key: StringName, default_value: Variant = null) -> Variant:

获取格子字段值。

参数：

名称	说明
cell	格坐标。
key	字段名。
default_value	默认值。

返回：字段值。

结构：

• default_value: Variant fallback value returned when the field is missing.
• return: Variant field value or default_value.

clear

• API：public

func clear() -> void:

清空缓存。

diff_cells

• API：public

func diff_cells(other: GFTileMapCache, compare_key: StringName = &"") -> Array[Vector2i]:

和另一个缓存做差分。

参数：

名称	说明
other	另一个缓存。
compare_key	为空时比较完整字典；否则只比较指定字段。

返回：发生变化的格子列表。

to_dict

• API：public
• 首次版本：8.0.0

func to_dict() -> Dictionary:

序列化为 JSON 兼容字典。

返回：可保存的 JSON 兼容字典。

结构：

• return: Dictionary mapping string cell keys to JSON-compatible Dictionary cell records.

from_dict

• API：public
• 首次版本：8.0.0

func from_dict(data: Dictionary) -> void:

从字典恢复。

参数：

名称	说明
data	to_dict() 生成的数据，或旧版原始 Variant 记录。

结构：

• data: Dictionary mapping string cell keys to JSON-compatible Dictionary cell records.