Como programar no Roblox Studio: guia para iniciantes

Antes de começar: o Studio, uma Baseplate e a janela Output

Você precisa do Roblox Studio e de uma conta do Roblox, e mais nada: nem editor de código nem plugin. Todo script deste guia é digitado no próprio Script Editor do Studio.

1. Instale o Roblox Studio, o app grátis da Roblox para Windows e Mac, e entre com a sua conta do Roblox.
2. Abra o Studio. A página inicial lista templates: escolha Baseplate. Você ganha um chão com textura de grade 4x4 e uma SpawnLocation, o lugar onde o seu avatar aparece quando você joga.
3. Se as janelas Explorer e Properties não estiverem aparecendo, abra pelo menu Window ou pela aba Home. O Explorer lista todos os objetos do seu jogo; o Properties mostra as configurações do que estiver selecionado.
4. Abra o Output pelo menu Window ou pela aba Script. É aqui que aparecem as mensagens e os erros dos seus scripts.
5. Nas opções de exibição da janela Output, ative Show Context, que marca cada mensagem como Client ou Server, e Show Source, que mostra o script e o número da linha que a gerou.

Workspace
  Baseplate Part
  SpawnLocation SpawnLocation
  Part Part new
    ColourChanger Script new
  Pad Part new
    TouchPad Script new
ServerScriptService
  FirstScript Script new
StarterPlayer
  StarterPlayerScripts
    MyFirstLocalScript LocalScript new

Passo 1: Escreva o seu primeiro script

1. No Explorer, passe o mouse sobre ServerScriptService, clique no botão + e escolha Script (o atalho é Ctrl+I, ou ⌘I no Mac). O Studio cria o script e o abre no Script Editor.
2. Clique com o botão direito no script novo, escolha Rename e chame de FirstScript. O nome não muda o que o script faz, mas diz qual script imprimiu o quê.
3. Scripts novos começam com uma linha, print("Hello world!"). Apague e cole o código abaixo.
4. Aperte Play (F5), com Test escolhido no menu à esquerda dele. O Studio inicia um teste e coloca o seu avatar na SpawnLocation.
5. Leia as linhas no Output e aperte Stop (Shift+F5). O Stop também devolve cada objeto ao estado de antes do Play, então tudo o que você moveu ou pintou enquanto jogava volta ao normal.

-- Script no ServerScriptService chamado FirstScript.
-- Seu primeiro Luau: variáveis, uma função, um if, um loop e uma tabela.
-- Aperte Play (F5) e leia os resultados na janela Output.

-- Uma variável é um nome que guarda um valor
local gameName = "Coin Run"
local coinsToWin = 3

-- Uma função é um bloco de código com nome que você roda quantas vezes quiser.
-- name e goal são os parâmetros; return devolve um valor para quem chamou.
local function describe(name: string, goal: number): string
	return `{name}: collect {goal} coins to win`
end

print(describe(gameName, coinsToWin)) --> Coin Run: collect 3 coins to win

-- Um if só roda o código quando a condição é verdadeira
if coinsToWin > 5 then
	print("That is a long game")
elseif coinsToWin > 1 then
	print("That is a short game")
else
	print("One coin and you win")
end

-- Um loop for repete o código um número definido de vezes
for count = 1, coinsToWin do
	print("Coin number", count)
end

-- Uma tabela guarda uma lista de valores; este loop visita cada um em ordem
local colours = { "Red", "Green", "Blue" }
for position, colour in colours do
	print(position, colour) --> 1 Red, depois 2 Green, depois 3 Blue
end

O Output deve mostrar estas oito linhas, misturadas com mensagens do próprio Studio. Quando o print recebe mais de um valor, ele coloca um espaço entre eles. Com Show Context e Show Source ligados, cada linha também vem marcada como Server e FirstScript com o número da linha. Os textos estão em inglês porque são as strings do código.

Coin Run: collect 3 coins to win
That is a short game
Coin number 1
Coin number 2
Coin number 3
1 Red
2 Green
3 Blue

Ligue cada linha ao código que a imprimiu. Você vai fazer o mesmo com mensagens de erro depois, então vale criar o hábito agora.

O FirstScript usa só Luau puro, sem objetos do Roblox, então também roda no Luau playground grátis no seu navegador. Mude um valor lá e rode de novo para ver o que muda.

Todo bloco que abre com function, if, for ou while fecha com end. Um end faltando impede o script inteiro de rodar; ler os erros mostra a mensagem que aparece.

Passo 2: Mude uma parte com um script

