TileMapLayer

Hereda: Node2D < CanvasItem < Node < Object

Nodo para mapas basados en tiles 2D.

Descripción

Nodo para mapas 2D basados en tiles. Un TileMapLayer utiliza un TileSet que contiene una lista de tiles que se utilizan para crear mapas basados en cuadrículas. A diferencia del nodo TileMap, que está obsoleto, TileMapLayer tiene solo una capa de tiles. Puedes usar varios TileMapLayer para lograr el mismo resultado que un nodo TileMap.

Por razones de rendimiento, todas las actualizaciones de TileMap se procesan por lotes al final de un fotograma. En particular, esto significa que los tiles de escena de un TileSetScenesCollectionSource se inicializan después de su padre. Esto solo se pone en cola cuando está dentro del árbol de escena.

Para forzar una actualización antes, llama a update_internals().

Nota: Por razones de rendimiento y compatibilidad, las coordenadas serializadas por TileMapLayer están limitadas a enteros firmados de 16 bits, es decir, el rango para las coordenadas X e Y es de -32768 a 32767. Al guardar datos de tiles, los tiles fuera de este rango se ajustan.

Tutoriales

Propiedades

bool	collision_enabled	`true`
DebugVisibilityMode	collision_visibility_mode	`0`
bool	enabled	`true`
bool	navigation_enabled	`true`
DebugVisibilityMode	navigation_visibility_mode	`0`
bool	occlusion_enabled	`true`
int	physics_quadrant_size	`16`
int	rendering_quadrant_size	`16`
PackedByteArray	tile_map_data	`PackedByteArray()`
TileSet	tile_set
bool	use_kinematic_bodies	`false`
bool	x_draw_order_reversed	`false`
int	y_sort_origin	`0`

Métodos

void	_tile_data_runtime_update(coords: Vector2i, tile_data: TileData) virtual
void	_update_cells(coords: Array[Vector2i], forced_cleanup: bool) virtual
bool	_use_tile_data_runtime_update(coords: Vector2i) virtual
void	clear()
void	erase_cell(coords: Vector2i)
void	fix_invalid_tiles()
int	get_cell_alternative_tile(coords: Vector2i) const
Vector2i	get_cell_atlas_coords(coords: Vector2i) const
int	get_cell_source_id(coords: Vector2i) const
TileData	get_cell_tile_data(coords: Vector2i) const
Vector2i	get_coords_for_body_rid(body: RID) const
RID	get_navigation_map() const
Vector2i	get_neighbor_cell(coords: Vector2i, neighbor: CellNeighbor) const
TileMapPattern	get_pattern(coords_array: Array[Vector2i])
Array[Vector2i]	get_surrounding_cells(coords: Vector2i)
Array[Vector2i]	get_used_cells() const
Array[Vector2i]	get_used_cells_by_id(source_id: int = -1, atlas_coords: Vector2i = Vector2i(-1, -1), alternative_tile: int = -1) const
Rect2i	get_used_rect() const
bool	has_body_rid(body: RID) const
bool	is_cell_flipped_h(coords: Vector2i) const
bool	is_cell_flipped_v(coords: Vector2i) const
bool	is_cell_transposed(coords: Vector2i) const
Vector2i	local_to_map(local_position: Vector2) const
Vector2i	map_pattern(position_in_tilemap: Vector2i, coords_in_pattern: Vector2i, pattern: TileMapPattern)
Vector2	map_to_local(map_position: Vector2i) const
void	notify_runtime_tile_data_update()
void	set_cell(coords: Vector2i, source_id: int = -1, atlas_coords: Vector2i = Vector2i(-1, -1), alternative_tile: int = 0)
void	set_cells_terrain_connect(cells: Array[Vector2i], terrain_set: int, terrain: int, ignore_empty_terrains: bool = true)
void	set_cells_terrain_path(path: Array[Vector2i], terrain_set: int, terrain: int, ignore_empty_terrains: bool = true)
void	set_navigation_map(map: RID)
void	set_pattern(position: Vector2i, pattern: TileMapPattern)
void	update_internals()

Señales

changed() 🔗

Se emite cuando cambian las propiedades de este TileMapLayer. Esto incluye celdas modificadas, propiedades o cambios realizados en su TileSet asignado.

Nota: Esta señal puede emitirse muy a menudo al modificar por lotes un TileMapLayer. Evita ejecutar procesamiento complejo en una función conectada y considera retrasarlo hasta el final del fotograma (es decir, llamando a Object.call_deferred()).

