본문 바로가기
프로그램 (PHP,Python)

IDE로 개발하는 로블록스: Luau LSP + Rojo + Script Sync 양방향 통합

by 날으는물고기 2025. 9. 3.

IDE로 개발하는 로블록스: Luau LSP + Rojo + Script Sync 양방향 통합

728x90

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-rojoRostar 사용

워크플로우 권장

  • 전체 프로젝트 파일 관리Rojo 추천
  • 일부 스크립트만 외부 IDE 편집Script Sync 적합
  • 혼합 워크플로우: Rojo로 전체 구조 관리 + Script Sync로 핵심 스크립트 실시간 동기화

Studio Script Sync 상세 가이드

1. 활성화 방법

  1. 베타 기능 활성화
    • Studio → File → Beta Features → "Studio Script Sync [Early Preview]" 체크
  2. Studio 재시작 권장
  3. 베타 메뉴가 없다면?
    • 점진적 롤아웃 중일 수 있음
    • Studio 최신 버전 확인
    • 재로그인 시도

2. 사용법

기본 동기화 시작

  1. Explorer에서 스크립트 선택
  2. 우클릭 → Start Sync (또는 Sync to Disk)
  3. 로컬 폴더/파일 경로 지정 (.lua/.luau 확장자)
  4. 시작 시점에는 Studio 상태가 디스크를 덮어씀

다중 선택

  1. Shift/Ctrl 클릭으로 여러 스크립트 선택 가능 (최대 64개)
  2. 한 번에 동기화 설정 가능

관리 메뉴

  1. Resume Sync: 중단된 동기화 재개
  2. Stop Sync: 동기화 중단
  3. Show synced file location: 연결된 파일 위치 확인

3. 자동 재개 및 충돌 정책

Studio 재시작 시 동기화 상태를 자동으로 재개할 수 있으며, 파일과 Studio 내용이 다를 때의 처리 방식을 설정할 수 있습니다.

Studio Settings → Script Sync → "Resume conflicted sync on place open"

충돌 정책 옵션

  1. Always keep Studio (Studio 우선)
    • Studio의 버전이 항상 파일 시스템의 파일을 덮어씀
  2. Always keep local (로컬 우선)
    • 파일 시스템의 버전이 항상 Studio의 스크립트를 덮어씀
  3. Do not resume (수동 재개 - 기본값)
    • 충돌하는 스크립트는 오류 상태로 남김
    • 컨텍스트 메뉴의 "Resume Sync"로 수동 재개

4. 현재 제한사항

  • 폴더 단위 동기화 미지원 (향후 계획)
  • 동시 64개 스크립트 제한
  • 디스크 상태에서 동기화 시작 미지원 (향후 계획)
  • Team Create, Drafts, Local 모두 지원
  • 양방향 자동 동기화 (설정된 스크립트 한정)

5. 향후 로드맵

  1. 폴더 + 하위 스크립트 동기화 (수천 개 스크립트 지원)
  2. 디스크 상태에서 동기화 시작
  3. Source map/LSP 지원 (Luau LSP와 연동)

Rojo 상세 가이드

1. Rojo의 핵심 개념

Rojo는 "파일 시스템이 진실의 원천(Source of Truth)"이라는 철학으로 설계된 도구입니다.

300x250

주요 특징

  • 디스크 → 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 연결

  1. Studio에서 자주 수정하는 스크립트 선택
  2. 우클릭 → Start Sync
  3. 로컬 프로젝트의 해당 파일과 연결

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: 기반 구축

  1. 도구 설치 및 환경 구성
    • Rojo, Rostar, VS Code 확장 설치
    • Git 저장소 생성 및 권한 설정
  2. 기존 프로젝트 포팅
    • rbxlx-to-rojo로 파일 구조 변환
    • Git 초기 커밋 및 브랜치 보호 설정

Phase 2: 워크플로우 정착

  1. Rojo 기반 개발 도입
    • 팀원 교육 및 가이드 문서 작성
    • 코드 리뷰 프로세스 구축
  2. Script Sync 선별 도입
    • 핵심 스크립트만 선별하여 동기화
    • 충돌 정책 및 사용 규칙 확립

Phase 3: 고도화

  1. CI/CD 파이프라인 구축
    • 자동 빌드 및 테스트
    • 배포 자동화
  2. 보안 및 감사 체계 구축
    • 접근 권한 최소화
    • 변경사항 추적 및 로깅

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-rojoRostar 같은 포팅 도구를 먼저 사용해야 합니다.

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 SyncRojo를 효과적으로 활용하여 현대적인 Roblox 개발 워크플로우를 구축할 수 있습니다.

 

핵심 포인트

  • 작게 시작: 핵심 스크립트 몇 개부터 Script Sync 적용
  • 점진적 확장: 팀이 적응되면 Rojo 기반 전체 워크플로우로 전환
  • 보안 우선: 항상 보안 정책을 준수하며 도구 사용
  • 지속적 개선: 팀 피드백을 바탕으로 워크플로우 개선

 

성공적인 도입을 위해 단계적 접근충분한 교육이 가장 중요합니다.

728x90
그리드형(광고전용)

댓글