Scripts ficam úteis quando mudam coisas no mundo. As configurações que você vê na janela Properties, como Color, Transparency ou Anchored de uma parte, são propriedades, e um script também pode defini-las.

1. Na aba Home, clique em Part. O Studio adiciona um bloco ao Workspace. O nome dele não importa.
2. No Explorer, passe o mouse sobre a parte nova, clique em + e insira um Script. Renomeie para ColourChanger e troque o conteúdo pelo código abaixo.
3. Aperte Play. A parte fica vermelha, depois azul, depois verde, mudando uma vez por segundo, e recomeça.

-- Script dentro de uma Part no Workspace, chamado ColourChanger.
-- Scripts mudam as mesmas propriedades que você vê na janela Properties.
-- Este dá uma cor nova à sua parte a cada segundo, para todos os jogadores.

local part = script.Parent :: BasePart -- a parte em que este script está

local colours = {
	Color3.fromRGB(255, 85, 85), -- vermelho
	Color3.fromRGB(85, 170, 255), -- azul
	Color3.fromRGB(85, 255, 127), -- verde
}

part.Anchored = true -- uma parte ancorada fica onde você a colocou

local index = 1
while true do
	part.Color = colours[index]
	index = index % #colours + 1 -- 1, 2, 3, depois volta para 1
	task.wait(1) -- pausa de um segundo (o antigo wait() está obsoleto)
end

• script.Parent é o objeto em que o script está, aqui a parte. Arraste o script para outra parte e ele passa a mudar aquela parte.
• :: BasePart é um cast de tipo. Ele diz ao Script Editor que o pai é uma parte, para conferir as propriedades que você usa nele. O Luau só usa tipos para avisos e sugestões, então o cast não muda o que a linha faz.
• part.Color e part.Anchored são as mesmas propriedades da janela Properties, com os mesmos nomes. A Roblox usa a grafia americana, então a propriedade é Color mesmo o script se chamando ColourChanger.
• Anchored = true mantém a parte parada: a referência da Roblox diz que uma parte ancorada nunca se move por gravidade, colisões ou qualquer outra física.
• colours[index] lê um item da lista. #colours é o tamanho da lista, 3, e % dá o resto da divisão, então index % #colours + 1 conta 1, 2, 3, 1, 2, 3.
• while true do repete para sempre, e por isso o task.wait(1) de dentro importa. A documentação da Roblox diz para sempre colocar uma pausa como task.wait() em um loop infinito: sem ela, o jogo trava e o Studio fecha.

O ColourChanger é um Script, então roda no servidor, e todos os jogadores no jogo veem a mesma cor ao mesmo tempo. O Passo 4 mostra o outro tipo de script.

Passo 3: Reaja a um jogador com um evento

A maior parte do código de jogo espera algo acontecer: um jogador entra, uma parte é tocada, um botão é clicado. A Roblox chama isso de eventos. Para rodar código quando um deles dispara, você conecta uma função a ele.

1. Insira outra Part e renomeie para exatamente Pad, com P maiúsculo. Deixe direto no Workspace, não dentro de uma pasta ou de um modelo, porque o LocalScript do Passo 4 procura por ela lá.
2. Faça dela uma plataforma plana em que dá para pisar, por exemplo definindo o Size como 6, 1, 6 na janela Properties. Coloque no chão perto da SpawnLocation e marque Anchored para ela ficar parada.
3. Passe o mouse sobre Pad, clique em +, insira um Script, renomeie para TouchPad e cole o código abaixo.
4. Aperte Play e pise na plataforma. Ela fica amarela por 2 segundos, e o Output diz o seu nome.

-- Script dentro de uma Part no Workspace chamada Pad, script chamado TouchPad.
-- Eventos: quando um jogador pisa na plataforma, ela brilha amarela e o Output diz quem foi.
-- Um debounce impede que rode várias vezes por segundo enquanto ele fica em cima.

local Players = game:GetService("Players")

local pad = script.Parent :: BasePart
local COOLDOWN_SECONDS = 2

local normalColour = pad.Color
local busy = false

local function onTouched(otherPart: BasePart)
	if busy then
		return -- ainda esperando o tempo de recarga do último toque
	end
	-- O personagem é o Model que contém a parte do corpo (ou o chapéu) que tocou a plataforma
	local character = otherPart:FindFirstAncestorOfClass("Model")
	local player = character and Players:GetPlayerFromCharacter(character)
	if not player then
		return -- uma parte solta ou um NPC tocou, não um jogador
	end

	busy = true
	print(`{player.Name} stepped on the pad`)
	pad.Color = Color3.fromRGB(255, 220, 0)
	task.wait(COOLDOWN_SECONDS)
	pad.Color = normalColour
	busy = false
