Sincronização de Script

Roblox Studio tem um editor de script embutido para editar o código em seu projeto Roblox. O editor inclui recursos principais como linting, verificação de tipo, autocompletar e edição colaborativa.

No entanto, muitos desenvolvedores têm um editor de texto ou ambiente de desenvolvimento integrado (IDE) preferido, como Visual Studio Code, Cursor, Sublime Text ou Notepad++. Ambientes de desenvolvimento populares costumam ter recursos ou plugins que não existem no Studio. Para usar um editor ou IDE externo com o Studio, ative o recurso Sincronização de Script.

A Sincronização de Script funciona sincronizando os scripts em seu modelo de dados com arquivos de texto no seu disco local. As alterações feitas nos arquivos Luau no disco são aplicadas aos scripts no Studio, e vice-versa. Essa sincronização significa que você pode editar um script em um editor externo como o VS Code e ver imediatamente a alteração no Studio.

Quando usar a Sincronização de Script

• Se você deseja usar seu editor de texto preferido ou verificar o código em controle de versão, mas usar o Studio para tudo o mais, a Sincronização de Script é uma boa opção. Ela também funciona com as ferramentas de colaboração integradas do Roblox, que ferramentas de terceiros muitas vezes não oferecem.

  A Sincronização de Script funciona bem com projetos Roblox existentes, pois é um recurso extra em vez de uma mudança total na forma como você gerencia o projeto.

• Se você deseja verificar todo o seu projeto (não apenas o código) em controle de versão ou usar seu sistema de arquivos como a fonte da verdade para seu projeto, ferramentas de terceiros como Rojo são uma escolha melhor.

Configurar a Sincronização de Script

1. No Explorer, selecione uma ou mais pastas que você deseja sincronizar.

2. Clique com o botão direito e selecione Sincronizar para….

   

3. Escolha um diretório no seu computador (ou crie um novo) e clique em Salvar.

4. No Studio, clique com o botão direito na pasta novamente e selecione Sincronização de Script ⟩ Revelar no Explorer (Windows) ou Revelar no Finder (macOS).

5. Abra o diretório no seu editor de texto preferido.

   Alternativamente, clique com o botão direito em um script individual no Studio e selecione Abrir no Editor Externo.

Você pode sincronizar scripts individuais, mas recomendamos fortemente sincronizar pastas; se você sincronizar uma pasta, a Sincronização de Script sincroniza automaticamente suas pastas e scripts filhos, o que permite criar, excluir e renomear scripts sem precisar ativar a sincronização a cada vez.

Depois de configurar a Sincronização de Script, você quase certamente desejará adicionar uma extensão LSP ao seu editor de texto.

Limites

A Sincronização de Script suporta até 10.000 scripts por instância sincronizada de nível superior e até 128 instâncias sincronizadas de nível superior, portanto, ela se adapta a grandes bases de código.

Resolução de conflitos

Ao iniciar ou retomar a sincronização, se houver diferenças entre o Studio e seus arquivos no disco, a Sincronização de Script mostrará um diálogo de resolução detalhado. O diálogo lista quais scripts serão adicionados, modificados ou excluídos de cada lado para que você possa entender o impacto de escolher Manter Studio vs. Manter Disco.

Exclusão seletiva

Quando você exclui um script ou pasta sincronizada no Studio ou no disco, a Sincronização de Script remove apenas scripts Luau e arquivos suportados. Ela não exclui arquivos ou pastas não Luau que não gerencia; ativos não script, como modelos e partes, são preservados mesmo quando você remove ou reorganiza itens sincronizados ao redor deles.

Criação em Equipe

A Sincronização de Script funciona com Criação em Equipe. O Explorer exibe um ícone em instâncias que um colaborador está sincronizando atualmente. Para evitar nomes duplicados, a Sincronização de Script automaticamente adiciona um sufixo numérico ao nome de qualquer nova instância adicionada sob uma árvore que você ou um colaborador está sincronizando.

Evite fluxos de trabalho onde várias pessoas sincronizam o mesmo script e editam os arquivos ao mesmo tempo. A Sincronização de Script continuará a funcionar, mas os colaboradores podem sobrescrever as alterações uns dos outros.

Dicas principais

• A Sincronização de Script sincroniza apenas instâncias Script, LocalScript, ModuleScript e Folder. Todas as outras instâncias em uma pasta sincronizada são ignoradas. Evite sincronizar pastas que contenham scripts junto com outras instâncias.

• Você pode sincronizar pacotes, embora o PackageLink em si não seja gravado no disco.

• Não sincronize scripts que tenham atributos ou tags. A Sincronização de Script ignora esses, o que pode levar à perda de dados se você criar ou excluir scripts ou começar a sincronizar com uma versão mais antiga de seus arquivos no disco.

• A Sincronização de Script requer que os nomes dos scripts sejam compatíveis com seu sistema de arquivos—sem nomes duplicados ou caracteres não suportados. Se o Studio encontrar algum desses problemas, ele gera um erro e pede que você resolva a situação antes de retomar a sincronização.

• Se algum arquivo ou pasta sincronizada mudar enquanto o Studio estiver fechado, o Studio perguntará como você deseja resolver a situação quando você reabrir o lugar.

• Excluir uma instância de nível superior (ou "raiz")—a instância que você inicialmente sincronizou—no seu disco local pode fazer com que o Studio gere um erro. Para excluir uma instância de nível superior:

  1. No Studio, clique com o botão direito no script ou pasta e selecione Sincronização de Script ⟩ Parar Sincronização.
  2. Escolha a opção Excluir arquivo(s) ou Excluir pasta(s) para excluir a instância do seu disco local.
  3. Exclua o script ou pasta no Studio.

  Você pode excluir instâncias filhas no Studio ou no seu disco local sem desativar a sincronização, e a exclusão será sincronizada como você esperaria.

Configurar um servidor de linguagem

Servidores de linguagem oferecem ao seu editor de texto recursos específicos de linguagem, como autocompletar, verificação de tipo, "ir para definição" e mais. Para o VS Code, recomendamos o Servidor de Linguagem Luau.

Extensões do protocolo de servidor de linguagem (LSP) precisam entender a hierarquia do modelo de dados de um projeto para funcionar corretamente. A extensão do VS Code vem com um plugin companion para o Studio (Companheiro do Servidor de Linguagem Luau) que fornece esses dados.

Recomendamos fortemente instalar ambos. Se você usar a extensão do VS Code e o plugin companion do Studio, os recursos de linguagem funcionarão corretamente no VS Code enquanto usa a Sincronização de Script.

Extensões recomendadas

• Roblox Luau LSP e Companheiro do Servidor de Linguagem Luau - Recursos de linguagem (veja acima)
• selene - Análise de código estática (linting)
• StyLua - Formatação automática de código

Regras de sincronização

Ao sincronizar uma instância com filhos com um diretório no disco, o Studio sincronizará automaticamente operações de criação, renomeação, movimentação e exclusão em filhos com os arquivos e pastas correspondentes no disco. Essa abordagem permite que você mantenha seu código sem precisar parar e iniciar a sincronização manualmente em scripts individuais.

No disco, a Sincronização de Script usa as seguintes regras para desambiguar os diferentes tipos de scripts entre si.

Configurações

A Sincronização de Script tem várias configurações na janela de Configurações do Studio (AltS ou ⌥S). As opções padrão são adequadas para a maioria dos casos de uso.