Imagina una caja de juguetes. Dentro puedes guardar coches, piezas de lego, muñecas. Cada juguete tiene su lugar. En programación, esa caja es un array.
¿Qué es un array?
Un array es una estructura de datos que almacena una colección de elementos del mismo tipo bajo un único nombre. Cada elemento ocupa una posición, y esa posición se llama índice. Los índices empiezan siempre en 0.
var dorsales = [14, 25, 30, 22, 35]
print(dorsales[0]) # Imprime 14
print(dorsales[2]) # Imprime 30
En Godot 4 los arrays son objetos de tipo Array y se usan constantemente: para guardar enemigos, objetos del inventario, puntos de un camino, resultados de una búsqueda. Si tienes más de un elemento del mismo tipo, probablemente necesitas un array.
Cómo crear un array en GDScript
Hay varias formas, según lo que necesites:
# Array vacío sin tipo
var enemigos = []
# Array con valores iniciales
var puntuaciones = [100, 250, 80, 310]
# Array tipado (solo acepta Strings)
var nombres: Array[String] = ["Oriol", "Marta", "Pau"]
# Array tipado vacío
var items: Array[String] = []
Los arrays tipados (Array[String], Array[int], etc.) son recomendables cuando sabes qué tipo de datos vas a guardar. Evitan errores difíciles de detectar y hacen el código más legible. Puedes ver más sobre esto en el artículo sobre crear arrays con valores asignados.
Acceder a los elementos
Para leer un elemento, usas su índice entre corchetes. Recuerda: el primer elemento es el índice 0, no el 1.
var frutas = ["manzana", "pera", "naranja"]
print(frutas[0]) # manzana
print(frutas[1]) # pera
print(frutas[-1]) # naranja (índice negativo = desde el final)
El índice -1 es un atajo para acceder al último elemento sin saber el tamaño del array. Muy útil en listas dinámicas. Más ejemplos en cómo acceder a un elemento de un array.
Añadir elementos
Tienes varias funciones según dónde quieras insertar el nuevo elemento:
var inventario = ["espada", "escudo"]
inventario.append("poción") # Añade al final → ["espada", "escudo", "poción"]
inventario.push_back("arco") # Igual que append → al final
inventario.push_front("llave") # Añade al principio → ["llave", "espada", ...]
inventario.insert(1, "casco") # Inserta en la posición 1
append() y push_back() hacen lo mismo. push_front() es útil cuando el orden importa y el nuevo elemento tiene más prioridad. Consulta el artículo sobre push_front y push_back para más detalle.
Eliminar elementos
Para eliminar tienes dos enfoques: por valor o por posición.
var enemigos = ["goblin", "troll", "dragón", "goblin"]
# Por valor (elimina la primera ocurrencia)
enemigos.erase("goblin") # → ["troll", "dragón", "goblin"]
# Por posición
enemigos.remove_at(0) # Elimina el elemento en índice 0
# Pop: elimina Y devuelve el elemento
var ultimo = enemigos.pop_back() # Elimina el último y lo guarda
var primero = enemigos.pop_front() # Elimina el primero y lo guarda
Los métodos pop_back() y pop_front() son especialmente útiles cuando procesas una lista de tareas o turnos: eliminas el elemento y al mismo tiempo lo usas. Ver todos los métodos de eliminación.
Recorrer un array
La forma más común es con un bucle for. Puedes recorrer directamente los valores o usar índices:
var puntos = [10, 30, 20, 50, 15]
# Recorrer por valor (más limpio)
for punto in puntos:
print(punto)
# Recorrer por índice (cuando necesitas la posición)
for i in range(puntos.size()):
print("Posición ", i, ": ", puntos[i])
Usa el recorrido por valor cuando solo necesitas los datos. Usa índices cuando necesitas saber en qué posición está cada elemento o modificar el array mientras lo recorres. Más ejemplos en cómo recorrer todos los elementos.
Funciones útiles
GDScript incluye un buen número de funciones para trabajar con arrays. Las más usadas:
var numeros = [5, 2, 8, 1, 9, 3]
print(numeros.size()) # Número de elementos → 6
print(numeros.is_empty()) # ¿Está vacío? → false
print(numeros.has(8)) # ¿Contiene el 8? → true
print(numeros.find(9)) # Posición del 9 → 4
numeros.sort() # Ordena de menor a mayor → [1, 2, 3, 5, 8, 9]
numeros.shuffle() # Desordena aleatoriamente
numeros.reverse() # Invierte el orden
var copia = numeros.duplicate() # Crea una copia independiente
has() es especialmente útil en juegos para comprobar si un objeto ya está en el inventario antes de añadirlo. duplicate() es importante cuando quieres trabajar con una copia sin modificar el original. Más sobre ordenación en cómo ordenar un array y sobre tamaño en la función size().
Casos de uso reales en videojuegos
Los arrays aparecen en casi cualquier mecánica de juego:
- Inventario del jugador: un array de objetos que se añaden al recogerlos y se eliminan al usarlos.
- Lista de enemigos activos: el juego recorre el array cada frame para actualizar la IA de cada uno.
- Waypoints de patrulla: un array de posiciones Vector2 que un enemigo recorre en orden.
- Cola de turnos: en un juego por turnos, un array determina el orden en que actúan los personajes.
- Historial de puntuaciones: se guarda en un array y se ordena para mostrar el ranking.
# Ejemplo: sistema de waypoints
var waypoints = [Vector2(100, 200), Vector2(300, 200), Vector2(300, 400)]
var indice_actual = 0
func _process(delta):
var destino = waypoints[indice_actual]
position = position.move_toward(destino, velocidad * delta)
if position.distance_to(destino) < 5:
indice_actual = (indice_actual + 1) % waypoints.size()
Este patrón — recorrer un array de posiciones de forma cíclica — aparece en tutoriales de IA básica de enemigos, sistemas de cámaras y rutas de cinematics.
Preguntas frecuentes
¿Qué diferencia hay entre Array y Array tipado en GDScript?
Un Array sin tipo acepta cualquier tipo de dato mezclado. Un Array[String] solo acepta strings y lanza un error si intentas insertar otro tipo. Los tipados son más seguros y ligeramente más rápidos.
¿Puedo tener un array de arrays?
Sí. Un array de arrays es una forma sencilla de crear una cuadrícula o tablero de juego:
var tablero = [[0, 0, 0], [0, 1, 0], [0, 0, 0]]
print(tablero[1][1]) # → 1 (fila 1, columna 1)
¿Qué pasa si accedo a un índice que no existe?
Godot lanza un error en tiempo de ejecución. Antes de acceder a un índice desconocido, comprueba siempre con size() que el índice es válido: if i < mi_array.size().
¿Cuándo usar un Dictionary en lugar de un Array?
Usa un array cuando el orden importa y accedes a los elementos por posición. Usa un Dictionary cuando necesitas acceder por nombre o clave, como jugador["vida"].