Rojo totalmente gerenciado

*Este conteúdo é traduzido por IA (Beta) e pode conter erros. Para ver a página em inglês, clique aqui.

Um fluxo de trabalho em equipe para projetos Roblox onde tudo vive no Git: código, configuração, arte e layout de níveis. Os lugares são construídos a partir do repositório, nunca editados manualmente, e cada build pode ser rastreada até um commit.

Como isso muda o papel do Studio

Esse fluxo de trabalho trata o Roblox Studio como exatamente duas coisas:

  1. Um alvo de implantação. O Rojo monta o arquivo de lugar .rbxl a partir do repositório. O Studio o abre, executa e publica, mas o lugar nunca é a fonte da verdade.
  2. Uma ferramenta para construir modelos .rbxm. Você constrói ou edita um ativo ou uma área no Studio, depois exporta para o repositório com Salvar como arquivo. O Rojo junta os arquivos exportados no lugar.

O repositório, e não o Studio, define como o jogo é montado. O arquivo do projeto e o layout da pasta dizem quais arquivos .rbxm vão onde. Você exporta esses arquivos do Studio um por um.

Por causa disso, os fluxos de trabalho habituais do Studio não se aplicam:

  • Sem Team Create. Ninguém co-edita um lugar compartilhado. A colaboração acontece através de branches e PRs.
  • Sem edição iterativa de mundo em um lugar ao vivo. Você não pode construir um nível ao longo do tempo em Dev e salvar o lugar. Qualquer edição que não seja exportada para um .rbxm e comitada é descartada na próxima build.
  • Sem pacotes. O Git fornece a versionação e compartilhamento que os pacotes teriam.

Se sua equipe depende do Team Create e da edição de níveis no lugar, use o fluxo de trabalho Rojo + Pacotes em vez disso.

A versão curta

  • Código, configuração, arte e níveis vivem no Git sob src/. As peças de arte e nível são arquivos .rbxm.
  • Rojo constrói o lugar a partir do repositório. O código itera ao vivo com rojo serve. As mudanças de arte entram ao reconstruir o lugar.
  • Todos trabalham em seu próprio lugar de Usuário e submetem mudanças através de PRs.
  • CI constrói e publica Dev em cada merge para main, e Stable a partir de tags de lançamento.
  • Prod é o jogo ao vivo.

Lugares

Todos os lugares são de propriedade do grupo do projeto.

LugarPropósitoQuem o alteraComoNome
UsuárioSeu espaço de trabalho pessoal, construído a partir de sua branchVocêrojo build + rojo serveUSER / [Nome] - [Projeto] - [Nível]
DevÚltimo main, usado para testes em equipeApenas CIConstruído e publicado em cada mergeDEV - [Projeto]
StableUma build marcada, usada para testes de jogoApenas CIConstruído e publicado a partir de uma tag de lançamentoSTABLE / [Projeto]
ProdO jogo públicoProprietário do lançamento, com aprovaçãoCI publica uma build Stable aprovada[Projeto]

Nunca edite Dev ou Stable manualmente. A próxima publicação do CI os sobrescreve. Se algo precisar ser alterado, mude no Git.

Onde as coisas vão

O queOndeFormato
Código (sistemas, bibliotecas)src/…/Systems, src/…/Libraries.luau
Configuração e definições tipadassrc/…/ManagedContent/.luau, .model.json
Ativos de arte (props, peças de kit, personagens, VFX)src/…/ManagedContent/Art/.rbxm, um arquivo por ativo
Layout de nívelsrc/Workspace/Areas/.rbxm, um arquivo por área
Configurações de iluminação, Workspace e serviçosdefault.project.json$properties
Arte fonte (FBX, PSD, texturas)Git LFS ou PerforceFormatos nativos

