Um fluxo de trabalho em equipe para projetos Roblox que mantém o código no Git, mantém a arte versionada com pacotes e permite que todos trabalhem sem sobrescrever as alterações uns dos outros.
A versão curta
- Código vive no Git e entra no Studio através do Rojo.
- Arte vive no Roblox como pacotes. Os originais ficam em um lugar de ativos, e as cópias no lugar de desenvolvimento se atualizam automaticamente.
- Todos trabalham em seu próprio lugar de usuário, e depois trazem o trabalho finalizado para o lugar de desenvolvimento compartilhado.
- Estável é uma captura congelada do desenvolvimento para testes de jogo. Produção é o jogo ao vivo.
Lugares
Todos os lugares são de propriedade do grupo do projeto. Sempre verifique se o grupo está selecionado antes de clicar em Publicar Como.
| Lugar | Propósito | Quem altera | Como | Nome |
|---|---|---|---|---|
| Usuário | Seu espaço de trabalho pessoal do dia a dia, copiado do Dev | Você | Rojo connect + Studio | USER / [Nome] - [Projeto] - [Nível] |
| Dev | Combinação compartilhada e instável do trabalho de todos | Todos, após revisão | Rojo connect para código, Team Create para arte | DEV - [Projeto] |
| Ativo | Os pacotes originais: personagens, kits de construção, decoração de cenários | Artistas | Editar + Publicar como Pacote | ASSET / [Projeto] - [Nível] |
| Estável | Captura congelada do Dev, usada para testes de jogo | Apenas o script de implantação | Automatizado | STABLE / [Projeto] |
| Produção | O jogo público | Proprietário da liberação, com aprovação | Copiado do Estável | [Projeto] |
Onde as coisas vão
Rojo está configurado como parcialmente gerenciado: o Git possui o código e a configuração, e o arquivo do lugar possui a arte e o nível. Cada local de tempo de execução (ReplicatedStorage, ServerScriptService) tem duas pastas de conteúdo:
| O que | Onde | Fonte da verdade |
|---|---|---|
| Código (sistemas, bibliotecas) | src/… no repositório | Git |
| Configuração e definições tipadas (itens, missões, sons, mecanismos) | src/…/ManagedContent/ | Git |
| Arte e qualquer coisa com MeshParts | …/Content, como pacotes | O arquivo do lugar e o lugar de ativos |
| Layout do nível, iluminação, terreno | Workspace / Lighting no lugar de Dev | O arquivo do lugar |
ManagedContent: Git é a fonte da verdade
- Rojo o reconstrói a partir do disco, então edições do Studio são sobrescritas na próxima sincronização. Edite os arquivos no disco.
- Os arquivos são módulos .luau, descritores .model.json ou instâncias .rbxmx.
- Para mover algo que você construiu no Studio para o ManagedContent:
- Clique com o botão direito e escolha Salvar como Arquivo → .rbxmx. O formato XML fornece diffs legíveis, ao contrário do binário .rbxm.
- Coloque o arquivo em ManagedContent/, e então faça o commit.
- Use-o para qualquer coisa que o código leia como configuração. A revisão de código e o histórico do Git então cobrem isso.
Conteúdo: o arquivo do lugar é a fonte da verdade
- Rojo o ignora, e não há arquivos no disco, então o autocompletar do editor não pode vê-lo.
- É necessário para MeshParts, porque Rojo não pode sincronizá-los.
- Use-o para arte que os artistas editam no Studio: props, personagens, VFX, cenografia.
- Nunca coloque configuração de código aqui. Isso se torna invisível para revisão e diffs.
- O único histórico é o histórico de versões do lugar do Roblox, então publique o Dev regularmente.
Arquivo do projeto
Diga ao Rojo para deixar o Content em paz com $ignoreUnknownInstances:
"ReplicatedStorage": {
"$path": "src/ReplicatedStorage",
"Content": {
"$className": "Folder",
"$ignoreUnknownInstances": true
}
}Layout do repositório:
src/
├── ReplicatedStorage/ # compartilhado + cliente
│ ├── Systems/
│ ├── Libraries/
│ └── ManagedContent/
└── ServerScriptService/ # apenas servidor, não replicado
├── Systems/
├── Libraries/
└── ManagedContent/Configuração (uma vez por projeto)
- Clone o repositório e instale a ferramenta. Usamos Rokit: execute rokit install para obter rojo, selene, StyLua, luau-lsp e lune.
- Crie seu lugar de Usuário:
- Abra o lugar de Dev.
- Escolha Arquivo → Publicar Como, selecione o grupo do projeto e crie um novo lugar chamado USER / [Nome] - [Projeto] - [Nível].
- Feche o Dev e abra seu novo lugar.
- Conecte o Rojo:
- Abra o repositório em seu editor e execute rojo serve.
- No Studio, clique em Conectar no plugin Rojo.
Seu lugar de Usuário é uma cópia do Dev, então seus pacotes permanecem vinculados. Eles se atualizam para a versão mais recente cada vez que você abre o lugar.
Engenheiros: o ciclo de código
- Crie um branch a partir do main.
- Atualize seu lugar de Usuário a partir do Dev, para que você comece com o layout e a arte mais recentes:
- Abra o lugar de Dev.
- Escolha Arquivo → Publicar Como, selecione o grupo do projeto e escolha seu lugar de Usuário existente para sobrescrevê-lo.
- Trabalhe em seu lugar de Usuário com rojo serve conectado.
- Execute stylua (formatação) e selene (linting) antes de abrir um PR.
- Abra um PR e faça-o revisar.
- Uma vez aprovado, mescle para o main.
- Sincronize o Dev:
- Execute git checkout main && git pull.
- Abra o lugar de Dev, execute rojo serve e conecte.
- Se sua alteração precisar de mudanças de layout no lugar, como novos atributos ou ativos de espaço reservado, adicione-os ao Dev também. Rojo só sincroniza código e ManagedContent, então não os traz.
Nunca edite manualmente um script gerenciado pelo Rojo ou ManagedContent no Studio. A próxima sincronização o apaga.
Artistas: o ciclo de ativos
Alterando um ativo existente
- Abra o lugar de Ativos e edite o pacote original.
- Clique com o botão direito e escolha Publicar como Pacote.
- As cópias no Dev recebem a alteração:
- Cópias com AutoUpdate ativado se atualizam na próxima vez que alguém abrir o Dev.
- Se o Dev já estiver aberto, clique com o botão direito em uma cópia e escolha Obter Último Pacote. Você também pode usar Atualizar Todos para atualizar cada lugar no jogo.
- Opcionalmente, adicione uma nota de versão em Detalhes do Pacote → Versões.
Adicionando um novo ativo
- Construa-o no lugar de Ativos. Agrupe-o como um Modelo, mesmo que seja um único objeto, para que você possa adicionar filhos mais tarde sem quebrar o pacote.
- Clique com o botão direito e escolha Converter em Pacote.
- Defina Propriedade para o grupo do projeto. A propriedade não pode ser transferida depois.
- Selecione seu PackageLink e ative AutoUpdate.
- Adicione-o ao Dev: no Toolbox, vá para Criações → Pacotes de Grupo, insira-o e coloque-o no Workspace ou Content.
Trabalho de layout e nível
- Organize as coisas em seu lugar de Usuário.
- Uma vez que seu líder aprove, copie as alterações para o Dev. Use o Team Create no Dev para passes de layout compartilhados.
Regras de Pacote
- Edite pacotes apenas no lugar de Ativos. Se você editar uma cópia no Dev, ela será marcada como modificada e parará de se atualizar automaticamente. Para corrigir uma edição acidental, clique com o botão direito e escolha Desfazer Alterações no Pacote.
- Nunca exclua ou mova um PackageLink. Fazer isso transforma a cópia de volta em um modelo simples.
- Pacotes aninhados: publique o pacote interno primeiro, depois o externo.
- Revertendo: vá para Detalhes do Pacote → Versões, escolha uma versão anterior e clique em Enviar.
- Comparando versões: clique com o botão direito no pacote e escolha Opções do Pacote → Comparar Versões do Pacote.
- AutoUpdate está desativado por padrão. Ative AutoUpdate no PackageLink de uma cópia para que ela se atualize automaticamente, ou deixe desativado para atualizar a cópia manualmente.
- Acesso: compartilhe pacotes com o grupo para que toda a equipe possa usá-los e editá-los. Veja privacidade de ativos.
Lançamentos: Dev → Estável → Produção
Dev → Estável (script de implantação)
Escreva um pequeno script de implantação; Lune funciona bem para isso. Execute-o em um cronograma ou antes de cada teste de jogo. Ele deve:
- Baixar o lugar atual do Dev, para que inclua o Conteúdo, Workspace e iluminação.
- Remover todos os PackageLink. Os pacotes se tornam modelos simples, então o Estável é congelado e não mudará quando os artistas publicarem novas versões de pacotes.
- Publicar o resultado no lugar Estável com a API de publicação de lugares Open Cloud. Você precisa de uma chave de API com a permissão ativos e acesso Ler e Escrever, além do ID do lugar.
Os testadores recebem uma versão estável enquanto a equipe continua trabalhando no Dev. Ninguém edita o Estável manualmente.
Estável → Produção
O proprietário da liberação copia o Estável para a Produção, e somente com aprovação. A Produção está ao vivo, então ninguém mais a toca.
Comunicação
Dê a cada projeto um canal geral, um canal de engenharia (links de PR, discussão técnica) e um canal de arte (WIPs, revisões).