end

pad.Touched:Connect(onTouched)

Por que a plataforma precisa de um debounce

A página de debounce da Roblox avisa que o Touched dispara várias vezes em sequência rápida conforme as partes fazem contato, e um personagem andando tem várias partes do corpo. Sem uma checagem, um passo na plataforma poderia imprimir muitas linhas e reiniciar o brilho amarelo de novo e de novo.

A variável busy é o debounce. O primeiro toque a define como true, e todo toque nos 2 segundos seguintes chega em if busy then return end e para. Depois de task.wait(COOLDOWN_SECONDS), a plataforma volta ao normal e busy volta a false. COOLDOWN_SECONDS está em maiúsculas porque é uma configuração que não muda enquanto o jogo roda, o padrão de nomes que a Roblox sugere para constantes.

Esta plataforma tem um debounce para todo mundo, então um segundo jogador que pisar dentro desses 2 segundos é ignorado. Isso serve para uma plataforma que brilha. Uma plataforma que dá recompensas deve ter um tempo de recarga para cada jogador, como faz a plataforma de moedas do guia de leaderboard (em inglês).

Passo 4: Seu primeiro LocalScript, e por que ele é diferente

Um jogo rodando é um servidor mais um cliente para cada jogador. Tudo até aqui foi um Script, que roda no servidor, então as alterações chegam a todos os jogadores. Um LocalScript roda no dispositivo de um jogador. Teclas, câmera e menus na tela são tratados ali, porque só aquele dispositivo sabe deles.

1. No Explorer, abra StarterPlayer, passe o mouse sobre StarterPlayerScripts, clique em + e insira um LocalScript. Renomeie para MyFirstLocalScript e cole o código abaixo.
2. Aperte Play. O Output mostra Hello, e o seu nome, marcado como Client.
3. Clique na visão do jogo e aperte E. A plataforma fica transparente. Aperte E de novo para voltar.
4. Com o teste ainda rodando, clique no botão Client/Server nos controles de teste do Studio para trocar para a cópia do jogo do servidor. Lá a plataforma está sólida: o servidor nunca soube da mudança.

-- LocalScript em StarterPlayer > StarterPlayerScripts chamado MyFirstLocalScript.
-- Um LocalScript roda no próprio dispositivo de um jogador. Aperte E: a Pad fica transparente
-- só na sua tela, porque uma mudança em uma parte feita aqui não chega ao servidor nem a mais ninguém.

local Players = game:GetService("Players")
local UserInputService = game:GetService("UserInputService")

local player = Players.LocalPlayer
print(`Hello, {player.Name}`) -- aparece no Output, marcado como Client

UserInputService.InputBegan:Connect(function(input: InputObject, gameProcessed: boolean)
	if gameProcessed then
		return -- a tecla foi usada para outra coisa, como digitar no chat
	end
	if input.KeyCode == Enum.KeyCode.E then
		local pad = workspace:FindFirstChild("Pad")
		if pad and pad:IsA("BasePart") then
			pad.Transparency = if pad.Transparency == 0 then 0.6 else 0
		end
	end
end)

• Players.LocalPlayer é o jogador cujo dispositivo está rodando o script. A Roblox o define só para LocalScripts e os ModuleScripts que eles usam com require, então o código do servidor não pode usá-lo.
• UserInputService.InputBegan dispara quando o jogador começa a apertar uma tecla, clicar ou tocar. gameProcessed é true quando o motor já usou essa entrada, por exemplo um clique em um botão ou uma tecla digitada na barra do chat, então o script ignora.
• workspace:FindFirstChild("Pad") devolve o filho chamado Pad, ou nil se não houver. pad:IsA("BasePart") confere se é mesmo uma parte antes de o script mudar a Transparency.
• if pad.Transparency == 0 then 0.6 else 0 é uma expressão if: ela escolhe um de dois valores. Transparency 0 é totalmente visível e 1 é invisível.
• Um script de correr com Shift (em inglês) é um bom segundo LocalScript: ele escuta uma tecla e muda a WalkSpeed do seu personagem.

O que um trapaceiro consegue mudar

Considere que um trapaceiro controla tudo no próprio dispositivo. Ele pode rodar os próprios LocalScripts e mudar os seus, então pode deixar a plataforma transparente, ou qualquer outra coisa, na tela dele. Aqui isso é inofensivo: a transparência é só visual e fica no dispositivo dele. É também o motivo de tudo o que importa ser decidido por um Script no servidor.

