O Roblox Studio oferece muitas ferramentas de depuração normalmente encontradas em ambientes de desenvolvimento integrados (IDEs). O depurador é uma ferramenta que ajuda você a inspecionar seus scripts linha a linha enquanto eles são executados. Ele exibe os dados nas janelas Observar, Pilha de chamadas, Pontos de interrupção e Saída para que você os inspecione.
Para desativar e reativar o depurador, abra o menu Configurações do Studio, acione a configuração Depurador habilitado e, em seguida, reinicie o Studio.
Fluxo geral de trabalho
Se você notar um problema na experiência ou deseja verificar se ela funciona como pretende, é possível depurar o código relacionado ao problema da seguinte forma:
Utilize a função Inserir pontos de interrupção nas linhas de códigos que você deseja examinar.
Na guia Script, clique em Jogar ou Executar na guia Teste para iniciar uma sessão de teste de jogo, também conhecida como sessão de depuração.
Quando um script atinge um ponto de interrupção, a sessão de teste pausa. Passe pelo código. Inspecione as janelas Observar, Pilha de chamadas e Saída para ajudar você a diagnosticar e a entender o problema.
Insira pontos de interrupção adicionais nas linhas de código que ainda não foram executadas para inspecionar dados adicionais. Use as funções Desabilitar ou Excluir os pontos de interrupção de que você não precisa mais.
Na guia Script, clique em Parar para encerrar a sessão de depuração.
Repita as etapas anteriores até que você resolva o problema ou encontre a causa raiz. Conforme você aprende o fluxo geral de trabalho, é possível configurar os pontos de interrupção para quebrar somente se determinadas condições forem atendidas para exibir uma mensagem na janela Saída e executar no cliente ou servidor. Para mais informações, consulte Configurações do ponto de interrupção.
Inserir pontos de interrupção
Os pontos de interrupção são os pontos de verificação que pausam ou "quebram" a execução dos seus scripts em linhas específicas. Você pode usar as pausas para inspecionar e depurar sua experiência, observar as variáveis e inspecionar a pilha de chamadas. Os pontos de interrupção são uma das maneiras mais eficazes de depurar funções, portanto, eles são uma das ferramentas de depuração mais importantes. Você pode inserir um ponto de interrupção em qualquer linha de código executável.
Para inserir um ponto de interrupção padrão em uma linha de código, clique com o botão esquerdo na margem direita do número de linha. Você também pode clicar com o botão direito na margem e clicar em Inserir ponto de interrupção. O ponto de interrupção é exibido como um ponto vermelho. Para desativá-lo, clique no ponto.
Passar pelo código
Se você inserir um ponto de interrupção em uma linha de um script, o script pausa antes de executar essa linha. Uma seta amarela chamada "depurador" indica qual linha do código é executada a seguir.
Quando o script pausar, execute o código a seguir, uma linha de cada vez, passando por eles com os botões na guia Script. Os botões também são exibidos no canto superior esquerdo da janela Pilha de chamadas. Conforme você passa pelo código, monitore como sua experiência é alterada enquanto a linha atual é executada.
A tabela a seguir resume as três maneiras de passar pelo código. Para continuar a executar seu código após ter atingido um ponto de interrupção, clique em Retomar na guia Script.
| Botão | Ação | Atalho | Descrição |
|---|---|---|---|
 | Step Into | F11 | O botão Entrar na função move o depurador no código da função na linha atual. Se não houver função na linha atual, o depurador avança para a linha seguinte. |
 | Step Over | F10 | O botão Próxima linha move o depurador para a próxima linha do código, e não se move dentro das funções. |
 | Step Out | Shift + F11 | O botão Sair da função retira o depurador da função atual e da próxima linha do código após a execução da função. Se a linha atual não estiver dentro de uma função, o depurador se move para a linha seguinte. |
