Roblox Studio Script Sync & Rojo 파일 기반 워크플로우 A-to-Z 종합 가이드
이 문서는 Studio Script Sync (Early Preview)와 Rojo를 함께 활용하여 최적의 개발 워크플로우를 구축하는 완전한 가이드입니다. 실무진·보안팀·개발팀이 바로 적용할 수 있도록 설정법, 명령어, 파일 규칙, 운영 가이드, 보안 점검표까지 모두 포함했습니다.
핵심 요약 (TL;DR)
Script Sync란?
- Studio Script Sync: Roblox Studio에서 스크립트를 로컬 파일과 양방향 자동 동기화하는 베타 기능
- 어디서 켜나: Studio → File → Beta Features → "Studio Script Sync [Early Preview]" 활성화
- 어떻게 쓰나: Explorer에서 스크립트 우클릭 → Start Sync로 디스크 경로 지정
- 제한: 동시 64개 스크립트까지, 폴더 단위는 향후 지원 예정
Rojo란?
- Rojo: "디스크 → Studio" 단방향 동기화 중심 도구. 전체 프로젝트를 파일 시스템 기반으로 관리
- 주의: rbxl/rbxlx 내부 스크립트를 자동으로 바깥 파일로 추출해주지 않음
- 포팅 도구 필요: 기존 게임 → 파일로 분리하려면
rbxlx-to-rojo
나Rostar
사용
워크플로우 권장
- 전체 프로젝트 파일 관리 → Rojo 추천
- 일부 스크립트만 외부 IDE 편집 → Script Sync 적합
- 혼합 워크플로우: Rojo로 전체 구조 관리 + Script Sync로 핵심 스크립트 실시간 동기화
Studio Script Sync 상세 가이드
1. 활성화 방법
- 베타 기능 활성화
Studio → File → Beta Features → "Studio Script Sync [Early Preview]" 체크
- Studio 재시작 권장
- 베타 메뉴가 없다면?
- 점진적 롤아웃 중일 수 있음
- Studio 최신 버전 확인
- 재로그인 시도
2. 사용법
기본 동기화 시작
- Explorer에서 스크립트 선택
- 우클릭 → Start Sync (또는 Sync to Disk)
- 로컬 폴더/파일 경로 지정 (.lua/.luau 확장자)
- 시작 시점에는 Studio 상태가 디스크를 덮어씀
다중 선택
- Shift/Ctrl 클릭으로 여러 스크립트 선택 가능 (최대 64개)
- 한 번에 동기화 설정 가능
관리 메뉴
- Resume Sync: 중단된 동기화 재개
- Stop Sync: 동기화 중단
- Show synced file location: 연결된 파일 위치 확인
3. 자동 재개 및 충돌 정책
Studio 재시작 시 동기화 상태를 자동으로 재개할 수 있으며, 파일과 Studio 내용이 다를 때의 처리 방식을 설정할 수 있습니다.
Studio Settings → Script Sync → "Resume conflicted sync on place open"
충돌 정책 옵션
- Always keep Studio (Studio 우선)
- Studio의 버전이 항상 파일 시스템의 파일을 덮어씀
- Always keep local (로컬 우선)
- 파일 시스템의 버전이 항상 Studio의 스크립트를 덮어씀
- Do not resume (수동 재개 - 기본값)
- 충돌하는 스크립트는 오류 상태로 남김
- 컨텍스트 메뉴의 "Resume Sync"로 수동 재개
4. 현재 제한사항
- ❌ 폴더 단위 동기화 미지원 (향후 계획)
- ❌ 동시 64개 스크립트 제한
- ❌ 디스크 상태에서 동기화 시작 미지원 (향후 계획)
- ✅ Team Create, Drafts, Local 모두 지원
- ✅ 양방향 자동 동기화 (설정된 스크립트 한정)
5. 향후 로드맵
- 폴더 + 하위 스크립트 동기화 (수천 개 스크립트 지원)
- 디스크 상태에서 동기화 시작
- Source map/LSP 지원 (Luau LSP와 연동)
Rojo 상세 가이드
1. Rojo의 핵심 개념
Rojo는 "파일 시스템이 진실의 원천(Source of Truth)"이라는 철학으로 설계된 도구입니다.
주요 특징
- 디스크 → Studio 단방향 동기화 (주 기능)
- 전체 프로젝트를 파일 시스템으로 관리
- CI/CD, 빌드 시스템과의 완벽한 통합
- 강력한 소스맵 지원으로 LSP 연동 가능
2. 파일명 규칙 (스크립트 타입 자동 인식)
파일명 패턴 → 생성되는 스크립트 타입
*.server.lua → Script
*.client.lua → LocalScript
*.lua → ModuleScript
폴더/init.server.lua → 폴더를 Script로 승격
폴더/init.client.lua → 폴더를 LocalScript로 승격
폴더/init.lua → 폴더를 ModuleScript로 승격
폴더 구조 예시
src/
├── server/
│ ├── init.server.lua # ServerScriptService/Server (Script)
│ ├── DataStore.lua # ServerScriptService/Server/DataStore (ModuleScript)
│ └── PlayerManager.server.lua # ServerScriptService/Server/PlayerManager (Script)
├── client/
│ ├── init.client.lua # StarterPlayer/StarterPlayerScripts/Client (LocalScript)
│ └── UI/
│ └── MenuScript.client.lua # StarterPlayer/StarterPlayerScripts/Client/UI/MenuScript (LocalScript)
└── shared/
└── Utilities.lua # ReplicatedStorage/Shared/Utilities (ModuleScript)
3. 프로젝트 설정 파일
default.project.json 예시
{
"name": "MyGame",
"tree": {
"$className": "DataModel",
"ReplicatedStorage": {
"$className": "ReplicatedStorage",
"Shared": { "$path": "src/shared" }
},
"ServerScriptService": {
"$className": "ServerScriptService",
"Server": { "$path": "src/server" }
},
"StarterPlayer": {
"$className": "StarterPlayer",
"StarterPlayerScripts": {
"$className": "StarterPlayerScripts",
"Client": { "$path": "src/client" }
}
}
}
}
4. 기본 명령어
개발 중 실시간 동기화
# 기본 포트 (34872)로 서버 시작
rojo serve
# 커스텀 포트 지정
rojo serve --port 8080
# 프로젝트 파일 지정
rojo serve MyProject.project.json
빌드 (파일 → rbxl/rbxm 생성)
# Place 파일로 빌드
rojo build --output Game.rbxl
# Model 파일로 빌드
rojo build --output MyModel.rbxm MyModel.project.json
소스맵 생성 (LSP 지원)
# 소스맵 생성 (한 번)
rojo sourcemap --output sourcemap.json
# 파일 변경 감시하며 소스맵 자동 업데이트
rojo sourcemap --output sourcemap.json --watch
기존 게임을 파일로 분리하기
Rojo는 기존 rbxl/rbxlx 파일에서 스크립트를 자동으로 추출해주지 않습니다. 별도의 포팅 도구가 필요합니다.
1. 옵션 A: rbxlx-to-rojo (권장)
설치
# cargo로 설치 (Rust 필요)
cargo install rbxlx-to-rojo
# 또는 GitHub에서 바이너리 다운로드
# https://github.com/rojo-rbx/rbxlx-to-rojo/releases
사용법
# 1. Studio에서 File → Save to File As... → .rbxlx로 저장
# 2. rbxlx-to-rojo로 변환
rbxlx-to-rojo MyPlace.rbxlx output-folder/
# 3. output-folder에 default.project.json과 src/ 폴더 생성됨
2. 옵션 B: Rostar
설치
# Aftman 사용 시
aftman add tacheometry/rostar
aftman install
# 직접 다운로드
# https://github.com/Tacheometry/Rostar/releases
사용법
# rbxl/rbxlx를 폴더로 분해
rostar unpack ./MyPlace.rbxl
# 스크립트만 추출 (모델 제외)
rostar unpack ./MyPlace.rbxl --no-models
# 모델만 추출 (스크립트 제외)
rostar unpack ./MyPlace.rbxl --no-lua
# 폴더를 다시 rbxl로 빌드
rostar pack OutputPlace.rbxl
Place ID에서 직접 추출 (보안 주의)
# REMODEL_AUTH 환경변수 필요 (Roblox 쿠키)
export REMODEL_AUTH="your-roblox-cookie"
rostar unpack --place-id 123456789
⚠️ 보안 경고: REMODEL_AUTH
는 민감한 정보입니다. 개인 계정 쿠키를 팀과 공유하지 마세요.
혼합 워크플로우: Rojo + Script Sync 함께 사용하기
1. 워크플로우 개요
flowchart TD
A[기존 rbxlx 게임] --> B[포팅 도구로 분리]
B --> C[Rojo 프로젝트 생성]
C --> D[Git 버전 관리]
D --> E[Rojo serve로 전체 동기화]
E --> F[핵심 스크립트만 Script Sync]
F --> G[외부 IDE 편집]
G --> H[양방향 실시간 반영]
2. 단계별 구현
1단계: 기존 게임 포팅
# Studio에서 .rbxlx로 저장
# File → Save to File As... → MyGame.rbxlx
# rbxlx-to-rojo로 변환
rbxlx-to-rojo MyGame.rbxlx ./MyGameProject/
cd MyGameProject
2단계: Git 초기 설정
git init
git add .
git commit -m "feat: initial project from Studio conversion"
# .gitignore 설정
echo "*.rbxl
*.rbxm
*.rbxlx
*.rbxmx
sourcemap.json
**/.DS_Store
**/Thumbs.db" > .gitignore
3단계: Rojo로 전체 구조 관리
# 실시간 동기화 시작
rojo serve
# Studio에서 Rojo 플러그인 → Connect
4단계: 핵심 스크립트만 Script Sync 연결
- Studio에서 자주 수정하는 스크립트 선택
- 우클릭 → Start Sync
- 로컬 프로젝트의 해당 파일과 연결
5단계: 외부 IDE 설정
# VS Code에서 프로젝트 열기
code .
# Luau LSP 확장 설치
# - "Luau Language Server" by JohnnyMorganz
# 소스맵 생성 (LSP 지원)
rojo sourcemap --output sourcemap.json --watch
3. 권장 사용 패턴
Rojo 사용 케이스
- 프로젝트 전체 구조 관리
- CI/CD 빌드 파이프라인
- 팀 협업용 Git 기반 워크플로우
- 모델, 에셋 등 비스크립트 자원 관리
Script Sync 사용 케이스
- 빠른 스크립트 수정이 필요한 경우
- Team Create 세션 중 실시간 편집
- 실험적 코드 작성
- UI 스크립트 등 자주 바뀌는 코드
함께 사용할 때 주의사항
- 동일 스크립트에 Rojo + Script Sync 동시 적용 금지
- 충돌 정책을 명확히 설정 (팀 규칙 문서화)
- Git 커밋 전 동기화 상태 확인
VS Code & 개발 환경 설정
1. 필수 확장 프로그램
Luau Language Server
확장명: Luau Language Server
제작자: JohnnyMorganz
기능: 문법 하이라이팅, 타입 체킹, 자동 완성
StyLua (코드 포매터)
# StyLua 설치
cargo install stylua
# 또는 aftman으로
aftman add JohnnyMorganz/stylua
aftman install
stylua.toml 설정
indent_type = "Spaces"
indent_width = 4
end_of_line = "Unix"
quote_style = "AutoPreferDouble"
call_parentheses = "Always"
2. 프로젝트 설정 파일
.editorconfig (일관된 코딩 스타일)
root = true
[*]
end_of_line = lf
insert_final_newline = true
charset = utf-8
indent_style = space
indent_size = 4
[*.{lua,luau}]
indent_size = 4
trim_trailing_whitespace = true
.gitattributes (플랫폼 간 일관성)
*.lua text eol=lf
*.luau text eol=lf
*.json text eol=lf
*.md text eol=lf
3. VS Code 워크스페이스 설정
.vscode/settings.json
{
"luau-lsp.sourcemap.path": "sourcemap.json",
"files.associations": {
"*.lua": "luau",
"*.luau": "luau"
},
"editor.formatOnSave": true,
"[luau]": {
"editor.defaultFormatter": "JohnnyMorganz.stylua"
},
"git.ignoreLimitWarning": true
}
보안 가이드 & 운영 점검표
1. 접근 권한 관리
Windows 권한 설정
# 프로젝트 폴더 권한 최소화
icacls "C:\Projects\MyRobloxGame" /inheritance:r
icacls "C:\Projects\MyRobloxGame" /grant:r "DOMAIN\Developers:(OI)(CI)M"
icacls "C:\Projects\MyRobloxGame" /deny "Everyone:(OI)(CI)F"
macOS/Linux 권한 설정
# 소유권 설정
chown -R developer:devteam /projects/MyRobloxGame
# 권한 설정 (소유자: 읽기/쓰기/실행, 그룹: 읽기/실행, 기타: 접근 불가)
chmod -R 750 /projects/MyRobloxGame
# Git 디렉토리 보호
chmod -R 700 /projects/MyRobloxGame/.git
2. 민감정보 보호
환경변수 관리
# .env 파일 생성 (Git에서 제외)
echo "REMODEL_AUTH=your-cookie-here" > .env
echo ".env" >> .gitignore
# 환경변수 로드
export $(cat .env | xargs)
pre-commit 훅 설정
# pre-commit 설치
pip install pre-commit
# .pre-commit-config.yaml 생성
cat > .pre-commit-config.yaml << EOF
repos:
- repo: https://github.com/pre-commit/pre-commit-hooks
rev: v4.4.0
hooks:
- id: trailing-whitespace
- id: end-of-file-fixer
- id: check-secrets
- repo: https://github.com/Yelp/detect-secrets
rev: v1.4.0
hooks:
- id: detect-secrets
EOF
# 훅 설치
pre-commit install
3. 충돌 방지 정책
Script Sync 충돌 정책 가이드라인
팀 성격 | 권장 설정 | 이유 |
---|---|---|
Git 중심 팀 | Always keep local | 파일시스템이 진실의 원천 |
Studio 중심 팀 | Always keep Studio | Studio가 주 작업 환경 |
신중한 팀 | Do not resume (기본) | 수동 확인 후 결정 |
팀 규칙 예시
## Script Sync 사용 규칙
1. **동기화 대상**: 실험적 스크립트, 자주 변경되는 UI 코드만
2. **충돌 정책**: "Do not resume" (수동 해결)
3. **커밋 전 확인**: 동기화 상태 점검 필수
4. **코드 리뷰**: Script Sync 변경사항도 PR 필수
4. 네트워크 보안
허용된 저장소 위치
- ✅ 로컬 SSD (권장)
- ✅ 사내 보안 NAS (보안팀 승인 시)
- ❌ 네트워크 드라이브 (지연/락 문제)
- ❌ 클라우드 동기화 폴더 (OneDrive, Google Drive 등)
- ❌ 공용 네트워크 공유
5. 감사 및 로깅
Git 서버 보안 설정
# 브랜치 보호 규칙 (GitHub/GitLab)
- Require pull request reviews: 1명 이상
- Require status checks: CI/CD 통과 필수
- Restrict pushes: main 브랜치 직접 푸시 금지
- Require signed commits: GPG 서명 필수
로컬 감사 로그
# Git 액세스 로그 확인
git log --oneline --all --graph
# 최근 동기화 활동 확인 (Script Sync 사용 시)
# Studio의 Output에서 Script Sync 관련 메시지 모니터링
트러블슈팅 가이드
1. Script Sync 문제
베타 메뉴가 보이지 않음
원인: 점진적 롤아웃 중이거나 계정 권한 부족
해결책:
1. Studio 최신 버전 확인
2. 로블록스 계정 재로그인
3. 다른 계정으로 테스트
4. 개발자 포럼에서 베타 신청 확인
"File not found" 오류
원인: 파일 이동/삭제되었거나 네트워크 드라이브 문제
해결책:
1. 우클릭 → Show synced file location으로 경로 확인
2. 파일이 실제 존재하는지 확인
3. 네트워크 드라이브 사용 중단
4. 로컬 SSD로 파일 이동
동기화 충돌
원인: Studio와 파일이 동시에 수정됨
해결책:
1. Studio Settings에서 충돌 정책 확인
2. 수동 해결이 필요한 경우 백업 후 선택
3. Git에서 변경사항 비교
4. 팀원과 협의 후 결정
2. Rojo 문제
연결이 안 됨
# 포트 확인
netstat -an | grep 34872
# 방화벽 규칙 확인 (Windows)
netsh advfirewall firewall show rule name="Rojo"
# macOS 방화벽 확인
sudo pfctl -sr | grep 34872
스크립트가 반영되지 않음
원인: 파일명 규칙 위반 또는 프로젝트 설정 오류
해결책:
1. 파일명이 *.server.lua, *.client.lua, *.lua 형식인지 확인
2. default.project.json의 $path가 정확한지 확인
3. Studio에서 Rojo 플러그인 재연결
4. rojo serve 재시작
3. LSP/IntelliSense 문제
자동 완성이 안 됨
# 소스맵 생성 확인
ls -la sourcemap.json
# 소스맵 재생성
rojo sourcemap --output sourcemap.json
# VS Code 설정 확인
code .vscode/settings.json
CI/CD 파이프라인 구축
1. GitHub Actions 예시
.github/workflows/build.yml
name: Build and Test
on:
push:
branches: [ main, develop ]
pull_request:
branches: [ main ]
jobs:
test:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Install Aftman
uses: ok-nick/setup-aftman@v0.4.2
- name: Install Tools
run: aftman install
- name: Lint with StyLua
run: stylua --check src/
- name: Type check with Luau
run: luau-analyze src/
- name: Build place file
run: rojo build --output game.rbxl
- name: Upload artifact
uses: actions/upload-artifact@v3
with:
name: game-build
path: game.rbxl
deploy:
needs: test
runs-on: ubuntu-latest
if: github.ref == 'refs/heads/main'
steps:
- uses: actions/checkout@v4
- name: Deploy to Roblox
env:
ROBLOSECURITY: ${{ secrets.ROBLOSECURITY }}
run: |
# Open Cloud API를 사용한 자동 배포
# 실제 구현은 보안 정책에 따라 조정 필요
2. aftman.toml 도구 관리
[tools]
rojo = "rojo-rbx/rojo@7.4.0"
stylua = "JohnnyMorganz/StyLua@0.19.1"
selene = "Kampfkarren/selene@0.26.0"
rostar = "Tacheometry/Rostar@0.3.0"
도입 가이드 & SOP
1. 도입 단계별 계획
Phase 1: 기반 구축
- 도구 설치 및 환경 구성
- Rojo, Rostar, VS Code 확장 설치
- Git 저장소 생성 및 권한 설정
- 기존 프로젝트 포팅
- rbxlx-to-rojo로 파일 구조 변환
- Git 초기 커밋 및 브랜치 보호 설정
Phase 2: 워크플로우 정착
- Rojo 기반 개발 도입
- 팀원 교육 및 가이드 문서 작성
- 코드 리뷰 프로세스 구축
- Script Sync 선별 도입
- 핵심 스크립트만 선별하여 동기화
- 충돌 정책 및 사용 규칙 확립
Phase 3: 고도화
- CI/CD 파이프라인 구축
- 자동 빌드 및 테스트
- 배포 자동화
- 보안 및 감사 체계 구축
- 접근 권한 최소화
- 변경사항 추적 및 로깅
2. 역할별 가이드
개발팀장/리드
✅ 책임 사항
- 워크플로우 정책 수립
- 도구 선택 및 교육 계획
- 코드 리뷰 프로세스 설계
- 충돌 해결 에스컬레이션 처리
📋 체크리스트
□ 팀 개발 환경 표준화
□ Git 브랜치 전략 수립
□ Script Sync 사용 가이드라인 작성
□ 정기적 도구 업데이트 일정 수립
시니어 개발자
✅ 책임 사항
- 주니어 개발자 멘토링
- 복잡한 포팅 작업 수행
- CI/CD 파이프라인 구축
- 보안 정책 구현
📋 체크리스트
□ Rojo 프로젝트 구조 설계
□ 코드 품질 도구 설정
□ 자동화 스크립트 작성
□ 문제 해결 가이드 작성
주니어 개발자
✅ 책임 사항
- 기본 워크플로우 숙지
- 일상적 개발 작업 수행
- 문제 발생 시 적절한 에스컬레이션
- 문서 및 가이드 피드백
📋 체크리스트
□ VS Code 환경 설정 완료
□ Git 기본 명령어 숙지
□ Script Sync 사용법 학습
□ 코드 리뷰 참여 활성화
3. 표준 운영 절차 (SOP)
일일 개발 워크플로우
## 오전 루틴
1. Git pull로 최신 변경사항 동기화
2. Rojo serve 시작
3. Studio에서 Rojo 연결 확인
4. Script Sync 상태 점검
## 개발 중
1. 새 기능은 feature 브랜치에서 작업
2. 자주 변경되는 스크립트만 Script Sync 사용
3. 코드 변경 후 즉시 테스트
4. 의미 있는 단위로 커밋
## 마무리 루틴
1. Script Sync 동기화 상태 확인
2. 변경사항을 Git에 커밋
3. Pull Request 생성 및 리뷰 요청
4. Rojo 서버 종료
주간 점검 사항
## 매주 금요일
1. 미사용 Script Sync 연결 정리
2. Git 저장소 용량 점검
3. CI/CD 파이프라인 상태 확인
4. 보안 정책 준수 여부 검토
5. 도구 업데이트 필요성 검토
자주 묻는 질문 (FAQ)
Q1: Rojo가 rbxlx 안 스크립트를 자동으로 파일로 저장해 주나요?
A: 아니요. Rojo는 파일 → Studio 방향이 주 기능입니다. 기존 게임을 파일로 뽑으려면 rbxlx-to-rojo나 Rostar 같은 포팅 도구를 먼저 사용해야 합니다.
Q2: Script Sync로 전체 프로젝트를 한 번에 동기화할 수 있나요?
A: 현재는 개별 스크립트만 동기화 가능하고, 최대 64개 제한이 있습니다. 폴더 단위 동기화는 향후 업데이트에서 지원 예정입니다.
Q3: Rojo와 Script Sync를 함께 사용해도 되나요?
A: 네, 가능합니다. 하지만 동일한 스크립트에는 둘 다 적용하면 안 됩니다. Rojo로 전체 구조를 관리하고, Script Sync는 자주 수정하는 특정 스크립트만 연결하는 것을 권장합니다.
Q4: Team Create 환경에서도 Script Sync가 동작하나요?
A: 네, Team Create, Drafts, Local 환경 모두에서 동작합니다. 다만 여러 명이 동시에 같은 스크립트를 수정하면 충돌이 발생할 수 있으므로 팀 규칙을 정해야 합니다.
Q5: VS Code에서 Roblox API 자동완성이 안 됩니다.
A: Luau Language Server 확장을 설치하고, rojo sourcemap 명령으로 소스맵을 생성해야 합니다. 소스맵이 있어야 Roblox API 인텔리센스가 제대로 동작합니다.
Q6: 보안팀에서 외부 도구 사용을 제한하고 있습니다.
A: 이 문서의 보안 가이드를 보안팀에 제시하고, 각 도구의 공식 출처와 오픈소스 특성을 확인받으세요. 필요하다면 사내 도구 저장소에서 관리하는 방안도 고려할 수 있습니다.
참고 자료 및 출처
공식 문서
도구 저장소
커뮤니티
마무리
이 가이드를 통해 Studio Script Sync와 Rojo를 효과적으로 활용하여 현대적인 Roblox 개발 워크플로우를 구축할 수 있습니다.
핵심 포인트
- 작게 시작: 핵심 스크립트 몇 개부터 Script Sync 적용
- 점진적 확장: 팀이 적응되면 Rojo 기반 전체 워크플로우로 전환
- 보안 우선: 항상 보안 정책을 준수하며 도구 사용
- 지속적 개선: 팀 피드백을 바탕으로 워크플로우 개선
성공적인 도입을 위해 단계적 접근과 충분한 교육이 가장 중요합니다.
댓글