Enumeraciones

enum DebugVisibilityMode: 🔗

DebugVisibilityMode DEBUG_VISIBILITY_MODE_DEFAULT = 0

Oculta las formas de depuración de colisiones o navegación en el editor y utiliza la configuración de depuración para determinar su visibilidad en el juego (es decir, SceneTree.debug_collisions_hint o SceneTree.debug_navigation_hint).

DebugVisibilityMode DEBUG_VISIBILITY_MODE_FORCE_HIDE = 2

Siempre oculta las formas de depuración de colisiones o navegación.

DebugVisibilityMode DEBUG_VISIBILITY_MODE_FORCE_SHOW = 1

Siempre muestra las formas de depuración de colisiones o navegación.

Descripciones de Propiedades

bool collision_enabled = true 🔗

void set_collision_enabled(value: bool)
bool is_collision_enabled()

Activa o desactiva las colisiones.

DebugVisibilityMode collision_visibility_mode = 0 🔗

void set_collision_visibility_mode(value: DebugVisibilityMode)
DebugVisibilityMode get_collision_visibility_mode()

Muestra u oculta las formas de colisión del TileMapLayer. Si se establece en DEBUG_VISIBILITY_MODE_DEFAULT, esto depende de la configuración de depuración de visualización de colisiones.

bool enabled = true 🔗

void set_enabled(value: bool)
bool is_enabled()

Si es false, deshabilita este TileMapLayer por completo (renderizado, colisión, navegación, tiles de escena, etc.).

bool navigation_enabled = true 🔗

void set_navigation_enabled(value: bool)
bool is_navigation_enabled()

Si es true, las regiones de navegación están habilitadas.

DebugVisibilityMode navigation_visibility_mode = 0 🔗

void set_navigation_visibility_mode(value: DebugVisibilityMode)
DebugVisibilityMode get_navigation_visibility_mode()

Muestra u oculta las mallas de navegación del TileMapLayer. Si se establece en DEBUG_VISIBILITY_MODE_DEFAULT, esto depende de la configuración de depuración de visualización de navegación.

bool occlusion_enabled = true 🔗

void set_occlusion_enabled(value: bool)
bool is_occlusion_enabled()

Habilitar o deshabilitar la oclusión de luz.

int physics_quadrant_size = 16 🔗

void set_physics_quadrant_size(value: int)
int get_physics_quadrant_size()

The TileMapLayer's physics quadrant size. Within a physics quadrant, cells with similar physics properties are grouped together and their collision shapes get merged. physics_quadrant_size defines the length of a square's side, in the map's coordinate system, that forms the quadrant. Thus, the default quadrant size groups together 16 * 16 = 256 tiles.

Note: As quadrants are created according to the map's coordinate system, the quadrant's "square shape" might not look like square in the TileMapLayer's local coordinate system.

Note: This impacts the value returned by get_coords_for_body_rid(). Higher values will make that function less precise. To get the exact cell coordinates, you need to set physics_quadrant_size to 1, which disables physics chunking.

int rendering_quadrant_size = 16 🔗

void set_rendering_quadrant_size(value: int)
int get_rendering_quadrant_size()

El tamaño del cuadrante de renderizado del TileMapLayer. Un cuadrante es un grupo de tiles que se dibujan juntos en un solo elemento de lienzo, con fines de optimización. rendering_quadrant_size define la longitud del lado de un cuadrado, en el sistema de coordenadas del mapa, que forma el cuadrante. Por lo tanto, el tamaño de cuadrante predeterminado agrupa juntos 16 * 16 = 256 tiles.

El tamaño del cuadrante no se aplica en un TileMapLayer ordenado por Y, ya que los tiles se agrupan por posición Y en ese caso.

Nota: Como los cuadrantes se crean de acuerdo con el sistema de coordenadas del mapa, la "forma cuadrada" del cuadrante podría no parecerse a un cuadrado en el sistema de coordenadas local de TileMapLayer.

PackedByteArray tile_map_data = PackedByteArray() 🔗

void set_tile_map_data_from_array(value: PackedByteArray)
PackedByteArray get_tile_map_data_as_array()

Los datos del mapa de tiles sin procesar como un array de bytes.

Note: The returned array is copied and any changes to it will not update the original property value. See PackedByteArray for more details.

TileSet tile_set 🔗

void set_tile_set(value: TileSet)
TileSet get_tile_set()

El TileSet utilizado por esta capa. Las texturas, colisiones y el comportamiento adicional de todos los tiles disponibles se almacenan aquí.

