완전 관리되는 Rojo

모든 것이 Git에 존재하는 Roblox 프로젝트를 위한 팀 워크플로우: 코드, 구성, 예술 및 레벨 레이아웃. 장소는 리포지토리에서 빌드되며, 수동으로 편집되지 않으며, 모든 빌드는 커밋에 추적될 수 있습니다.

이것이 스튜디오의 역할을 어떻게 변화시키는가

이 워크플로우는 Roblox Studio를 정확히 두 가지로 취급합니다:

1. 배포 대상. Rojo는 리포지토리에서 .rbxl 장소 파일을 조립합니다. 스튜디오는 이를 열고 실행하며 게시하지만, 장소는 결코 진실의 출처가 아닙니다.
2. .rbxm 모델을 구축하는 도구. 스튜디오에서 하나의 자산이나 하나의 영역을 구축하거나 편집한 다음, 파일로 저장하여 리포지토리에 내보냅니다. Rojo는 내보낸 파일을 장소에 통합합니다.

게임이 조립되는 방식은 스튜디오가 아니라 리포지토리에서 정의됩니다. 프로젝트 파일과 폴더 레이아웃은 어떤 .rbxm 파일이 어디로 가는지를 말합니다. 스튜디오에서 이러한 파일을 하나씩 내보냅니다.

이로 인해 일반적인 스튜디오 워크플로우는 적용되지 않습니다:

• 팀 생성 없음. 아무도 공유 장소를 공동 편집하지 않습니다. 협업은 브랜치와 PR을 통해 이루어집니다.
• 라이브 장소에서의 반복적인 세계 편집 없음. Dev에서 시간을 두고 레벨을 구축하고 장소를 저장할 수 없습니다. .rbxm으로 내보내지 않고 커밋되지 않은 모든 편집은 다음 빌드에서 버려집니다.
• 패키지 없음. Git은 패키지가 제공할 버전 관리 및 공유를 제공합니다.

팀이 팀 생성 및 장소에서 레벨 편집에 의존하는 경우, 대신 Rojo + 패키지 워크플로우를 사용하세요.

간단한 버전

• 코드, 구성, 예술 및 레벨은 src/ 아래의 Git에 존재합니다. 예술 및 레벨 조각은 .rbxm 파일입니다.
• Rojo가 리포지토리에서 장소를 빌드합니다. 코드는 rojo serve로 실시간으로 반복됩니다. 예술 변경 사항은 장소를 재구성하여 반영됩니다.
• 모두 자신의 사용자 장소에서 작업하고 PR을 통해 변경 사항을 제출합니다.
• CI는 main에 병합될 때마다 Dev를 빌드하고 게시하며, 릴리스 태그에서 Stable을 빌드합니다.
• Prod는 라이브 게임입니다.

장소

모든 장소는 프로젝트 그룹에 소속됩니다.

Dev 또는 Stable을 수동으로 편집하지 마세요. 다음 CI 게시가 이를 덮어씁니다. 변경이 필요하면 Git에서 변경하세요.

항목이 위치하는 곳

파일을 구성하기 위한 몇 가지 규칙:

• 자산 또는 영역당 하나의 파일은 차이를 작게 유지하고 병합 충돌을 드물게 만듭니다. 파일 이름은 빌드된 장소에서 인스턴스 이름이 됩니다.
• 예술 및 레벨에는 .rbxm을 사용하세요. 이진 파일은 메시를 포함할 때 XML보다 훨씬 작습니다. rbx-merge를 사용하여 이를 비교하고 병합하세요; 아래를 참조하세요.
• 모든 설정은 Git에 있어야 합니다. 빌드된 장소는 리포지토리에 있는 것만 포함합니다. 조명, Workspace.StreamingEnabled 및 Players.CharacterAutoLoads와 같은 설정은 프로젝트 파일에 있어야 합니다. 스튜디오에서만 설정된 것은 다음 빌드에서 사라집니다.
• 지형은 이진 형식이며, Rojo는 이를 실시간으로 동기화할 수 없습니다. 한 사람의 소유로 별도의 파일에 보관하세요. 의존하기 전에 rojo build가 이를 유지하는지 확인하세요.

프로젝트 파일

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

리포지토리 레이아웃

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

예술이 재구성되는 이유, 실시간 동기화되지 않는 이유

Rojo의 실시간 동기화(rojo serve)는 스튜디오 플러그인 API를 통해 이루어지며, 해당 API는 일부 속성을 설정할 수 없습니다: MeshPart.MeshId, 지형 및 CSG 부품. rojo build는 장소 파일을 직접 작성하며 이러한 제한이 없습니다. Rojo 동기화 세부정보를 참조하세요.

따라서 규칙은 다음과 같습니다:

• 코드 및 구성 변경: rojo serve + 연결, 정상적으로.
• 예술 및 레벨 변경: rojo build로 장소를 재구성한 다음, 다시 엽니다.

설정 (프로젝트당 한 번)

1. 리포지토리를 클론하고 Rokit으로 도구 체인을 설치합니다: rokit install을 실행합니다.
2. rbx-merge를 설정하여 .rbxm 파일이 제대로 비교 및 병합되도록 합니다:

   • 리포지토리당 한 번, 한 사람이 이를 실행하고 결과를 커밋합니다: rbx-merge install --write-gitattributes.
   • 클론당 한 번, 모든 사람이 rbx-merge install을 실행한 다음, rbx-merge doctor를 실행하여 작동 여부를 확인합니다.
