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...

TileMapLayer

Eredita: Node2D < CanvasItem < Node < Object

Nodo per mappe basate su tasselli 2D.

Descrizione

Nodo per mappe basate su tasselli 2D. Un TileMapLayer utilizza un TileSet che contiene un elenco di tasselli che servono per creare mappe basate su griglia. A differenza del nodo TileMap, che è deprecato, TileMapLayer ha un solo livello di tasselli. È possibile utilizzare diversi TileMapLayer per ottenere lo stesso risultato di un nodo TileMap.

Per motivi di prestazioni, tutti gli aggiornamenti di TileMap sono raggruppati alla fine di un frame. In particolare, ciò significa che i tasselli di scena da un TileSetScenesCollectionSource sono inizializzati dopo il loro genitore. Ciò viene messo in coda solo quando ci si trova all'interno dell'albero di scene.

Per forzare un aggiornamento in anticipo, chiamare update_internals().

Nota: Per motivi di prestazioni e compatibilità, le coordinate serializzate da TileMapLayer sono limitate a numeri interi con segno a 16 bit, ovvero l'intervallo per le coordinate X e Y è compreso tra -32768 e 32767. Quando si salvano i dati dei tasselli, i tasselli al di fuori di questo intervallo sono avvolti.

Tutorial

Proprietà

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`

Metodi

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()

Segnali

changed() 🔗

Emesso quando cambiano le proprietà di questo TileMapLayer. Ciò include celle modificate, proprietà o modifiche apportate al TileSet assegnato.

Nota: Questo segnale può essere emesso molto spesso quando si modifica in blocco un TileMapLayer. Evitare di eseguire elaborazioni complesse in una funzione connessa e considerare di ritardarla alla fine del frame (ad esempio chiamando Object.call_deferred()).

Enumerazioni

enum DebugVisibilityMode: 🔗

DebugVisibilityMode DEBUG_VISIBILITY_MODE_DEFAULT = 0

Nasconde le forme di debug delle collisioni o della navigazione nell'editor e usa le impostazioni di debug per determinarne la visibilità nel gioco (ad esempio SceneTree.debug_collisions_hint o SceneTree.debug_navigation_hint).

DebugVisibilityMode DEBUG_VISIBILITY_MODE_FORCE_HIDE = 2

Nascondi sempre le forme di debug delle collisioni o della navigazione.

DebugVisibilityMode DEBUG_VISIBILITY_MODE_FORCE_SHOW = 1

Mostra sempre le forme di debug delle collisioni o della navigazione.

Descrizioni delle proprietà

bool collision_enabled = true 🔗

void set_collision_enabled(value: bool)
bool is_collision_enabled()

Abilita o disabilita le collisioni.

DebugVisibilityMode collision_visibility_mode = 0 🔗

void set_collision_visibility_mode(value: DebugVisibilityMode)
DebugVisibilityMode get_collision_visibility_mode()

Mostra o nasconde le forme di collisione del TileMapLayer. Se impostato su DEBUG_VISIBILITY_MODE_DEFAULT, dipende dalle impostazioni di debug di visualizzazione delle collisioni.

bool enabled = true 🔗

void set_enabled(value: bool)
bool is_enabled()

Se false, disabilita completamente questo TileMapLayer (rendering, collisione, navigazione, tasselli di scena, ecc.)

bool navigation_enabled = true 🔗

void set_navigation_enabled(value: bool)
bool is_navigation_enabled()

Se true, le regioni di navigazione sono abilitate.

DebugVisibilityMode navigation_visibility_mode = 0 🔗

void set_navigation_visibility_mode(value: DebugVisibilityMode)
DebugVisibilityMode get_navigation_visibility_mode()

Mostra o nascondi le mesh di navigazione del TileMapLayer. Se impostato su DEBUG_VISIBILITY_MODE_DEFAULT, dipende dalle impostazioni di debug della navigazione.

bool occlusion_enabled = true 🔗

void set_occlusion_enabled(value: bool)
bool is_occlusion_enabled()

Abilita o disabilita l'occlusione di luce.

int physics_quadrant_size = 16 🔗

void set_physics_quadrant_size(value: int)
int get_physics_quadrant_size()

La dimensione dei quadranti di fisica del TileMapLayer. All'interno di un quadrante di fisica, le celle con proprietà fisiche simili sono raggruppate assieme e le loro forme di collisione sono unite. rendering_quadrant_size definisce la lunghezza del lato di un quadrato, nel sistema di coordinate della mappa, che forma il quadrante. Quindi, la dimensione predefinita dei quadranti raggruppa insieme 16 * 16 = 256 tasselli.

Nota: Poiché i quadranti sono creati secondo il sistema di coordinate della mappa, la "forma quadrata" dei quadranti potrebbe non apparire quadrata nel sistema di coordinate locale del TileMapLayer.

Nota: Ciò influisce sul valore restituito da get_coords_for_body_rid(). Valori più alti renderanno quella funzione meno precisa. Per ottenere le coordinate esatte di una cella, è necessario impostare physics_quadrant_size su 1, il che disabilita la suddivisione fisica.

int rendering_quadrant_size = 16 🔗

void set_rendering_quadrant_size(value: int)
int get_rendering_quadrant_size()

La dimensione dei quadranti di rendering del TileMapLayer. Un quadrante è un gruppo di tasselli da disegnare insieme su un singolo elemento canvas, per scopi di ottimizzazione. rendering_quadrant_size definisce la lunghezza del lato di un quadrato, nel sistema di coordinate della mappa, che forma il quadrante. Quindi, la dimensione predefinita dei quadranti raggruppa insieme 16 * 16 = 256 tasselli.

La dimensione dei quadranti non si applica a un TileMapLayer ordinato per Y, poiché in quel caso i tasselli sono raggruppati in base alla posizione Y.

Nota: Poiché i quadranti sono creati secondo il sistema di coordinate della mappa, la "forma quadrata" dei quadranti potrebbe non apparire quadrata nel sistema di coordinate locale del TileMapLayer.

PackedByteArray tile_map_data = PackedByteArray() 🔗

void set_tile_map_data_from_array(value: PackedByteArray)
PackedByteArray get_tile_map_data_as_array()

I dati grezzi della mappa dei tasselli come array di byte.

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()

Il TileSet utilizzato da questo livello. Le texture, le collisioni e il comportamento aggiuntivo di tutti i tasselli disponibili sono memorizzati qui.

bool use_kinematic_bodies = false 🔗

void set_use_kinematic_bodies(value: bool)
bool is_using_kinematic_bodies()

Se true, le forme di collisione di questo TileMapLayer saranno istanziate come corpi cinematici. Ciò può essere necessario per spostare i nodi TileMapLayer (ad esempio piattaforme mobili).

bool x_draw_order_reversed = false 🔗

void set_x_draw_order_reversed(value: bool)
bool is_x_draw_order_reversed()

Se CanvasItem.y_sort_enabled è abilitato, impostando questo su true sarà invertito l'ordine in cui i tasselli sono disegnati sull'asse X.

int y_sort_origin = 0 🔗

void set_y_sort_origin(value: int)
int get_y_sort_origin()

Questo valore di origine di Y-sort viene aggiunto al valore di origine Y-sort di ogni tile. Ciò consente, ad esempio, di simulare un diverso livello di altezza. Ciò può essere utile per i giochi con vista dall'alto.

Descrizioni dei metodi

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

Chiamato con un oggetto TileData che sta per essere utilizzato internamente dal TileMapLayer, consentendone la modifica in fase di esecuzione.

Questo metodo viene chiamato solo se _use_tile_data_runtime_update() è implementato e restituisce true per le coordinate coords del tassello.

Attenzione: le sotto-risorse dell'oggetto tile_data sono le stesse di quelle nel TileSet. Modificarle potrebbe avere un impatto sull'intero TileSet. Assicurati invece di duplicare tali risorse.

Nota: Se le proprietà dell'oggetto tile_data dovessero cambiare nel tempo, usa notify_runtime_tile_data_update() per notificare al TileMapLayer che necessita di un aggiornamento.

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

Chiamato quando le celle di questo TileMapLayer necessitano di un aggiornamento interno. Questo aggiornamento può essere causato dalla modifica di singole celle o da una modifica nel tile_set (la quale causa la messa in coda di tutte le celle per un aggiornamento). La prima chiamata a questa funzione è sempre per inizializzare tutte le celle del TileMapLayer. coords contiene le coordinate di tutte le celle modificate, più o meno nell'ordine in cui sono state modificate. forced_cleanup è true quando le parti interne del TileMapLayer devono essere completamente ripulite. Questo è il caso quando:

Il livello è disabilitato;
Il livello non è visibile;
tile_set è impostato su null;
Il nodo viene rimosso dall'albero;
Il nodo viene liberato.

Nota che qualsiasi aggiornamento interno che avviene mentre una di queste condizioni si è verificata è considerato una "pulizia". Vedi anche update_internals().

Attenzione: L'implementazione di questo metodo potrebbe degradare le prestazioni del TileMapLayer.

bool _use_tile_data_runtime_update(coords: Vector2i) virtual 🔗

Dovrebbe restituire true se il tassello alle coordinate coords richiede un aggiornamento in fase di esecuzione.

Avviso: Assicurati che questa funzione restituisca true solo quando necessario. Qualsiasi tassello elaborato in fase di esecuzione senza che ce ne sia bisogno implicherà una notevole penalizzazione delle prestazioni.

Nota: Se il risultato di questa funzione dovesse cambiare, usa notify_runtime_tile_data_update() per notificare a TileMapLayer che necessita di un aggiornamento.

void clear() 🔗

Cancella tutte le celle.

void erase_cell(coords: Vector2i) 🔗

Cancella la cella alle coordinate coords.

void fix_invalid_tiles() 🔗

Cancella le celle contenenti tasselli che non esistono nel tile_set.

int get_cell_alternative_tile(coords: Vector2i) const 🔗

Restituisce l'ID tassello alternativo della cella alle coordinate coords.

Vector2i get_cell_atlas_coords(coords: Vector2i) const 🔗

Restituisce l'ID coordinate dell'atlante di tasselli della cella alle coordinate coords. Restituisce Vector2i(-1, -1) se la cella non esiste.

int get_cell_source_id(coords: Vector2i) const 🔗

Restituisce l'ID sorgente di tassello della cella alle coordinate coords. Restituisce -1 se la cella non esiste.

TileData get_cell_tile_data(coords: Vector2i) const 🔗

Restituisce l'oggetto TileData associato alla cella specificata, oppure null se la cella non esiste o non è un TileSetAtlasSource.

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

Vector2i get_coords_for_body_rid(body: RID) const 🔗

Restituisce le coordinate del quadrante di fisica (vedi physics_quadrant_size) per il RID del corpo fisico specificato. Tale RID può essere recuperato da KinematicCollision2D.get_collider_rid(), quando avviene una collisione con un tassello.

Nota: Valori più alti di physics_quadrant_size renderanno questa funzione meno precisa. Per ottenere le coordinate esatte di una cella, è necessario impostare physics_quadrant_size su 1, il che disabilita la suddivisione fisica.

Restituisce il RID della navigazione del NavigationServer2D utilizzata da questo TileMapLayer.

Per impostazione predefinita, restituisce la mappa di navigazione predefinita del World2D, a meno che non sia stata fornita una mappa personalizzata tramite set_navigation_map().

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

Restituisce la cella adiacente a quella con le coordinate coords, identificata dalla direzione neighbor. Questo metodo tiene conto dei diversi layout che una TileMap può assumere.

TileMapPattern get_pattern(coords_array: Array[Vector2i]) 🔗

Crea e restituisce un nuovo TileMapPattern dall'array di celle specificato. Vedi anche set_pattern().

Array[Vector2i] get_surrounding_cells(coords: Vector2i) 🔗

Restituisce la lista di tutte le celle adiacenti a quella nelle coordinate coords. Ogni cella adiacente è una cella che tocca i bordi, quindi per una cella quadrata verrebbero restituite 4 celle, per un esagono ne vengono restituite 6.

Array[Vector2i] get_used_cells() const 🔗

Restituisce un array di Vector2i con le posizioni di tutte le celle contenenti un tassello. Una cella è considerata vuota se il suo identificatore di sorgente è uguale a -1, il suo identificatore di coordinate atlante è Vector2(-1, -1) e il suo identificatore di alternativo è -1.

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

Restituisce un array Vector2i con le posizioni di tutte le celle contenenti un tassello. I tasselli possono essere filtrati in base alla loro origine (source_id), alle loro coordinate d'atlante (atlas_coords) o all'ID alternativo (alternative_tile).

Se un parametro ha il suo valore impostato su quello predefinito, questo parametro non viene utilizzato per filtrare una cella. Pertanto, se tutti i parametri hanno i rispettivi valori predefiniti, questo metodo restituisce lo stesso risultato di get_used_cells().

Una cella è considerata vuota se il suo identificatore di sorgente è uguale a -1, il suo identificatore di coordinate atlante è Vector2(-1, -1) e il suo identificatore di alternativo è -1.

Rect2i get_used_rect() const 🔗

Restituisce un rettangolo che racchiude i tasselli usati (non vuoti) della mappa.

bool has_body_rid(body: RID) const 🔗

Restituisce se il RID body fornito appartiene a una delle celle di questo TileMapLayer.

bool is_cell_flipped_h(coords: Vector2i) const 🔗

Restituisce true se la cella alle coordinate coords è ribaltata orizzontalmente. Il risultato è valido solo per le sorgenti atlante.

bool is_cell_flipped_v(coords: Vector2i) const 🔗

Restituisce true se la cella alle coordinate coords è ribaltata verticalmente. Il risultato è valido solo per le sorgenti atlante.

bool is_cell_transposed(coords: Vector2i) const 🔗

Restituisce true se la cella alle coordinate coords è trasposta. Il risultato è valido solo per le sorgenti atlante.

Vector2i local_to_map(local_position: Vector2) const 🔗

Restituisce le coordinate della mappa della cella contenente la posizione locale local_position. Se local_position è in coordinate globali, considera di usare Node2D.to_local() prima di passarlo a questo metodo. Vedi anche map_to_local().

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

Restituisce per le coordinate coords_in_pattern in un TileMapPattern le coordinate della cella corrispondente se il motivo è stato incollato alle coordinate position_in_tilemap (vedi set_pattern()). Questa mappatura è richiesta poiché nelle forme dei tasselli con offset dimezzato, la mappatura potrebbe non funzionare calcolando position_in_tile_map + coords_in_pattern.

Vector2 map_to_local(map_position: Vector2i) const 🔗

Restituisce la posizione centrata di una cella nello spazio di coordinate locali del TileMapLayer. Per convertire il valore restituito in coordinate globali, usa Node2D.to_global(). Vedi anche local_to_map().

Nota: Questo potrebbe non corrispondere alla posizione visiva del tassello, ovvero ignora la proprietà TileData.texture_origin dei singoli tasselli.

void notify_runtime_tile_data_update() 🔗

Notifica al nodo TileMapLayer che le chiamate a _use_tile_data_runtime_update() o _tile_data_runtime_update() porteranno a risultati diversi. Ciò attiverà quindi un aggiornamento del TileMapLayer.

Attenzione: L'aggiornamento di TileMapLayer è computazionalmente costoso e potrebbe avere un impatto sulle prestazioni. Prova a limitare il numero di chiamate a questa funzione per evitare aggiornamenti non necessari.

Nota: Ciò non attiva un aggiornamento diretto del TileMapLayer, l'aggiornamento sarà eseguito alla fine del frame come al solito (a meno che tu non chiami update_internals()).

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

Imposta gli identificatori del tassello per la cella alle coordinate coords. Ogni tassello del TileSet è identificato utilizzando tre parti:

L'identificatore di sorgente source_id identifica un identificatore TileSetSource. Vedi TileSet.set_source_id(),
L'identificatore delle coordinate dell'atlante atlas_coords identifica le coordinate di un tassello nell'atlante (se la sorgente è un TileSetAtlasSource). Per TileSetScenesCollectionSource dovrebbe essere sempre Vector2i(0, 0),
L'identificatore di tassello alternativo alternative_tile identifica un'alternativo tassello nell'atlante (se la sorgente è un TileSetAtlasSource) e la scena per un TileSetScenesCollectionSource.

Se source_id è impostato su -1, atlas_coords su Vector2i(-1, -1), o alternative_tile su -1, la cella verrà cancellata. Una cella cancellata ottiene tutti i suoi identificatori impostati automaticamente sui rispettivi valori non validi, ovvero -1, Vector2i(-1, -1) e -1.

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

Aggiorna tutte le celle nell'array di coordinate cells in modo che usino il terreno terrain per l'insieme di terreni terrain_set. Se una cella aggiornata ha lo stesso terreno di una delle celle vicine, questa funzione tenta di unire le due. Questa funzione potrebbe aggiornare i tasselli vicine se necessario per creare transizioni di terreno adeguate.

Se ignore_empty_terrains è true, i terreni vuoti saranno ignorati quando si tenta di trovare il tassello più adatto per i vincoli di terreno specificati.

Nota: Per funzionare correttamente, questo metodo richiede che il TileSet del TileMapLayer abbia terreni impostati con tutte le combinazioni di terreno richieste. Altrimenti, potrebbe produrre risultati imprevisti.

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

Aggiorna tutte le celle nell'array di coordinate path in modo che usino il terreno terrain per l'insieme di terreni terrain_set. La funzione collegherà anche due celle successive nel percorso con lo stesso terreno. Questa funzione potrebbe aggiornare i tasselli vicini se necessario per creare transizioni di terreno adeguate.

Se ignore_empty_terrains è true, i terreni vuoti saranno ignorati quando si tenta di trovare il tassello più adatto per i vincoli di terreno specificati.

Nota: Per funzionare correttamente, questo metodo richiede che il TileSet del TileMapLayer abbia terreni impostati con tutte le combinazioni di terreno richieste. Altrimenti, potrebbe produrre risultati imprevisti.

Imposta una map personalizzata come mappa di navigazione del NavigationServer2D. Se non impostata, utilizza invece la mappa di navigazione predefinita del World2D.

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

Incolla il TileMapPattern alla posizione position nella mappa. Vedi anche get_pattern().

void update_internals() 🔗

Attiva un aggiornamento diretto del TileMapLayer. Di solito, non è necessario chiamare questa funzione, poiché il nodo TileMapLayer si aggiorna automaticamente quando una delle sue proprietà o celle viene modificata.

Tuttavia, per motivi di prestazioni, tali aggiornamenti sono raggruppati e ritardati alla fine del frame. Chiamare questa funzione forzerà invece TileMapLayer ad aggiornarsi immediatamente.

Attenzione: L'aggiornamento di TileMapLayer è computazionalmente costoso e potrebbe avere un impatto sulle prestazioni. Prova a limitare il numero di aggiornamenti e il numero di tasselli che influenzano.