bool use_kinematic_bodies = false 🔗

void set_use_kinematic_bodies(value: bool)
bool is_using_kinematic_bodies()

Si es true, las formas de colisión de este TileMapLayer se instanciarán como cuerpos cinemáticos. Esto puede ser necesario para mover nodos TileMapLayer (es decir, plataformas móviles).

bool x_draw_order_reversed = false 🔗

void set_x_draw_order_reversed(value: bool)
bool is_x_draw_order_reversed()

Si CanvasItem.y_sort_enabled está habilitado, establecer esto en true invertirá el orden en que se dibujan los tiles en el eje X.

int y_sort_origin = 0 🔗

void set_y_sort_origin(value: int)
int get_y_sort_origin()

Este valor de origen de ordenación Y se agrega al valor de origen de ordenación Y de cada tile. Esto permite, por ejemplo, simular un nivel de altura diferente. Esto puede ser útil para juegos de vista superior.

Descripciones de Métodos

void _tile_data_runtime_update(coords: Vector2i, tile_data: TileData) virtual 🔗

Se llama con un objeto TileData que está a punto de ser utilizado internamente por el TileMapLayer, lo que permite su modificación en tiempo de ejecución.

Este método solo se llama si _use_tile_data_runtime_update() está implementado y devuelve true para el coords del tile dado.

Advertencia: Los subrecursos del objeto tile_data son los mismos que los del TileSet. Modificarlos podría afectar a todo el TileSet. En su lugar, asegúrate de duplicar esos recursos.

Nota: Si las propiedades del objeto tile_data deben cambiar con el tiempo, usa notify_runtime_tile_data_update() para notificar al TileMapLayer que necesita una actualización.

void _update_cells(coords: Array[Vector2i], forced_cleanup: bool) virtual 🔗

Se llama cuando las celdas de este TileMapLayer necesitan una actualización interna. Esta actualización puede deberse a que las celdas individuales se están modificando o a un cambio en el tile_set (lo que hace que todas las celdas se pongan en cola para una actualización). La primera llamada a esta función es siempre para inicializar todas las celdas del TileMapLayer. coords contiene las coordenadas de todas las celdas modificadas, aproximadamente en el orden en que fueron modificadas. forced_cleanup es true cuando los internos del TileMapLayer deben limpiarse por completo. Este es el caso cuando:

La capa está deshabilitada;
La capa no es visible;
tile_set está establecido en null;
El nodo se elimina del árbol;
El nodo se libera.

Ten en cuenta que cualquier actualización interna que ocurra mientras se verifica una de estas condiciones se considera una "limpieza". Véase también update_internals().

Advertencia: La implementación de este método puede degradar el rendimiento del TileMapLayer.

bool _use_tile_data_runtime_update(coords: Vector2i) virtual 🔗

Debería devolver true si el tile en las coordenadas coords requiere una actualización en tiempo de ejecución.

Advertencia: Asegúrate de que esta función solo devuelva true cuando sea necesario. Cualquier tile procesado en tiempo de ejecución sin necesidad de ello implicará una penalización significativa en el rendimiento.

Nota: Si el resultado de esta función debe cambiar, usa notify_runtime_tile_data_update() para notificar al TileMapLayer que necesita una actualización.

void clear() 🔗

Limpia todas las celdas.

void erase_cell(coords: Vector2i) 🔗

Borra la celda en las coordenadas coords.

void fix_invalid_tiles() 🔗

Borra las celdas que contienen tiles que no existen en el tile_set.

int get_cell_alternative_tile(coords: Vector2i) const 🔗

Devuelve el ID alternativo del tile de la celda en las coordenadas coords.

Vector2i get_cell_atlas_coords(coords: Vector2i) const 🔗

Devuelve el ID de las coordenadas del atlas del tile de la celda en las coordenadas coords. Devuelve Vector2i(-1, -1) si la celda no existe.

int get_cell_source_id(coords: Vector2i) const 🔗

Devuelve el ID de origen del tile de la celda en las coordenadas coords. Devuelve -1 si la celda no existe.

TileData get_cell_tile_data(coords: Vector2i) const 🔗

Devuelve el objeto TileData asociado con la celda dada, o null si la celda no existe o no es un TileSetAtlasSource.

func get_clicked_tile_power():
    var celda_pulsada = tile_map_layer.local_to_map(tile_map_layer.get_local_mouse_position())
    var datos = tile_map_layer.get_cell_tile_data(celda_pulsada)
    if datos:
        return datos.get_custom_data("power")
    else:
        return 0