Algumas regras para organizar arquivos:

  • Um arquivo por ativo ou área mantém os diffs pequenos e os conflitos de merge raros. O nome do arquivo se torna o nome da instância no lugar construído.
  • Use .rbxm para arte e níveis. Arquivos binários são muito menores que XML quando contêm malhas. Use rbx-merge para diffs e merges; veja abaixo.
  • Toda configuração deve estar no Git. Um lugar construído contém apenas o que está no repositório. Configurações como Iluminação, Workspace.StreamingEnabled e Players.CharacterAutoLoads vão no arquivo do projeto. Qualquer coisa definida apenas no Studio é perdida na próxima build.
  • Terreno é binário, e o Rojo não pode sincronizá-lo ao vivo. Mantenha-o em seu próprio arquivo, de propriedade de uma pessoa. Confirme que ele sobrevive a um rojo build antes de confiar nele.

Arquivo do projeto

{
"name": "MeuJogo",
"tree": {
"$className": "DataModel",
"ReplicatedStorage": { "$path": "src/ReplicatedStorage" },
"ServerScriptService": { "$path": "src/ServerScriptService" },
"Workspace": {
"$path": "src/Workspace",
"$properties": { "StreamingEnabled": true }
},
"Lighting": {
"$properties": { "Technology": "Future", "ClockTime": 14 }
}
}
}

Layout do repositório

src/
├── ReplicatedStorage/
│ ├── Systems/
│ ├── Libraries/
│ └── ManagedContent/
│ ├── ItemDefinitions/
│ └── Art/
│ ├── Props/Crate.rbxm
│ └── Characters/Hero.rbxm
├── ServerScriptService/
│ ├── Systems/
│ └── ManagedContent/
└── Workspace/
└── Areas/
├── Town.rbxm
└── Forest.rbxm

Por que a arte é reconstruída, não sincronizada ao vivo

A sincronização ao vivo do Rojo (rojo serve) passa pela API do plugin do Studio, e essa API não pode definir algumas propriedades: MeshPart.MeshId, terreno e partes CSG. O rojo build escreve o arquivo do lugar diretamente e não tem essa limitação. Veja Detalhes da sincronização do Rojo.

Então, as regras são:

  • Mudanças de código e configuração: rojo serve + Conectar, como de costume.
  • Mudanças de arte e nível: reconstrua o lugar com rojo build, depois reabra-o.

Configuração (uma vez por projeto)

  1. Clone o repositório e instale a ferramenta com Rokit: execute rokit install.
  2. Configure o rbx-merge para que os arquivos .rbxm sejam diffs e merges corretamente:
    • Uma vez por repositório, uma pessoa executa isso e comita o resultado: rbx-merge install --write-gitattributes.
    • Uma vez por clone, todos executam rbx-merge install, depois rbx-merge doctor para verificar se funcionou.
  3. Configure o armazenamento de arte fonte: instale o Git LFS (git lfs install), ou configure o acesso ao depósito Perforce do projeto.
  4. Construa seu lugar de Usuário:
    • Execute rojo build default.project.json -o build/place.rbxl, depois abra build/place.rbxl no Studio.
    • Para testar com outros, escolha Arquivo → Publicar como, selecione o grupo do projeto e nomeie como USER / [Nome] - [Projeto] - [Nível].
  5. Conecte o Rojo: execute rojo serve, depois clique em Conectar no plugin Rojo do Studio.

Engenheiros: o loop de código

  1. Faça uma branch a partir de main.
  2. Construa seu lugar de Usuário (Passo de Configuração 4) e conecte rojo serve.
  3. Trabalhe normalmente. Quando você puxar mudanças de arte, reconstrua e reabra o lugar.
  4. Execute stylua (formatação) e selene (linting) antes de abrir um PR.
  5. Abra um PR e faça-o revisar. O CI deve executar um teste rojo build em cada PR.
  6. Mescle para main. O CI publica a nova build em Dev.

Artistas: o loop de ativos