Inspecionar o código
Quando um ponto de interrupção pausa a experiência durante o teste de jogo, você pode inspecionar a janela Observar, a janela Pilha de chamadas, a janela Saída e o Editor de script para encontrar informações sobre valores variáveis e execuções de função. Com essas informações, você pode encontrar a causa raiz do problema na sua experiência.
Janela Observar
A janela Observar tem duas abas: Variáveis e Minhas observações. A guia Variáveis mostra as informações sobre as variáveis atuais no escopo e a guia Minhas observações exibe o valor das variáveis ou expressões que você define. Ambas as amostras mostram informações antes da linha ser executada.
A guia Variáveis tem as seguintes colunas:
- Nome – O nome declarado da variável.
- Escopo – O escopo da variável: onde ela pode ser "vista" e acessada, como valor Local, Global ou Upvalue.
- Valor – O valor atual da variável.
- Tipo de dado – O tipo de dado da variável.
A guia Minhas observações tem as seguintes colunas:
- Expressão – A expressão que você deseja observar.
- Valor – O valor atual da expressão.
- Tipo de dado – O tipo de dado da expressão.
Na guia Variáveis, você pode filtrar o escopo das variáveis clicando no ícone do filtro. Você também pode classificar as linhas clicando no nome da coluna. A janela Observar apresenta visualizações expandidas e recolhidas das tabelas.
Para inspecionar o código na janela Observar:
Se a janela Observar não estiver aberta, então clique em Observar na guia Exibir.
Quando a sessão de teste do jogo parar em um ponto de interrupção, pense em como você espera que a linha atual altere os valores das variáveis nesse script.
Conforme você passa pelos códigos, observe como o valor das variáveis mudam na guia Variáveis. Se você quiser observar uma expressão fora da guia Variáveis, abra a guia Minhas observações. Clique em uma linha vazia na coluna Expressão e digite a expressão nela. Se você quiser observar uma variável no Editor de Script, clique com o botão direito e, em seguida, em Adicionar observação.
Compare os valores das variáveis e expressões do que você espera e do que você vê na janela Observar. Se houver uma diferença entre como você espera que as variáveis mudem e como elas realmente mudam, as variáveis ou as funções que interagem com elas podem estar causando problemas ou erros.
Na janela Pilha de chamadas
A janela Pilha de chamadas mostra qual linha do código será executada quando o depurador atingir um ponto de interrupção. A Pilha de chamadas indica qual linha você chama uma função e, se você chamar a função em outras funções, a ordem das chamadas de função e em quais linhas você chama outras funções. A função superior da Pilha de chamadas é a última chamada e a primeira a executar. Você pode usar a Pilha de chamadas para verificar se a ordem das chamadas de função em seus scripts corresponde ao modelo mental das chamadas de função.
Se você tiver vários pontos de interrupção em scripts diferentes, eles podem pausar a sessão de teste do jogo ao mesmo tempo. É possível ir para os pontos de interrupção clicando na seta ao lado do nome do script na janela Pilha de chamadas. Se você clicar em Resumir, você passará por todos os pontos de interrupção que foram interrompidos ao mesmo tempo.
Para inspecionar o código na janela Pilha de chamadas durante uma sessão de depuração:
Se a janela Pilha de chamadas não estiver aberta, clique em Pilha de chamadas na guia Exibir.
Quando a sua experiência em um ponto de interrupção pausar, pense em como você espera que a ordem das execuções de função esteja nesse script.
A Pilha de chamadas mostra a ordem das execuções de função. Se o ponto de interrupção estiver dentro de uma função, a Pilha de chamadas mostra qual função chama uma determinada função, se houver. A Pilha de chamadas também mostra o nome e o número de linha de cada função. Clique na linha para uma função para acessá-la.
Compare a ordem das chamadas de função que você projetou na etapa 2 e a ordem real da etapa 3. Se houver alguma diferença, haverá distinção entre como você espera que o código se comporte e como ele realmente se comporta, causando assim problemas e erros potenciais.
Na janela Saída
A janela Saída, acessível a partir da guia Exibir, exibe erros capturados de execução de scripts, mensagens do Roblox Engine, mensagens de registro dos pontos de log, mensagens de chamadas para print(), e erros de chamadas para warn(). Para mais informações na janela Saída e como customizá-la, consulte Saída.
No Editor de script
O depurador é integrado com o Editor de script. Quando sua experiência pausa em ponto de interrupção em um script, você pode arrastar seu mouse sobre o nome de uma variável para ver o valor. É possível, por exemplo, ver o valor de uma tabela que você passa como um argumento em uma execução de função.
Configurações do ponto de interrupção
É possível configurar os pontos de interrupção para interromper somente se certas condições forem atendidas a fim de expressar uma mensagem na janela Saída e para executar apenas no cliente ou servidor. Você também pode misturar essas configurações juntas para melhor atender às suas necessidades de depuração.
Editar pontos de interrupção
É possível editar a configuração de um ponto de interrupção a qualquer momento, incluindo as sessões de teste do jogo. Se você editar os pontos de interrupção durante uma sessão de teste do jogo, as edições persistem mesmo depois de terminá-la. Você também pode editar um ponto de interrupção que esteja ativamente pausando a sessão de teste do jogo, mas as alterações não se aplicam até a próxima sessão de teste do jogo.
Para editar a configuração de um ponto de interrupção:
Clique com o botão direito no ponto de interrupção e clique em Editar ponto de interrupção.
Na janela Editar ponto de interrupção, configure o ponto de interrupção como você deseja.
Condição, mensagem de registro e opções
Para cada ponto de interrupção, é possível definir sua Condição, Mensagem de registro, Continuar execução, e Contexto.
A condição é a expressão que determina se o ponto de interrupção é ativado. A Condição é opcional. Se a Condição estiver vazia, o ponto de interrupção sempre é ativado. Se a Condição existir, o ponto de interrupção é ativado somente se a condição for verdadeira. Por exemplo, se você quiser que o ponto de interrupção seja ativado somente se a variável for n``42igual, então configure a Condição como n == 42. As condições são úteis para depurar como as funções são executadas quando certas variáveis têm determinados valores ou se você quiser quebrar em certas execuções em um loop.
A Mensagem de registro é a expressão que se expressa na janela Saída quando a condição é verdadeira. O formato da Mensagem de registro é o mesmo que o argumento para uma print()declaração. Configure, por exemplo, a Mensagem de registro como "The value of n:", npara expressar a mesma mensagem que print("The value of n:", n). Você pode adicionar e remover Mensagens de registro sem ter que interromper a execução, ao contrário das declarações de expressão.
A opção Continuar execução determina se o ponto de interrupção pausa o script se ele for ativado. Isso é útil caso haja o desejo de registrar valores de variáveis ou expressões sem interromper a execução. Essa opção é desativada por padrão.
O Contexto de um ponto de interrupção determina se o ponto de interrupção deve ser ativado no Cliente, Servidor ou Editar. Se o contexto for Cliente, o ponto de interrupção é acionado em scripts do lado do cliente. Se o contexto for o Servidor, o ponto de interrupção é acionado em scripts do lado do servidor. Se o contexto for Editar, o ponto de interrupção é acionado ao depurar plugins. Se você clicar em Contexto personalizado, a janela indica o contexto atual.
Pontos de interrupção condicionais e pontos de registro
O Studio oferece variações nomeadas de pontos de interrupção para realizar mais rapidamente a inserção do ponto de interrupção. Para inserir uma variação nomeada, clique com o botão direito na margem à direita do número de linha e clique na variante que você deseja inserir.
Um ponto de interrupção condicional é um ponto de interrupção com uma Condição e Execução contínua desativada. Os pontos de interrupção condicionais pausam o script somente se uma condição for verdadeira, então eles são úteis para depurar a forma como as funções são executadas quando certas variáveis têm certos valores. Os pontos de interrupção condicionais usam os valores das variáveis antes da linha ser executada. Quando você insere um ponto de interrupção condicional, o cursor se concentra na opção Condição para que você realize a configuração rapidamente.
Um ponto de registro é um ponto de interrupção com uma Mensagem de registro e Execução contínua ativada. Os pontos de registro das mensagens na janela Saída sem pausar seus scripts, então eles são úteis para depurar valores de variável. Os pontos de registro usam os valores das variáveis antes da linha ser executada. Quando você insere um ponto de registro, o cursor centra-se na Mensagem de registro para que você a defina rapidamente.
Os pontos de registro são frequentemente mais eficientes para a depuração de variáveis do que as print()declarações porque permitem que você registre mensagens na janela Saída sem ter que interromper ou reiniciar a sessão ativa de teste do jogo. Comparado com as print()declarações , eles mantêm o código limpo durante a depuração e são mais fáceis de remover após terminar a depuração.
Desabilitar pontos de interrupção
Existem muitas maneiras para desativar e reativar um ponto de interrupção:
- Clique no ícone do ponto de interrupção.
- Edite o ponto de interrupção e deixe sua caixa de seleção como Ativada.
- Clique com o botão direito no ícone do ponto de interrupção e clique em Desativar ponto de interrupção ou Ativar ponto de interrupção.
Excluir pontos de interrupção
Para excluir um ponto de interrupção, clique no meio do seu ícone. Você também pode clicar com o botão direito no ícone e clicar em Excluir ponto de interrupção.
Excluir um ponto de interrupção apaga a Condição e a Mensagem de registro. Se você quiser manter a Condição ou Mensagem de registro para a depuração futura, desative o ponto de interrupção.
Janela Pontos de interrupção
A janela Pontos de interrupção exibe todos os pontos de interrupção na sua experiência. Para abrir a janela Pontos de interrupção, clique na guia Exibir na parte superior do Studio e clique em Pontos de interrupção.
A janela Pontos de interrupção tem as seguintes colunas: não rotuladas, script, linha, Linha de origem, Condição, Mensagem de registro e Continuar Execução. As colunas Não rotuladas, Script e Linha sempre são exibidas, mas você pode ativar outras colunas clicando nos três pontos no canto superior direito da janela.
Na coluna não rotulada, o rótulo (x3) indica o número de pontos de interrupção na mesma linha de código, e o ícone indica a configuração do ponto de interrupção. Os pontos de interrupção na mesma linha compartilham a mesma Condição, Mensagem de registro e Continuar Execução, mas variam no contexto. Você pode editar a configuração de um ponto de interrupção na janela Pontos de interrupção. Você pode editar, por exemplo, a Condição de um ponto de interrupção ao editar a área de texto na coluna Condição.
Você pode habilitar e desabilitar os pontos de interrupção clicando no ícone do ponto de interrupção na coluna Ativada. Você também pode clicar nos seguintes botões para ativar, desativar e excluir alguns ou todos os pontos de interrupção.
| Botão | Ação |
|---|---|
 | Desabilitar todos os pontos de interrupção. Se qualquer ponto de interrupção estiver desativado, ative todos eles. |
 | Exclua todos os pontos de interrupção. |