3. 소스 아트 저장소를 설정: Git LFS를 설치합니다 (git lfs install), 또는 프로젝트의 Perforce 저장소에 대한 액세스를 설정합니다.
4. 사용자 장소를 빌드합니다:

   • rojo build default.project.json -o build/place.rbxl을 실행한 다음, 스튜디오에서 build/place.rbxl을 엽니다.
   • 다른 사람과 테스트하려면 파일 → 다른 이름으로 게시를 선택하고, 프로젝트 그룹을 선택한 후 USER / [이름] - [프로젝트] - [레벨]로 이름을 지정합니다.
5. Rojo 연결: rojo serve를 실행한 다음, 스튜디오 Rojo 플러그인에서 연결을 클릭합니다.

엔지니어: 코드 루프

1. main에서 브랜치를 만듭니다.
2. 사용자 장소를 빌드하고 (설정 단계 4) rojo serve를 연결합니다.
3. 정상적으로 작업합니다. 예술 변경 사항을 가져올 때, 장소를 재구성하고 다시 엽니다.
4. PR을 열기 전에 stylua (형식 지정) 및 selene (린트 검사)를 실행합니다.
5. PR을 열고 검토를 받습니다. CI는 모든 PR에서 테스트 rojo build를 실행해야 합니다.
6. main에 병합합니다. CI는 새로운 빌드를 Dev에 게시합니다.

아티스트: 자산 루프

소스 아트 가져오기

1. 소스 파일(FBX, PSD, 텍스처)을 Git LFS 또는 Perforce에 보관합니다.
2. 스튜디오의 3D 가져오기 도구를 사용하여 프로젝트 그룹에 업로드합니다. 그러면 자산은 그룹에 속하게 되며, 리포지토리에서 빌드된 모든 장소에서 사용할 수 있습니다. 자산 개인 정보 보호를 참조하세요.
3. 메시나 텍스처를 변경하면 다시 업로드해야 하며, 이는 새로운 자산 ID를 부여합니다. 이를 사용하는 인스턴스를 업데이트하고 .rbxm을 다시 저장합니다.

자산 추가 또는 변경

1. 브랜치를 만들고 사용자 장소를 빌드한 다음 엽니다.
2. 스튜디오에서 자산을 빌드하거나 편집합니다. 각 자산을 단일 모델로 유지합니다.
3. 마우스 오른쪽 버튼을 클릭하고 파일로 저장 → .rbxm을 선택한 다음, ManagedContent/Art/… 아래의 경로에 저장합니다. 기존 자산을 덮어쓰려면 동일한 경로를 사용합니다.
4. 장소를 재구성하고 자산이 올바르게 보이는지 확인합니다.
5. 커밋하고 PR을 엽니다. 검토자는 git diff를 통해 변경된 내용을 확인할 수 있으며, rbx-merge는 이를 읽기 쉬운 텍스트로 변환합니다.
6. 병합합니다. CI는 변경 사항을 Dev에 게시합니다.

레벨 레이아웃

• 각 영역은 src/Workspace/Areas/ 아래의 하나의 .rbxm입니다.
• 사용자 장소에서 영역을 편집한 다음, 파일로 저장하여 동일한 파일에 다시 저장합니다.
• 재구성하면 저장되지 않은 스튜디오 변경 사항이 버려집니다. 재구성하거나 가져오기 전에 파일로 저장하세요.
• 각 영역의 소유자를 합의합니다. 두 사람이 동일한 영역을 편집하면 일반적으로 충돌이 발생합니다.

레벨에 자산 배치

• 빌드된 장소에는 패키지 스타일의 링크가 없습니다. 영역에 배치된 자산의 복사본은 원본 자산 파일이 변경될 때 업데이트되지 않습니다.
• 옵션 1 (권장): 자주 재사용하는 키트 조각의 경우, 복사본 대신 레벨에 마커를 배치합니다. 예를 들어, Crate라는 태그가 있는 파트를 사용합니다. 스크립트가 런타임에 각 마커를 ManagedContent/Art의 자산으로 교체합니다. 자산 파일을 변경하면 모든 배치가 업데이트됩니다.
• 옵션 2: 전체 복사본을 배치하고 원본 자산이 변경될 때 수동으로 업데이트합니다.

병합 및 충돌

• rbx-merge는 .rbxm 파일을 인스턴스별로 병합합니다. 두 사람이 동일한 파일에서 다른 것을 변경하면 병합이 자동으로 완료됩니다.
• 양쪽 모두 동일한 속성을 변경하면, Git은 충돌을 보고하고 rbx-merge는 .rbxmerge/<file>/conflicts.txt에 보고서를 작성합니다. 이를 해결하려면:

  1. 보고서에서 각 충돌에 대해 resolution = ours | theirs | base를 설정합니다.
  2. rbx-merge resolve --stash-dir .rbxmerge/<file> --out <file>를 실행합니다.
  3. git add <file>를 실행하고 병합을 계속합니다.
• 소스 아트는 병합할 수 없습니다. LFS 파일 잠금(git lfs lock) 또는 Perforce 독점 체크아웃을 사용하여 한 번에 한 사람만 파일을 편집할 수 있도록 합니다.

CI: 빌드 및 게시

파이프라인은 자산 권한과 읽기 및 쓰기 액세스가 있는 Open Cloud API 키가 필요하며, 각 장소의 ID도 필요합니다. 이를 CI 비밀로 저장합니다.

모든 빌드는 커밋에서 나오므로, 잘못된 릴리스 후에도 이전 버전을 다시 빌드하고 재게시할 수 있습니다.

커뮤니케이션

각 프로젝트에 일반 채널, 엔지니어링 채널(PR 링크, 기술 논의) 및 아트 채널(WIP, 리뷰)을 제공합니다.

참고

• Rojo 프로젝트 형식
• Rojo 동기화 세부정보
• rbx-merge
• Git LFS
• 자산 개인 정보 보호
• Open Cloud 장소 게시