Importando arte fonte

  1. Mantenha os arquivos fonte (FBX, PSD, texturas) no Git LFS ou Perforce.
  2. Importe-os com o Importador 3D do Studio, fazendo upload para o grupo do projeto. Os ativos então pertencem ao grupo, e cada lugar construído a partir do repositório pode usá-los. Veja Privacidade de ativos.
  3. Alterar uma malha ou textura significa fazer upload novamente, o que dá um novo ID de ativo. Atualize a instância que a utiliza e re-salve o .rbxm.

Adicionando ou alterando um ativo

  1. Faça uma branch, construa seu lugar de Usuário e abra-o.
  2. Construa ou edite o ativo no Studio. Mantenha cada ativo como um único Modelo.
  3. Clique com o botão direito, escolha Salvar como arquivo → .rbxm, e salve no seu caminho sob ManagedContent/Art/…. Use o mesmo caminho para sobrescrever um ativo existente.
  4. Reconstrua o lugar e verifique se o ativo está correto.
  5. Comite e abra um PR. Os revisores podem ver o que mudou com git diff, que o rbx-merge transforma em texto legível.
  6. Mescle. O CI publica a mudança em Dev.

Layout de nível

  • Cada área é um .rbxm sob src/Workspace/Areas/.
  • Edite a área em seu lugar de Usuário, depois salve-a de volta com Salvar como arquivo sobre o mesmo arquivo.
  • Reconstruir descarta quaisquer mudanças não salvas do Studio. Salve como arquivo antes de reconstruir ou puxar.
  • Concorde sobre quem possui cada área. Duas pessoas editando a mesma área geralmente terão conflitos.

Colocando ativos em níveis

  • Lugares construídos não têm links no estilo de pacotes. Uma cópia de um ativo colocada em uma área não é atualizada quando você altera o arquivo de ativo original.
  • Opção 1 (recomendada): para peças de kit que você reutiliza muito, coloque marcadores no nível em vez de cópias, por exemplo, uma Parte marcada chamada Crate. Um script troca cada marcador pelo ativo de ManagedContent/Art em tempo de execução. Alterar o arquivo de ativo então atualiza cada colocação.
  • Opção 2: coloque cópias completas e atualize-as manualmente quando o ativo original mudar.

Mesclagem e conflitos

  • rbx-merge mescla arquivos .rbxm instância por instância. Se duas pessoas mudarem coisas diferentes no mesmo arquivo, a mesclagem é concluída sozinha.
  • Se ambos os lados mudarem a mesma propriedade, o Git relata um conflito e o rbx-merge escreve um relatório em .rbxmerge/<file>/conflicts.txt. Para resolvê-lo:
    1. No relatório, defina resolution = ours | theirs | base para cada conflito.
    2. Execute rbx-merge resolve --stash-dir .rbxmerge/<file> --out <file>.
    3. Execute git add <file> e continue a mesclagem.
  • Arte fonte não pode ser mesclada. Use bloqueio de arquivo LFS (git lfs lock) ou checkout exclusivo do Perforce para que apenas uma pessoa edite um arquivo por vez.

CI: construir e publicar

O pipeline precisa de uma chave de API Open Cloud com a permissão assets e acesso Read e Write, além do ID de cada lugar. Armazene-os como segredos do CI.

GatilhoEtapas
Cada PRrojo build, stylua --check, selene. Falhe o PR se algum deles falhar.
Mesclar para mainrojo build -o build/place.rbxl, depois publique-o em Dev.
Tag de lançamentoConstrua o commit marcado e publique-o em Stable.
Lançamento aprovadoPublique a mesma build marcada em Prod.

Cada build vem de um commit, então você pode reconstruir e republicar qualquer versão anterior, incluindo após um lançamento ruim.

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).

Referência

©2026 Roblox Corporation, Roblox, o logotipo Roblox e Powering Imagination estão entre nossas marcas registradas e não registradas nos EUA e em outros países.