Introdução a dicionários | Documentação - Central de Criadores Roblox

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

Exemplo:

Sintaxe do dicionário Luau
local pet = {
   Nome = "Bobbie",
   Tipo = "Cão",
}

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

Sintaxe do dicionário

Assim como os arrays, os 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 qualquer tipo de dado, incluindo strings, números e nomes de variáveis.


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

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


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

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

Use tipos de dados consistentes para as chaves do dicionário. Misturar tipos de dados, como usar tanto strings quanto variáveis para chaves, pode levar a resultados inconsistentes ao manipular o array e confundir outros programadores.

Criar um dicionário

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

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


local inimigo = {

}

A primeira chave no dicionário irá rastrear o nome do inimigo com uma variável chamada Nome.
```
local inimigo = {
	Nome
}
```

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


local inimigo = {
	Nome = "Spike",
}

Adicione um segundo par chave-valor para quanto de saúde o inimigo deve ter. Lembre-se de que 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 do dicionário

Existem duas maneiras de acessar valores de um dicionário:

tableName["keyName"] (importante, note as aspas)
tableName.keyName


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 da finalidade 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 tableName["keyName"]. Para um dicionário usado para descrever um objeto, os programadores são mais propensos a usar tableName.keyName.

Mudar um valor de dicionário

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

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)

Teste o jogo e verifique a janela de saída.

Variáveis pré-existentes como chaves

Os 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 na experiência e, em seguida, define seu valor de pontos para 0.

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


local Players = game:GetService("Players")

local pontosDoJogador = {

}

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


local pontosDoJogador = {

}

local function setPoints(novoJogador)

end

Players.PlayerAdded:Connect(setPoints)

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


local function setPoints(novoJogador)
	local nome = novoJogador.Name
	print("olá " .. nome)
end

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


local function setPoints(novoJogador)
	local nome = novoJogador.Name
	print("olá " .. nome)
	pontosDoJogador[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, ele precisaria ser acessado da mesma forma que outras strings: pontosDoJogador["nome"].

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


local function setPoints(novoJogador)
	local nome = novoJogador.Name
	print("olá " .. nome)
	pontosDoJogador[nome] = 0
	print(nome .. " tem " .. pontosDoJogador[nome] .. " pontos.")
end

Execute o projeto e observe a saída.

Script finalizado
local Players = game:GetService("Players")

local pontosDoJogador = {

}

local function setPoints(novoJogador)
   local nome = novoJogador.Name
   print("olá " .. nome)
   pontosDoJogador[nome] = 0
   print(nome .. " tem " .. pontosDoJogador[nome] .. " pontos.")
end

Players.PlayerAdded:Connect(setPoints)

Desafios opcionais

Abaixo estão alguns desafios que se aplicam ao uso de dicionários de maneiras diferentes. 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 então permita que ele receba dano novamente.
Crie uma função que verifica qual dos dois jogadores tem mais pontos acessando um dicionário.
Crie uma cifra, 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 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 de um elemento do dicionário, valor, ou ambos. 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

Os dicionários são tabelas que usam pares chave-valor em vez de valores indexados. Dicionários e arrays começam de maneira semelhante atribuindo chaves a uma variável. Mantenha as entradas separadas com 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á tableName[keyName].

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

Muitos scripts precisam percorrer dicionários ou arrays, mas você pode nem sempre saber o início e o fim dessas estruturas de dados. Por exemplo, um dicionário de jogadores pode estar mudando, ou os jogadores podem ter um inventário em 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().