Um Script de servidor também não é seguro automaticamente. O TouchPad roda no servidor, mas o dispositivo de cada jogador controla a física do próprio personagem, e a documentação de segurança da Roblox lista manipular quando o Touched dispara, ou impedir que ele dispare, entre as coisas que um cliente pode fazer com as partes que controla. Para uma plataforma que brilha, isso não importa. Para uma plataforma que paga, confira também algo que o próprio servidor controla, como a regra do guia de obby (em inglês) de que os checkpoints só contam em ordem.

Passo 5: Teste os quatro scripts juntos

1. Limpe o Output com Ctrl+K (⌘K no Mac) e aperte Play (F5). O Output mostra as oito linhas do FirstScript marcadas como Server, e a sua linha Hello marcada como Client. A parte do ColourChanger muda de cor a cada segundo.
2. Pise na plataforma. Ela fica amarela por 2 segundos e o Output mostra o seu nome e "stepped on the pad" uma vez. Continue andando em cima dela: uma linha nova aparece no máximo uma vez a cada 2 segundos, não toda vez que o Touched dispara.
3. Aperte E. A plataforma vai para Transparency 0,6. Aperte E de novo e ela fica sólida.
4. Aperte Stop. No menu de teste, escolha Server & Clients, defina 2 clientes e aperte Play (ou F7). O Studio abre uma janela de servidor e duas de cliente. Em um cliente, aperte E: a plataforma fica transparente ali, enquanto o outro cliente e o servidor ainda a mostram sólida. Aperte End Session quando terminar.
5. Quebre algo de propósito. Renomeie Pad para Pad2 e jogue. Pisar nela ainda a deixa amarela, porque o TouchPad acha a parte com script.Parent, não pelo nome. Apertar E agora não faz nada, e não há erro: FindFirstChild("Pad") devolveu nil, e a checagem if pad and ... pulou o resto em silêncio. Adicione print(pad) na linha depois do FindFirstChild, jogue e aperte E: o Output mostra nil. Um print assim é o jeito mais rápido de descobrir por que um script não faz nada. Pare, apague a linha do print e renomeie a parte de volta para Pad.

Onde ficam os scripts

O lugar onde um script fica decide se ele roda ou não, e o Studio não avisa quando ele nunca vai rodar. Para os scripts que você vai escrever a seguir:

A página de locais de scripts da Roblox recomenda não colocar scripts direto dentro de partes no Workspace: marque as partes com tags e trabalhe com elas a partir de um único ModuleScript usando CollectionService. Um script dentro de uma parte ainda é o jeito mais fácil de começar, e serve para um ou dois objetos enquanto você aprende. O guia de portas mostra o padrão com tags, com um script para todas as portas, e o guia de cliente e servidor tem a tabela completa de quais contêineres rodam quais scripts (em inglês).

Quando algo dá errado: leia o Output

Os erros aparecem no Output em vermelho. Cada um começa dizendo onde aconteceu, o nome completo do script e o número da linha, e depois diz o que deu errado. Clique no erro e o Studio abre aquele script naquela linha. Por exemplo, se você apagasse a checagem if not player do TouchPad e uma parte solta caísse na plataforma, o Output mostraria:

Workspace.Pad.TouchPad:22: attempt to index nil with 'Name'

Erros na forma como o código está escrito, como um end faltando, aparecem antes de você apertar Play: o Script Editor sublinha em vermelho, e a janela Script Analysis (o botão Analysis na aba Script) lista todos. Um script com um erro desses não roda nada, nem as linhas acima dele.

Quando um script não faz nada e o Output também não mostra nada, normalmente ele está em um lugar onde nunca roda, ou esperando um evento que nunca dispara. O guia de erros de script tem uma lista para scripts silenciosos e se aprofunda em como ler o Output (em inglês).

O que os tutoriais de scripting antigos fazem diferente

Se você também aprende com vídeos e posts em fóruns, vai encontrar padrões antigos. Estes são os que importam, com o motivo de cada um ser um problema.

Prática: três mudanças para tentar

Mudar código ensina mais do que ler. Tente estas no seu próprio jogo, uma de cada vez, e aperte Play depois de cada uma.

