Introdução a dicionários

Dicionários são tabelas que associam nomes ou chaves a um valor em vez de um índice.

Exemplo:

local pet = {
   Nome = "Bobbie",
   Tipo = "Cachorro",
}

Use dicionários quando você precisar rotular valores, não apenas listá-los em ordem como um array faz. Pratique usando dicionários neste tutorial manipulando valores associados a um jogador.

Sintaxe de dicionário

Assim como arrays, dicionários são atribuídos a uma variável com chaves {}. Pares chave-valor são armazenados em linhas separadas seguidas por uma vírgula. Chaves e valores podem ser de qualquer tipo de dado, incluindo strings, números e nomes de variáveis.

local nomesJogadores = {
	jogador1 = "Zap",
	jogador2 = "Kel",
}
print(nomesJogadores["jogador1"])

Para referenciar partes ou outros objetos instanciados como chaves, use colchetes.

local parteVerde = workspace.GreenPart
local parteVermelha = workspace.RedPart

local listaPartes = {
	[parteVerde] = true,
	[parteVermelha] = false,
}
print(listaPartes[parteVermelha])

Criar um dicionário

Um uso cotidiano de dicionários é organizar informações de jogadores ou personagens. Estes passos exploram como as informações de um personagem inimigo teórico podem ser armazenadas e acessadas.

1. Em um novo script, crie um dicionário chamado inimigo.

   local inimigo = {
   
   }

2. A primeira chave no dicionário rastreará o nome do inimigo com uma variável chamada Nome.

   local inimigo = {
   	Nome
   }

3. Atribua um nome ao inimigo à chave, seguido por uma vírgula.

   local inimigo = {
   	Nome = "Spike",
   }

4. Adicione um segundo par chave-valor para quanto de saúde o inimigo deve ter. Lembre-se, as chaves devem sempre usar o mesmo tipo de dado, mas os valores não precisam.

   local inimigo = {
   	Nome = "Spike",
   	Saúde = 1000,
   }

Usar valores de dicionário

Existem duas maneiras de acessar valores de dicionário:

• nomeTabela["nomeChave"] (importante, note as aspas)
• nomeTabela.nomeChave

local inimigo = {
	Nome = "Spike",
	Saúde = 1000,
}

print("O vilão " .. inimigo["Nome"] .. " se aproxima!")
print("O vilão " .. inimigo.Nome .. " se aproxima!")

Qual estilo usar geralmente depende do propósito da tabela. Para tabelas que contêm uma coleção de valores, como uma lista de jogadores em um servidor, os programadores geralmente usarão nomeTabela["nomeChave"]. Para um dicionário usado para descrever um objeto, os programadores são mais propensos a usar nomeTabela.nomeChave.

Mudar um valor de dicionário

Mudar o valor de uma chave é o mesmo que qualquer outra variável; use o operador igual =.

1. Abaixo da tabela inimigo, defina o nome do inimigo para algo diferente.

   local inimigo = {
   	Nome = "Spike",
   	Saúde = 1000,
   }
   
   inimigo.Nome = "Rana"
   
   print("O nome do inimigo é " .. inimigo.Nome)

2. Teste o jogo e verifique a janela de Saída.

Variáveis pré-existentes como chaves

Dicionários podem interagir com variáveis pré-existentes declaradas em outras partes de um script. O seguinte exemplo de código usa uma variável para adicionar o nome de um jogador como uma chave quando ele entra no jogo e, em seguida, define seu valor de pontos para 0.

1. Em ServerScriptService, crie um novo script chamado PlayerPoints. No script, obtenha o Serviço de Jogadores e crie um dicionário vazio chamado pontosJogadores.

   local Jogadores = game:GetService("Players")
   
   local pontosJogadores = {
   
   }

2. Codifique uma função local para definir os pontos do jogador com um parâmetro para uma nova variável de jogador. Conecte a função ao evento Players.PlayerAdded.

   local pontosJogadores = {
   
   }
   
   local function definirPontos(novoJogador)
   
   end
   
   Jogadores.PlayerAdded:Connect(definirPontos)

3. Na função, adicione uma variável para obter o Nome do jogador, uma propriedade em cada objeto Player, e uma instrução de impressão para teste.

   local function definirPontos(novoJogador)
   	local nome = novoJogador.Nome
   	print("olá " .. nome)
   end

