Arrays

Note: Esta página cobre o uso de arrays em ACS. Para arrays em ZScript, veja aqui.

Arrays são grupos de variáveis distinguidos por números indexados. Se você já conhece C, Java ou qualquer outra linguagem que suporte arrays (basicamente todas as principais), não deve ter problemas. Para quem não está familiarizado, aqui vai uma explicação simples.

Enquanto uma variável guarda um único valor, um array guarda uma coleção ordenada de valores acessíveis por um número chamado índice (index). Arrays têm nomes como qualquer variável, mas você acessa valores específicos colocando o índice entre colchetes após o nome.

Para declarar um array, use a seguinte sintaxe: tipo nomeDoArray[tamanho];

Onde tipo é um dos tipos de dados suportados em ACS, nomeDoArray é um nome único para você referenciar o array no código, e tamanho é a quantidade de elementos que o array vai conter.

Aqui vão alguns exemplos de declaração:

int array1[4];

int array2[3] = { 1, 5, 9 };

str array3[2][2] = {{"This is", "a two"}, {"dimensional", "array"}};

Como em todas as variáveis em ACS, todo valor de um array é inicializado como '0'. Então, mesmo que você defina um array grande, não precisa inicializar cada posição manualmente por medo de acessar lixo (isso é mais uma preocupação típica pra quem vem de C). O número entre colchetes é chamado de tamanho quando você declara, e de índice quando você acessa (em scripts ou functions). Todos os arrays precisam ter escopo de script, map, global ou world (os dois últimos têm casos especiais).

A parte que mais confunde em arrays é a relação índice vs tamanho. Se você define um array com tamanho 4, você faz como no primeiro exemplo acima. Mas para acessar o quarto elemento, você usa array1[3], porque os índices começam em 0. O jeito mais fácil de lembrar: subtraia 1 do número “humano”. Se você quer o 10º elemento, acessa índice 9. Se quer o 1º, acessa índice 0.

Arrays também podem ser multidimensionais. Em outras palavras, você pode ter arrays de arrays (de arrays de arrays... conforme a quantidade de dimensões que precisar).

// Um array de 4 inteiros.
int normalArray[4] = { 1, 2, 3, 4 };

// Um array 2D com 4 “linhas” de tamanho 2. No total, 4x2 = 8 elementos.
int array2D[4][2] = {
                      { 1, 2 },
                      { 3, 4 },
                      { 5, 6 },
                      { 7, 8 },
                    };

Preste muita atenção no uso das chaves no exemplo de inicialização do array 2D acima. No array normal, um único par de chaves preenche os valores. No array 2D, as chaves mais externas correspondem à primeira dimensão ([4]) e cada um dos 4 valores é, por si só, um array de tamanho 2, a segunda dimensão ([2]). Você acessa elementos específicos usando ambos os índices. Se você quiser o valor 6 do exemplo, os índices são 2 e 1 (lembrando: índices começam em 0!).

print(d: array2D[2][1] ); // Imprime 6

Outra forma útil de pensar: um array 1D é como uma lista de itens; um array 2D é como uma grade (grid). O ACS também suporta arrays com mais dimensões (3D, 4D, etc.). Cada dimensão extra funciona adicionando mais um par de colchetes no final do nome. Mas atenção: a quantidade de elementos cresce rápido. arr[2] tem 2 elementos, arr[2][2] tem 4, arr[2][2][2] tem 8, arr[2][2][2][2] tem 16, etc. Então pense bem quantas dimensões você realmente precisa. Se você está pensando em muitas dimensões, talvez esteja complicando demais o problema.

Examples

Neste exemplo, uma mensagem diferente será exibida dependendo de quantas poções de vida (de um total de 100) o jogador pegar em 30 segundos. Se você quisesse uma mensagem diferente a cada dez (10, 20, 30 etc.) sem arrays, teria que fazer algo assim:

script 1 (int potions)
{
   if(potions >= 100)
      print(s:"Best potion picker-upper EVER!");
   else if(potions >= 90)
      print(s:"Nearly perfect!");
   else if(potions >= 80)
      print(s:"Wow that's a lot of potions!");
   else if(potions >= 70)
      print(s:"That was great!");
   else if(potions >= 60)
      print(s:"Pretty good!");
   else if(potions >= 50)
      print(s:"Not too bad");
   else if(potions >= 40)
      print(s:"You're decent");
   else if(potions >= 30)
      print(s:"You did kinda good");
   else if(potions >= 20)
      print(s:"You're okay sorta");
   else if(potions >= 10)
      print(s:"You're bad at this");
   else
      print(s:"You suck!");
}

Isso fica grande e feio. Com arrays, dá pra definir as strings numa lista e reduzir bastante o código:

str strings[11] = { "You suck!", "You're bad at this", "You're okay sorta", 
                "You did kinda good", "You're decent", "Not too bad", 
                "Pretty good!", "That was great!", 
                "Wow that's a lot of potions!", "Nearly perfect!", 
                "Best potion picker-uper EVER!" };

script 1 (int potions)
{
   int potionindex = potions / 10;
   if (potionindex < 0) potionindex = 0;
   if (potionindex > 10) potionindex = 10;
   print(s:strings[potionindex]);
}

Assim, você reduziu aquele script enorme para um array + algumas linhas simples. Repare que o inteiro passado para o script 1 é o número de poções, com “faixas” múltiplas de 10 (0, 10, 20, ..., 90, 100). Se você divide por 10, obtém o índice correspondente. Portanto, pegar 20 poções dá 20 / 10 = 2, ou seja, índice 2, que corresponde à terceira string do array: "You're okay sorta". Para evitar índice fora do limite (se alguém trapacear e pegar mais de 109 poções, ou se o valor ficar negativo), duas instruções “limitam” (clamp) o índice entre 0 e 10.