• Faça a plataforma dar um ponto. Adicione o script Leaderstats do Passo 1 do guia de leaderboard (em inglês). Depois, no TouchPad, depois de busy = true, ache a pasta leaderstats do jogador e some 1 ao valor Coins. Dica: player:FindFirstChild("leaderstats"), depois leaderstats:FindFirstChild("Coins"), depois coins.Value += 1. A plataforma de moedas do guia de leaderboard é uma versão pronta, com tempo de recarga para cada jogador.
• Faça o ColourChanger mudar a transparência também. Faça o ColourChanger mudar a Transparency da parte a cada segundo também. Dica: adicione uma segunda tabela de números entre 0 e 1, como { 0, 0.3, 0.6 }, e defina part.Transparency a partir dela na linha depois de part.Color, usando o mesmo index.
• Imprima a cor da plataforma. Faça o MyFirstLocalScript imprimir a Color da plataforma quando você apertar E. Dica: print(pad.Color) dentro do bloco if pad and pad:IsA("BasePart"). Aperte E enquanto a plataforma está amarela: o cliente vê a cor que o servidor definiu, porque mudanças feitas no servidor chegam a todos os clientes.

O que aprender a seguir

Agora você já usou as peças de que a maioria dos scripts de jogo é feita. Uma boa ordem para o que vem a seguir (guias em inglês, exceto o do primeiro jogo):

1. LocalScript vs Script vs ModuleScript: onde cada tipo de script roda e o que ele pode mudar, com mais detalhes que o Passo 4.
2. RemoteEvents: como um LocalScript pede ao servidor para fazer algo, e como o servidor confere o pedido.
3. Um leaderboard: suas primeiras estatísticas, criadas e mudadas no servidor.
4. Seu primeiro jogo: um percurso curto de moedas com lava, moedas e uma plataforma de chegada, controlado por dois scripts de servidor, e depois publicado.
5. Depois escolha um sistema para adicionar: uma loja com GUI, um sistema de rodadas, checkpoints de obby, uma tela de carregamento ou uma animação ao apertar uma tecla. Quando algo quebrar, o guia de erros de script ajuda a ler a mensagem.

Os tutoriais Coding fundamentals da própria Roblox (em inglês) são um bom complemento: seis séries que vão de variáveis e funções a condicionais, loops, arrays e dicionários até organizar código com ModuleScripts, com pequenos projetos para construir no Studio.

Problemas comuns e soluções

A maioria dos problemas com os primeiros scripts é um nome que não bate, um script no lugar errado ou um loop sem espera. Mantenha o Output aberto enquanto testa.

Destravando com o RoCode

Se você empacar em um script no seu próprio jogo, o RoCode pode lê-lo com você. O RoCode é um agente de IA independente para Roblox Studio, não feito pela Roblox: você escreve em um chat na web, e o plugin dele para o Studio cria e edita os scripts no seu Explorer.

Enquanto você aprende, o modo Ask é o útil: você continua escrevendo os scripts, e o RoCode lê o que já existe e responde suas perguntas sobre isso.

No modo Build, com o plugin 3.9 ou mais recente, o RoCode pode rodar um teste curto e ler os erros, e com o 3.9.11 ou mais recente controlar um personagem de teste para conferir se o jogo funciona, mas ele não tira capturas de tela enquanto o jogo roda, então você ainda pisa na plataforma. Como o RoCode se conecta ao Studio.

Perguntas frequentes

Fontes e leitura extra

• Roblox Creator Docs: Luau (em inglês). o que é o Luau e de onde ele vem
• Roblox Creator Docs: Roblox Studio setup (em inglês). Windows e Mac, e os requisitos do sistema
• Roblox Creator Docs: Output (em inglês). abrir o Output, filtros, Show Context e Show Source
• Roblox Creator Docs: Studio testing modes (em inglês). Play, Run, Stop, o botão Client/Server e Server & Clients
• Roblox Creator Docs: Script Editor (em inglês). onde os scripts novos abrem, e o Script Analysis
• Roblox Creator Docs: Script types and locations (em inglês). onde cada tipo de script roda, e usar tags em vez de colocar scripts nas partes
• Roblox Creator Docs: Script (em inglês). quando um Script começa a rodar
• Roblox Creator Docs: Control structures (em inglês). if, loops, e por que um loop infinito precisa de uma espera
• Roblox Creator Docs: Events (em inglês). Connect, e o que o Touched passa para a sua função
• Roblox Creator Docs: Debounce patterns (em inglês). por que o Touched dispara várias vezes em um contato
• Roblox Creator Docs: wait (em inglês). o wait() global e o task.wait()
• Roblox Creator Docs: Network ownership, movement validation and physics exploits (em inglês). o que um cliente pode fazer com o próprio personagem
• Roblox Creator Docs: Coding fundamentals (em inglês). a série para iniciantes da própria Roblox

Como o código foi verificado: todo script desta página passa no verificador de tipos estrito do Luau com as definições da API do Roblox (luau-lsp, 26 de outubro de 2026). A verificação de tipos pega APIs com nome errado e tipos incorretos, não a lógica do jogo, então teste no Studio antes de publicar.