4. Insira nome no dicionário pontosJogadores como uma chave e defina o valor, os pontos do jogador, para 0.

   local function definirPontos(novoJogador)
   	local nome = novoJogador.Nome
   	print("olá " .. nome)
   	pontosJogadores[nome] = 0
   end

   Como nome foi criado como uma variável, ele pode ser acessado com o nome da variável real. Se nome fosse um nome de chave, precisaria ser acessado da mesma forma que outras strings: pontosJogadores["nome"].

5. Use nome para imprimir o nome do jogador e pontosJogadores[nome] para imprimir o valor da chave correspondente à variável.

   local function definirPontos(novoJogador)
   	local nome = novoJogador.Nome
   	print("olá " .. nome)
   	pontosJogadores[nome] = 0
   	print(nome .. " tem " .. pontosJogadores[nome] .. " pontos.")
   end

6. Execute o projeto e observe a saída.

local Jogadores = game:GetService("Players")

local pontosJogadores = {

}

local function definirPontos(novoJogador)
   local nome = novoJogador.Nome
   print("olá " .. nome)
   pontosJogadores[nome] = 0
   print(nome .. " tem " .. pontosJogadores[nome] .. " pontos.")
end

Jogadores.PlayerAdded:Connect(definirPontos)

Desafios opcionais

Abaixo estão alguns desafios que se aplicam ao uso de dicionários de diferentes maneiras. Veja se você consegue desenvolver o código para estes.

• Crie uma parte de armadilha que cause dano ao longo do tempo a um jogador. Assim que um jogador tocar a armadilha, cause dano, espere e, em seguida, permita que ele seja danificado novamente.
• Crie uma função que verifique qual dos dois jogadores tem mais pontos acessando um dicionário.
• Crie um cifrador, um sistema de troca de uma string por outra para criar um código "secreto". Por exemplo, a letra "A" pode ser trocada por "G", ou a palavra "maçã" pode ser trocada por "laranja".

Dicionários e pairs()

pairs() é uma função que é frequentemente usada para iterar através de dicionários. Um exemplo é visto abaixo.

local meuDicionario = {
	["Jogador Azul"] = "Ana",
	["Jogador Dourado"] = "Binh",
	["Jogador Vermelho"] = "Cate",
}

for chave, valor in pairs(meuDicionario) do
	print(chave .. " é " .. valor)
end

pairs() pode ser usado para trabalhar com a chave, valor ou ambos de um elemento de dicionário. No loop for abaixo, a primeira variável é a chave. A segunda variável é o valor. O dicionário que você deseja trabalhar é passado para pairs().

local inventario = {
	["Tijolos Dourados"] = 43,
	Cenouras = 3,
	Tochas = 2,
}

print("Você tem:")

for nomeItem, valorItem in pairs(inventario) do
	print(valorItem, nomeItem)
end

Quando executado, o código imprimirá o seguinte:

Você tem:
43 Tijolos Dourados
3 Cenouras
2 Tochas

Resumo

Dicionários são tabelas que usam pares chave-valor em vez de valores indexados. Dicionários e arrays começam de forma semelhante ao atribuir chaves a uma variável. Mantenha as entradas separadas por vírgulas.

Todas as chaves dentro de um dicionário devem usar o mesmo tipo de dado, mas os valores podem misturar tipos de dados sem problemas.

A maneira como um dicionário é acessado pode transmitir seu propósito. Um dicionário de propriedades de inimigos provavelmente será acessado com o operador de ponto, enquanto uma lista de nomes provavelmente usará nomeTabela[nomeChave].

Ao usar colchetes, tenha cuidado; nomes de chaves criados dentro da tabela devem ser tratados como strings: nomeTabela["nomeChave"]. No entanto, ao referenciar objetos como partes, as aspas não são necessárias: nomeTabela[nomeChave].

Muitos scripts precisam percorrer dicionários ou arrays, mas você pode não saber sempre o início e o fim dessas estruturas de dados. Por exemplo, um dicionário de jogadores pode estar mudando, ou jogadores podem ter um inventário de array de tamanhos variados.

Nessas situações, você pode usar pairs() e ipairs() em um loop for para percorrer cada elemento sem pontos de início e fim conhecidos. Você também pode usar iteração geral através da palavra-chave in para percorrer elementos sem a necessidade de pairs() ou ipairs().