Vector2i get_coords_for_body_rid(body: RID) const 🔗

Returns the coordinates of the physics quadrant (see physics_quadrant_size) for given physics body RID. Such an RID can be retrieved from KinematicCollision2D.get_collider_rid(), when colliding with a tile.

Note: Higher values of physics_quadrant_size will make this function less precise. To get the exact cell coordinates, you need to set physics_quadrant_size to 1, which disables physics chunking.

Devuelve el RID de la navegación NavigationServer2D utilizada por este TileMapLayer.

Por defecto, esto devuelve el mapa de navegación World2D predeterminado, a menos que se haya proporcionado un mapa personalizado usando set_navigation_map().

Vector2i get_neighbor_cell(coords: Vector2i, neighbor: CellNeighbor) const 🔗

Devuelve la celda vecina a la que se encuentra en las coordenadas coords, identificada por la dirección neighbor. Este método tiene en cuenta los diferentes diseños que puede tener un TileMap.

TileMapPattern get_pattern(coords_array: Array[Vector2i]) 🔗

Crea y devuelve un nuevo TileMapPattern a partir del array de celdas dado. Véase también set_pattern().

Array[Vector2i] get_surrounding_cells(coords: Vector2i) 🔗

Devuelve la lista de todas las celdas vecinas a la de coords. Cualquier celda vecina es una que está tocando los bordes, por lo que para una celda cuadrada se devolverían 4 celdas, para un hexágono se devuelven 6 celdas.

Array[Vector2i] get_used_cells() const 🔗

Devuelve un array de Vector2i con las posiciones de todas las celdas que contienen un tile. Una celda se considera vacía si su identificador de origen es igual a -1, su identificador de coordenadas del atlas es Vector2(-1, -1) y su identificador alternativo es -1.

Array[Vector2i] get_used_cells_by_id(source_id: int = -1, atlas_coords: Vector2i = Vector2i(-1, -1), alternative_tile: int = -1) const 🔗

Devuelve un array Vector2i con las posiciones de todas las celdas que contienen un tile. Los tiles pueden filtrarse según su origen (source_id), sus coordenadas del atlas (atlas_coords) o el ID alternativo (alternative_tile).

Si un parámetro tiene su valor establecido en el predeterminado, este parámetro no se utiliza para filtrar una celda. Por lo tanto, si todos los parámetros tienen sus respectivos valores predeterminados, este método devuelve el mismo resultado que get_used_cells().

Se considera que una celda está vacía si su identificador de origen es igual a -1, su identificador de coordenadas del atlas es Vector2(-1, -1) y su identificador alternativo es -1.

Rect2i get_used_rect() const 🔗

Devuelve un rectángulo que encierra los tiles usados (no vacíos) del mapa.

bool has_body_rid(body: RID) const 🔗

Devuelve si el RID de body pertenece a una de las celdas de este TileMapLayer.

bool is_cell_flipped_h(coords: Vector2i) const 🔗

Devuelve true si la celda en las coordenadas coords se invierte horizontalmente. El resultado solo es válido para fuentes de atlas.

bool is_cell_flipped_v(coords: Vector2i) const 🔗

Devuelve true si la celda en las coordenadas coords se invierte verticalmente. El resultado solo es válido para fuentes de atlas.

bool is_cell_transposed(coords: Vector2i) const 🔗

Devuelve true si la celda en las coordenadas coords está transpuesta. El resultado solo es válido para fuentes de atlas.

Vector2i local_to_map(local_position: Vector2) const 🔗

Devuelve las coordenadas del mapa de la celda que contiene la local_position dada. Si local_position está en coordenadas globales, considera usar Node2D.to_local() antes de pasarla a este método. Véase también map_to_local().

Vector2i map_pattern(position_in_tilemap: Vector2i, coords_in_pattern: Vector2i, pattern: TileMapPattern) 🔗

Devuelve para las coordenadas dadas coords_in_pattern en un TileMapPattern las coordenadas de celda correspondientes si el patrón se pegó en las coordenadas position_in_tilemap (ver set_pattern()). Esta asignación es necesaria ya que en las formas de tile de medio desplazamiento, la asignación podría no funcionar calculando position_in_tile_map + coords_in_pattern.

Vector2 map_to_local(map_position: Vector2i) const 🔗

Devuelve la posición centrada de una celda en el espacio de coordenadas local del TileMapLayer. Para convertir el valor devuelto en coordenadas globales, usa Node2D.to_global(). Véase también local_to_map().