Ícones do ponto de interrupção
O ícone de um ponto de interrupção depende da ativação, de uma condição e de uma mensagem de registro. Se um ponto de interrupção tiver uma mensagem de registro, ela será exibida como um ponto de registro, independentemente de ela ter uma condição.
| Nome | Ícone | Ativado | Condição | Mensagem de registro |
|---|---|---|---|---|
| Ponto de interrupção |  | Sim | Não | Não |
 | Não | Não | Não | |
| Ponto de interrupção condicional |  | Sim | Sim | Não |
 | Não | Sim | Não | |
| Ponto de registro |  | Sim | Talvez | Sim |
 | Não | Talvez | Sim |
Ferramentas de depuração adicionais
Além do depurador, o Studio oferece ferramentas de depuração adicionais para que você corrija problemas e erros na sua experiência.
Barra de comando
A Barra de comando permite que você execute comandos do Luau enquanto a experiência estiver em execução. Está disponível no Studio na guia Exibir e no Console do desenvolvedor.
Console do desenvolvedor
O Console do desenvolvedor fornece um amplo conjunto de detalhes, incluindo a saída do servidor e do cliente, uso de memória, desempenho da rede e mais. Para abrir o Console do desenvolvedor ao testar ou jogar em uma experiência, /consoledigite no chat ou pressione F9. Para mais informações, consulte o Console do desenvolvedor.
Arquivos de registro
Quando um script é gravado ou opera com erros no aplicativo Studio ou do aplicativo do jogador, o aplicativo registra a mensagem em um arquivo de registro no sistema de arquivos local. Esses arquivos estão localizados em locais diferentes no sistema operacional:
- No Windows, os registros estão no diretório %LOCALAPPDATA%\Roblox\logs. Classifique a pasta por data modificada. Os nomes dos arquivos de registro começam com o formato log_XXXXX. Os registros com o mesmo XXXXXvalor são da mesma sessão do Studio.
- No macOS, os registros estão no diretório ~/Library/Logs/Roblox. No Finder, clique no menu Ir, selecione Ir para Pasta naquele diretório e confirme.