Nota: Esto puede no corresponder a la posición visual del tile, es decir, ignora la propiedad TileData.texture_origin de los tiles individuales.

void notify_runtime_tile_data_update() 🔗

Notifica al nodo TileMapLayer que las llamadas a _use_tile_data_runtime_update() o _tile_data_runtime_update() conducirán a resultados diferentes. Esto activará así una actualización de TileMapLayer.

Advertencia: La actualización del TileMapLayer es computacionalmente costosa y puede afectar el rendimiento. Intenta limitar el número de llamadas a esta función para evitar actualizaciones innecesarias.

Nota: Esto no activa una actualización directa del TileMapLayer, la actualización se realizará al final del fotograma como de costumbre (a menos que llames a update_internals()).

void set_cell(coords: Vector2i, source_id: int = -1, atlas_coords: Vector2i = Vector2i(-1, -1), alternative_tile: int = 0) 🔗

Establece los identificadores de tile para la celda en las coordenadas coords. Cada tile del TileSet se identifica utilizando tres partes:

El identificador de origen source_id identifica un identificador TileSetSource. Véase TileSet.set_source_id(),
El identificador de coordenadas del atlas atlas_coords identifica las coordenadas de un tile en el atlas (si el origen es un TileSetAtlasSource). Para TileSetScenesCollectionSource siempre debe ser Vector2i(0, 0),
El identificador de tile alternativo alternative_tile identifica un tile alternativo en el atlas (si el origen es un TileSetAtlasSource), y la escena para un TileSetScenesCollectionSource.

Si source_id se establece en -1, atlas_coords en Vector2i(-1, -1), o alternative_tile en -1, la celda se borrará. Una celda borrada obtiene todos sus identificadores establecidos automáticamente en sus respectivos valores no válidos, a saber, -1, Vector2i(-1, -1) y -1.

void set_cells_terrain_connect(cells: Array[Vector2i], terrain_set: int, terrain: int, ignore_empty_terrains: bool = true) 🔗

Actualiza todas las celdas en el array de coordenadas cells para que utilicen el terrain dado para el terrain_set dado. Si una celda actualizada tiene el mismo terreno que una de sus celdas vecinas, esta función intenta unir las dos. Esta función podría actualizar los tiles vecinos si es necesario para crear transiciones de terreno correctas.

Si ignore_empty_terrains es true, los terrenos vacíos se ignorarán al intentar encontrar el tile que mejor se adapte a las restricciones de terreno dadas.

Nota: Para que funcione correctamente, este método requiere que el TileSet del TileMapLayer tenga terrenos configurados con todas las combinaciones de terreno necesarias. De lo contrario, puede producir resultados inesperados.

void set_cells_terrain_path(path: Array[Vector2i], terrain_set: int, terrain: int, ignore_empty_terrains: bool = true) 🔗

Actualiza todas las celdas en el array de coordenadas path para que utilicen el terrain dado para el terrain_set dado. La función también conectará dos celdas sucesivas en la ruta con el mismo terreno. Esta función podría actualizar los tiles vecinos si es necesario para crear transiciones de terreno correctas.

Si ignore_empty_terrains es true, los terrenos vacíos se ignorarán al intentar encontrar el tile que mejor se adapte a las restricciones de terreno dadas.

Nota: Para que funcione correctamente, este método requiere que el TileSet del TileMapLayer tenga terrenos configurados con todas las combinaciones de terreno necesarias. De lo contrario, puede producir resultados inesperados.

Establece un map personalizado como un mapa de navegación NavigationServer2D. Si no se establece, se utiliza el mapa de navegación World2D predeterminado en su lugar.

void set_pattern(position: Vector2i, pattern: TileMapPattern) 🔗

Pega el TileMapPattern en la position dada en el mapa de tiles. Véase también get_pattern().

void update_internals() 🔗

Activa una actualización directa del TileMapLayer. Por lo general, no es necesario llamar a esta función, ya que el nodo TileMapLayer se actualiza automáticamente cuando se modifica una de sus propiedades o celdas.

Sin embargo, por razones de rendimiento, esas actualizaciones se procesan por lotes y se retrasan hasta el final del fotograma. Llamar a esta función forzará al TileMapLayer a actualizarse de inmediato.

Advertencia: La actualización del TileMapLayer es computacionalmente costosa y puede afectar el rendimiento. Intenta limitar el número de actualizaciones y cuántos tiles impactan.